Hi Collin, On Sat, Sep 20, 2025 at 01:05:52PM -0700, Collin Funk wrote: > Alejandro Colomar <[email protected]> writes: > > > Hi Pádraig, > > > > On Sat, Sep 20, 2025 at 06:01:21PM +0100, Pádraig Brady wrote: > >> > > All of the man pages have links to the info docs for full > >> > > documentation. > >> > > >> > I know. However, many users don't enjoy the info docs. > >> > >> I my experience user don't enjoy the info _reader_, while the docs are > >> fine. > >> The full docs are on the web though and also linked from each man page. > > > > Yeah, the info online docs are much nicer. However, I (and others) > > don't enjoy going online for documentation, when offline documentation > > is available. > > I wish distributions installed the HTML docs to > /usr/share/doc/coreutils, or somewhere similar (and substitute package > name for other packages). The gnu.org site is down or takes ages to load > frequently nowadays.
While having offline HTML docs would be better than having online docs,
I really prefer something I can read comfortably from the terminal.
man(1) is really comfortable to find and use documentation.
And if I want to sit down and slowly read documentation --as opposed to
just consulting quickly a detail--, I can read it as PDF with pdfman(1),
which has essentially the same command line interface as man(1), but
opens the page on a PDF viewer.
> 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
> 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.
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).
HTML is not yet good, although groff maintainers are slowly improving
it.
And the build system of the Linux man-pages has a lot of lints to make
sure the man(7) source code is of the highest quality, apart from also
helping catch easy mistakes.
> I guess Markdown or reStructuredText would be more friendly to new
> contributors since many do not know Texinfo. However, I haven't seen
> good PDFs generated by them (though I concede that I very well could be
> unaware of examples).
I doubt Markdown or RST would be good for quality documentation.
Have a lovely night!
Alex
--
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).
signature.asc
Description: PGP signature
