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

[Ingo Schwarze]

Hi Ralph,

Ralph Corderoy wrote on Thu, Nov 15, 2018 at 05:28:40PM +0000:
> Ingo Schwarze wrote:

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

> No, this is wrong.  tbl(1) doesn't show it needs piping to troff, and
> chem shouldn't show it needs piping to pic.

Is there are real-world use case where you would not pipe chem(1)
output to pic(1) or groff(1)?  I'm not aware of any, and in that
case, i wouldn't call it wrong.

Admittedly, showing a pipe in the SYNOPSIS is unusual, but even though
pipes are an extremely important concept in Unix and most utility
programs can be used in pipes, there are few that can *only* be used
in pipes, and i think that's why such synopses are rare.

If people dislike that proposal, there is of course nothing wrong
with leaving the SYNOPSIS untouched and saying the same in words.
The first paragraph of the description already somewhat tries to
achieve that, except that the wording "generates pic output" seems
confusing - doesn't it rather "generate *input* for pic"?  It's
also confusing to call it "a preprocessor like pic" when it is
actually a preprocessor *for* pic.  Maybe simply reword the first
paragraph similar to the following:

  chem produces chemical structure diagrams, in particular showing
  the bonds and rings common in organic chemistry.  Its output is
  intended to be piped into pic(1).

That's much shorter, yet clearer and more precise.  As shown, i'd
also get rid of the "today's version" because that goes without
saying.  Besides, it doesn't look like somebody will extend it do
show crystal lattices tomorrow, and if someone does, that will
necessitate changes to the documentation anyway.

> The NAME section is where it starts to go wrong
> in the version I have here.
> 
>     chem - groff preprocessor for producing chemical structure diagrams
> 
> I suggest
> 
>     chem - pic preprocessor for chemical-structure diagrams

That seems like an improvement to me.

Yours,
  Ingo