Hi John, At 2023-03-05T20:24:48+1100, John Gardner wrote: > Documentation cowboys think they're being cool when they cram all this > shit onto one logical synopsis line. > > Synopses for command-line programs (i.e., man pages allocated to > sections 1 or 8) are only a small part of the problem. When > documenting file formats, configuration files, schemata, and APIs > written in languages other than C/C++, the need to delineate alias > groups becomes much more prevalent.
Sure. When you have to describe languages where white space does not reliably separate lexical elements, (paired?) delimiters become necessary. A fortiori, Backus-Naur form exists for good reasons. But people don't need a command of it to profitably use the Unix command line. To pretend that they do--for the sake of "consistency", I suppose--I think trades away a good deal of readability and comprehensibility. Doug and Ingo pretty much talked me out of introducing a tbl(7) man page on similar grounds. http://lists.gnu.org/r/groff/2022-09/msg00011.html > On an unrelated note, I've recently found myself using the same > stylistic conventions used in man pages for denoting *literal* and > *placeholder* text in syntax descriptions (specifically those > containing expository characters like brackets and pipes, which users > aren't expected to type). The most recent > <https://github.com/Cutlery-Drawer/simh/blob/a8fd111bc28c5e5fd72e4514d60723f3169e4d49/doc/altairz80_doc.rst#id11> > case involves reStructuredText files which will be used to generate > man pages using Sphinx <https://www.sphinx-doc.org/>, so the font > choices are still somehow relevant… Yes indeed. > (Anywho, sorry for the long-winded rambling…) You're terse compared to some recent discussions. :) https://savannah.gnu.org/bugs/?63808 https://savannah.gnu.org/bugs/?63827 Regards, Branden
signature.asc
Description: PGP signature
