Re: [groff] 01/16: pic(1): Relocate material.

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Fri, Oct 16, 2020 at 07:46:29PM -0400:

> commit 38947ee078763f635db162f2bd9d0501b5751377
> Author: G. Branden Robinson <g.branden.robinson@gmail.com>
> AuthorDate: Sat Oct 17 03:49:58 2020 +1100
> 
>     pic(1): Relocate material.
>     
>     Move "Bugs" section to precede "See Also" (really, it should be a
>     "Notes" or "Limitations" subsection of "Description"--a man page is not
>     a bug tracker--but that can be done in the future).

I strongly disagree.

For the last three decades, people have become used to the conventional
order of sections

  See also, Standards, History, Authors, Caveats, Bugs

I believe the reason is that these are shorter sections of an
appendix-like character, and "See also" traditionally introduces
this final part of the page.  Before it, there are the "Description"-like
sections, in particular: Description, Environment, Files, Exit
Status, Examples.

The BUGS section has traditionlly been the last section of all,
all the way back to Version 1 AT&T UNIX in 1971.

Ctrl-G is not an argument.  On the one hand, all these sections are
short in almost all pages, so it works even if "See also" is not
last.  On the other hand, /SEE or /^S is just as easy as Ctrl-G.

By the way, BUGS (at least nowadays) is rarely used as a bugtracker
but more often for design bugs that have become hard to fix because
they have become so entrenched in tradition that fixing them would
badly break compatibility.

The BUGS section in pic(1) is not of particularly impressive quality,
but that's an urelated point.

Yours,
  Ingo