Hi Collin, On Sat, Sep 20, 2025 at 04:02:28PM -0700, Collin Funk wrote: > > This is what I'd use in a command: > > > > Usage: foo [OPTIONS] FILE > > Interesting, I like the documentation in --help. Regardless, it is part > of the GNU Coding Standards [1]: > > The standard --help option should output brief documentation for how > to invoke the program, on standard output, then exit successfully. > Other options and arguments should be ignored once this is seen, and > the program should not perform its normal function. > > My reading is that the mention of "documentation" implies more than a > usage line. One can try to change the standards through the > bug-standa...@gnu.org, but I do not think you will have much luck in > this case.
Yup, I don't intend to change that. It's just my personal preference. > >> Writing all of that in groff would be a pain. More of my time would be > >> spent understanding the syntax than it would be focusing on the content. > >> Texinfo's syntax is much more readable and easy to remember. And the > >> HTML and PDF output look nice to read. > > > > I volunteer to maintain the man(7) source. To me it's quite > > comfortable. When you get used to it, it's not bad. The syntax is > > actually quite simple. You don't need to learn the full roff(7) > > language; the man(7) macros are quite small compared to it. mdoc(7) is > > much more complex than man(7), for comparison. > > mdoc is the format mandoc uses for the different BSD man pages, correct? Yes, the BSDs use mdoc(7) instead of man(7). Some Linux projects also use it (for example, nginx), but they're minoritary. > > The PDF output of man(7) also looks nice. Please have a look at the > > PDF book of the Linux manual pages: > > <https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/book/man-pages-6.15.pdf> > > > > Or you can read single-page PDFs by running pdfman(1), which some > > distros already package, or you can find pdfman(1) in the man-pages.git > > repo (it's a shell script). > > It looks good, I'm glad you like them. :) > but I still prefer the Texinfo PDFs. Makes sense. I don't intend to replace that. I think it would be nice to provide both. Some details might not be necessary in the manual pages, I agree, so they can be a short version of the info manual, but the current ones are too lacking, IMO, and having them tied to --help makes it hard to make them useful, since I also wouldn't want to expand --help much more than what it currently is, and also maintaining generated manual pages is less than ideal. Have a lovely day! Alex > > Collin > > [1] https://www.gnu.org/prep/standards/standards.html#g_t_002d_002dhelp -- <https://www.alejandro-colomar.es> Use port 80 (that is, <...:80/>).
signature.asc
Description: PGP signature
