Re: [9front] 9front man pages

[sl@stanleylieber.com]

some questions:

- why are the man pages the way they are
- which ones are new to 9front

some answers:

- one of the aims of the original authors was to keep the
man pages short, preferrably to one page, if possible.
- we've imported or added a lot of new stuff, many of the
man pages that appeared alongside that new stuff either
disregarded or never promised to adhere to the intentions
of plan 9's original authors.

some suggestions:

- i agree, evaluating one page at a time is the only way
forward.  read and edit for content, but only if necessary.
- i prefer the "table of flags" approach, myself, but have been
rebuffed on this point in the past.  there is no consensus, so it is
what it is.  i like ori's suggestion of creating a special
macro, but then that implies a massive effort to update
every single man page that features flags, and some mechanism
for enforcing its use in future (otherwise the effort would be
kind of useless), both of which seem unlikely to happen.
- "read the source" as an alternative to documenting flags
seems to obviate the need for man pages at all, which is
quite a bit more radical than editing the man pages that
already exist.  probably the source and the man pages should
be arranged to compliment each other, since neither can
really replace the other's intended function.
- uriel's suggestion way back when to dive into editing man
pages as a way of contributing when you don't know how to do
anything else was more geared towards spellcheck and grammar,
if i understood him correctly.  early in my plan 9 career i
stumbled over pretty much this same debate.  there was even
an argument to omit some debug flags i unearthed because if
we documented them then we would have to maintain them (or so the
argument went).

sl