[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Ingo Schwarze
Subject: Re: [groff] 01/03: eqn(1): Relocate material.
Date: Sat, 17 Oct 2020 13:30:51 +0200
User-agent: Mutt/1.12.2 (2019-09-21)


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

> commit b66291f382316f658e0f35c713faa0d5e26b8665
> Author: G. Branden Robinson <>
> 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

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.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]