Re: [9front] 9front man pages

["Lyndon Nerenberg (VE7TFX/VE6BBM)" <lyndon@orthanc.ca>]

sirjofri writes:

> I also like the idea of having an additional program that parses the source f
> ile for everything in between ARGBEGIN/ARGEND, combined with comments for des
> cription. Flags without comment could be omitted to have the option of omitti
> ng debug functionality, and it's easy enough to document with that. On the ot
> her hand, that puts part of the documentation into the source code, which is 
> very much different from how man pages work.

The trouble with this approach is it only works with the languages
it knows about.

What if I write something in Fortran?  Or Go?  Or whatever other
language I port across.  Whatever this is, it needs to be universal,
and I don't see a practical solution.

I don't really believe the argument that people will read only
the flags documentation and ignore the manpage.  Someone that lazy
is likely not reading the manpage at all.  And anyway, that argument
is purely speculation.

Whenever you read technical documentation, those sorts of enumerated
lists are almost always called out separately.  There are several
reasons for that, readablilty being paramount.

While I'm a firm believer in precedent, it's shouldn't be cast in
granite.  I firmly believe documenting command flags inline was a
mistake.  We should be able to admit that and fix it.

--lyndon