Hi Ralph, Ralph Corderoy wrote on Thu, Nov 15, 2018 at 05:28:40PM +0000: > Ingo Schwarze wrote:
>> SYNOPSIS >> @g@chem [--] [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
