Re: [groff] 01/03: eqn(1): Relocate material.

[Ingo Schwarze]

Hi,

G. Branden Robinson wrote on Sat, Oct 17, 2020 at 05:24:13AM -0400:

> commit b66291f382316f658e0f35c713faa0d5e26b8665
> Author: G. Branden Robinson <g.branden.robinson@gmail.com>
> AuthorDate: Sat Oct 17 17:41:01 2020 +1100
> 
>     eqn(1): Relocate material.
>     Place "Options" after "Usage" (to be coalesced into "Description".

I think this particular change is a change for the worse.

Basically, the GNU eqn(1) page is a page that serves both as the
documenntation of the program eqn(1) and of the language eqn(7).
Combining two pages with distinct purposes in this way is fine
unless both are very long.  Many pages do that that document both a
program and a language or configuration file format that program
serves.

But in such cases, the "Description" section should really follow
the logical order:

 1. document the program
 2. document the language

Inside the first part, the documentation of the program, it should
follow the conventional order used in all section 1 pages:

 1.1. a short description of the purpose and default behaviour
 1.2. the list of option descriptions
 1.3. longer descriptions of more complicated program features;
      not needed for eqn(1)

By contrast, first documenting part of the program eqn(1), then
jumping to the language eqn(7), then jumping back to the program eqn(1)
is not cool but highly confusing.

Also, moving options down in the manual page to appear after very
long sections of other text is completely unexpected and runs counter
to what manual pages usually do.

Yours,
  Ingo