Re: [groff] 01/04: grn(1): Make options discussion a section.

[Ralph Corderoy]

Hi Branden,

> The Version 7 Unix pages are a wonderful thing but they are not the
> final word on current or best practice.

They show that OPTIONS was not in 7th Ed.'s section 1, despite some
commands, like ls(1) having many options.

> Implement the system documented there and you'll be rooted in
> seconds[1], among other problems.

I wasn't suggesting we wind back the world to 7th Ed.  Tenth was much
nicer.

> ...in favor of elevating one from 1979 as the final word.

Again, I wasn't suggesting they were the final word.  They were
hand-written, not machine produced, by a small set of people with
overarching editing.  That gives them value as a well-considered
example.

> > Not a good example since they're a standards committee and put
> > standardisation that above a good man page, e.g. `OPTIONS None.
> > OPERANDS None.  STDIN Not used.  INPUT FILES None...' for true(1p).
>
> I regard the Austin Group as worthy of consideration as the Bell Labs
> CSRC.  Why shouldn't I?

Because the Labs employed subjective decisions, unlike a standards
committee that decides to stick to the letter.  BL appreciated style.
Whether Strunk and White's, or Kernighan and Plauger's.  I still notice
this in all the little tweaks Rob Pike makes to Go's documentation.

> > I also agree with Igno that there's no need to split the option
> > description off from the preceding text that then becomes too short
> > to deserve its own DESCRIPTION section.  Something else the POSIX
> > committee doesn't care about.
>
> Quantify "too short".  Where is the _standard_ that defines this?

There doesn't need to be one.  It can be it's obvious it's too short, or
sometimes it's borderline.  Would you define the standard in lines,
words, or runes?

> It is best to describe what the command is up to, and let that
> discussion motivate the existence of options.  By adhering to a rule
> of one terse paragraph

You keep stating positions to argue against that are further away from
my position.  I'm not advocating a single paragraph.  I favour
terseness, but not to excess.  For a complex command the DESCRIPTION is
a high overview to put the options in context and allow further detail
to be sought.

> > The list of options is typically near the start of the man page and
> > stands out by itself.
>
> ...depending on how it's typeset.

As a list.  That's what makes it stand out.  :-)

-- 
Cheers, Ralph.
https://plus.google.com/+RalphCorderoy