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

[G. Branden Robinson]

At 2018-11-12T16:58:24+0000, Ralph Corderoy wrote:
> 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.

I don't dispute that.  But I don't think we should freeze the list of
acceptable section headings at those found in the 7th Edition corpus.
(Yes, that's a stronger statement than you may be making.  I'll get to
that. :) )

> > 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.

I haven't had the pleasure.  Much of what I have read about Plan
9/Inferno is seductive.

> > ...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.

I agree.  They are an instructive resource.

> > 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.

From what I've gathered about the processes of standards committees,
there's more subjectivity in the final result than even the most
hardened pedant might care for.

In any event, we're not starting from scratch here.  groff has 61 man
page source documents in it.  Some, like groff(7) and groff_diff(7) are
lengthy.

I am trying to bend the arc of this body of work towards better and more
consistent style by increments.  In part because it suits my time and
availability better to break the work up into chunks, but also because
that is better use of a revision control system, and not insignificantly
because if I presented the groff team with a ground-up total rewrite of
all 61 pages as one huge commit, people would despair of reviewing it,
and feel like they'd been handed a fait accompli.  That wouldn't be
nice.

> > 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?

This is the direction I was trying to push you in.  We're down to
judgment calls, and the reason my emails and (sometimes) commit messages
are lengthy is because I am presenting the reasons for the judgments I
make.

> > 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.

For a complex command, I'd use .SS macros to organize the Description
after an initial overflow.  Depending on how much complexity the option
interface in particular presented, I'd discuss them inline if doing so
were "wieldy", and move them to the commonly-seen and -accepted Options
if they required presentation in a table or list.

However, .SS is nowhere used in the 7th Edition man page corpus.  Does
this fact militate against its use?

> > > 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.  :-)

On the other hand, options are not the only things we put in lists.

Let me ask you this: do you propose that we eliminate Options sections
from all groff man pages?  If not, I have ideas about how to make
concrete the idea of "wieldy" option discussion I mentioned above.

-- 
Regards,
Branden

signature.asc
Description: PGP signature