Re: [groff] 01/01: chem(1): Condense option documentation.

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Wed, Nov 14, 2018 at 01:35:54PM -0500:

> commit 38dfd0b568376d371286af261235c44bda7b5abc
> Author: G. Branden Robinson <address@hidden>
> Date:   Wed Nov 14 13:27:27 2018 -0500
> 
>     chem(1): Condense option documentation.
>     
>       * contrib/chem/chem.1.man: Demote option documentation from a
>       section to a sentence (early) in the Description section since
>       the supported option interface is so minimal, per discussion
>       with Ingo Schwarze and Ralph Corderoy.

Thanks, yes, i think even though the new text is relatively unusual
and does not employ the conventional formatting, i think that's OK
because these options are so unimportant, so i think what you did
is an improvement.

Briefly looking at the page, i noticed huge amounts of low-hanging
fruit; not sending a patch because i never used chem(1), but maybe
someone else wants to take a shot to improve this page.

 * References to other manual pages (like pic(1), tbl(1), etc.)
   should be formatted as cross references.

 * The paragraph "The program @address@hidden originates..." is almost
   irrelevant to the user and hence misplaced, much too high up.
   The information ought to be demoted to the FILES section (where
   part of it is probably already present, so it can also be
   shortened).

 * The sentence "In a style reminiscent" says nothing and should
   be deleted without any replacement.

 * The next paragraph about .cstart and .cend states exactly
   the same point twice and can be made more concise.

 * The end of the paragraph "As an example" can be made more
   concise and less trivial like this: "... prints the structure
   diagram for ethane."  But as it is an example, it should
   also be demoted to the EXAMPLES section.

 * Talk about groffer(1) should be deleted or at least moved to
   EXAMPLES - this page is about chem(1), not about groffer(1).

 * The line
     @address@hidden [file ...] | groff -p ...
   is critical to understand how to use chem(1), so it is way to
   low down.  It should probably be deleted, and instead the SYNOPSIS
   should look like this:

     SYNOPSIS
       @address@hidden [--] [filespec ...] | groff -p ...

   That makes the usage clear without long-winded verbiage.

And so on and so forth, i stopped reading at "THE LANGUAGE".

Yours,
  Ingo