Alejandro Colomar <[email protected]> writes:
>> That said, I have seen complaints about the Coreutils man pages being
>> "incomplete". However, it is grown on me personally. I use the man pages
>> as a quick reference when I want to find an option or understand what it
>> does. And the info page for examples and/or commentary that is too long
>> to reasonably fit in --help.
>
> I personally would remove documentation from help, and only print a
> usage line. The user is welcome to read the manual page for consulting
> the documentation.
>
> 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
[email protected], but I do not think you will have much luck in
this case.
>> 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?
> 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, but I still prefer the Texinfo PDFs.
Collin
[1] https://www.gnu.org/prep/standards/standards.html#g_t_002d_002dhelp
