3 ms·
I've written what could be the largest man page in the world, and possibly the only one that auto-numbers its sections down to three levels. I've written a bunc
by kazinator 3y ago
I've written what could be the largest man page in the world, and possibly the only one that auto-numbers its sections down to three levels. I've written a bunch of smaller ones over the years, and when contributing patches to GNU programs, I did a tiny bit of Info documenting.
I can say with confidence that the language used for Info documentation is vastly superior to the nroff/troff language. Man pages are not suitable for writing large manuals. It didn't stop me, but what I'm doing is not really scalable.
To get a decent HTML version I had to maintain my own fork of the man2html program (a particular one of them; there exist more than one, and all suck in different ways). That program is not enough; there is considerable custom post-processing done on the HTML output, to add a bettr table of contents and internal hyperlinks and such.
I wrote numerous macros for all the necessary markup needed in a manual. The macros have weird syntax. I wrote a lint tool to check the 95,000+ line document for errors in the uses of these macros, which frequently occur.
I also wrote a minor tool which I use as a filter in CGIT which renders man pages. (It's not used for that one; that's too large and complex.) E.g. if you look at this small page, you can see it in action:
https://www.kylheku.com/cgit/cppawk/tree/cppawk.1 https://www.kylheku.com/cgit/cppawk/tree/cppawk.1
you see it as if you were reading it in man, rather than the source code, which you can see in the "plain" view. The line numbers are wrong: they are calculated from the original source. So while the rendered page ends at 250-something lines, the line numbers keep going past 400. There is no way a CGIT filter can indicate that it has completely munged the input into a different form, which has fewer lines.
So the summary of man pages is: awful language + next to nonexistent tooling for publishing quality documents in multiple formats.
On the topic of troff, it's the GNU project which holds up that language: it provides a program called GNU Roff (groff). If you ever render a man page to PDF, that's likely what you will be using. So, in a way, GNU is committed to the troff language as much as to Info.
But GNU projects would be crazy to switch from Info to man; it's an unthinkable regression.
- xyzzy_plugh 3y ago> I've written what could be the largest man page in the world I had to go see for myself and it is indeed around six times larger than the bash man page. I endorse this nomination.
- osmsucks 3y agoWriting man pages by hand is indeed something that makes you lose the will to live. For anything beyond the trivial case I just write Markdown and convert it to a man page using pandoc.
- fanf2 3y agoThe -mdoc macros are much nicer to use than the -man macros. https://man.freebsd.org/cgi/man.cgi?query=mdoc https://man.freebsd.org/cgi/man.cgi?query=mdoc https://man.freebsd.org/cgi/man.cgi?query=groff_mdoc https://man.freebsd.org/cgi/man.cgi?query=groff_mdoc
- kazinator 3y agoHere is that forked man2html program: https://www.kylheku.com/cgit/man/ https://www.kylheku.com/cgit/man/ I applied quite a lot of changes to it. It basically contains a really hacky, spaghetti-coded nroff interpreter. Very nasty C code. In some of the patches, I actually implement missing features, like if/else conditions and loops. I got it to handle some of the complex macros in the TXR man page. I also put in a way where the man page can detect that it's being processed by that man2html program to do some things differently, that work better for HTML. If the M2 variable is present, then the nroff processor is confirmed to the man2html. There is a three-way if for targeting macros that annotate key strokes (used in the part of the manual that documents the REPL). In man2html, we generate inline HTML <kbd>...</kbd> tags. In nroff (man paging) we put square brackets, like [Ctrl-C], and for PDF output via groff, I used a complex copy pasta from the Groff manual to render boxes.