Re: Mandoc for oil

[Ingo Schwarze <schwarze@usta.de>]

Hi Matthew,

Matthew Singletary wrote on Sat, Jun 15, 2019 at 10:39:55PM -0400:

> I've got a first attempt at an updated man page for osh (the pull
> request is https://github.com/oilshell/oil/pull/337).

I tried to find your draft of the manual page in there, but failed
to find any substantial body of text - small surprise though, i
consider the Github user interface totally unusable, so probably,
i merely didn't find your text.

> Any feedback would be appreciated.

If you desire feedback on your draft, please simply post it here.

> But while I can start copying from the markdown notes that are being
> maintained by the main author, what's a normal/reasonable workflow for
> updating man pages?

Different projects have different policies for that.

Personally, i recommend treating them exactly the same way as code:
Commit changes to the -current branch whenever you find gaps or
errors, then when a release comes, the newest version of the code
and documentation will automatically gets released together.  KISS.

> For example, are there any recommended ways to generate/keep up to date
> command line flags based upon source code,

Absolutely not.  It is utterly impossible to automatically generate
documentation from source code, and any attempt at doing so is certain
to result in documentation of abysmal quality.  Not just for manual
pages, for any kind of documentation.

> or is the convention to handle those by hand?

Yes, absolutely.  When the code is changed, the developer changing
the code should ask themselves: is this change visible to the end user,
or is it purely internal?  If it changes the user interface, they should
figure out how the documentation needs to be updated.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv