Hi Larry, Larry Kollar wrote on Wed, Nov 28, 2018 at 11:42:00PM -0500: > Ingo Schwarze <schwa...@usta.de> wrote: >> Branden wrote:
>>> * My semantic macro package extending groff_man(7), if I can get it >>> where I'm happy with it and folks on the list don't bleed from the >>> eyes about it. >> That would be a HUGE step backwards, making the groff manual pages >> even less portable (they are already among the 20-30 least portable >> manual page sets in those about ten thousand free software projects >> that i looked at, and the amount of portability problems in groff >> manual pages is vastly larger than in most other of those 20-30 >> projects). You surely want to make that worse, right? > Being a fan of semantic markup myself, I'd normally agree. > On the other hand, wouldn't the groff manpages always come > with a groff formatter? Don't FreeBSD manual pages always come with FreeBSD and Linux manual pages always with Linux? No, they dont't, i read more FreeBSD, NetBSD, and Linux manual pages on OpenBSD than on any other system. Also, somebody might want to peek at the groff manual pages in the source tree before compiling groff. But more importantly, how does it help to have groff installed, even installed system-wide? On almost all operating systems, you can install groff, but on several, it won't be the default manual page formatter. Examples: FreeBSD, OpenBSD, NetBSD, illimos, Alpine Linux, Void Linux, maybe some versions of Solaris or other commercial Unix systems, ... So, you installed the groff programs, but you cannot install the manual pages because the system's manual page formatter would choke on them. What do you do? Hack into the groff build system to format the manual pages at build time, then install the preformatted versions? That's what we did in the OpenBSD port of groff until a month ago. Then, i implemented about a dozen new features in mandoc(1) just for groff, just for being able to handle the groff manual pages - and that was *after* years of work done to cope with low-portability manual pages in other software packages. > Groff is the *de facto* standard for *roff these days; No doubt about that; i'd say since approximately 1994, so for well over twenty years. > I for one wouldn't mind semantic extensions to groff_man(7). It would > allow for the kind of flexibility HTML offers now, except for an equivalent > to tidy(1) to corral presentational markup. It might also go a long way > toward eliminating a lot of the portability issues -- who's to say > alternate *roff developers won't adapt the extended macros for their > own packages? Well, the largest ecosystem with non-roff as the manual page formatter is FreeBSD (plus the smaller cousins OpenBSD, NetBSD, illumos, Alpine Linux, ...) so i would be forced to implement them in mandoc. Inconvenient because it basically means bowing to NIH syndrome and because there is more important fish to fry, but likely to happen anyway. I already implemented man-ext and several other GNU extensions in the past, even many of those that i consider bad ideas. The second largest ecosystem are commercial Unix distros. I'd be surprised if those would move at all, they typically don't do anything about anything. MacOS is in the same boat - even though significant parts are actually FreeBSD, it is typically static and lagging behind for extremely long times - as in, many years. Carsten Kunze might implement them in Heirloom, if he finds time and is interested; i don't know. But Heirloom is not commonly used as a manual page formatter as far as i'm aware. > There are three things I have tried (and failed) multiple times to > wrap my head around: TeX, emacs, and mdoc. Stuff like > > .Op Fl c Ar class Oo Fl p Ar end-class Oc Oo Fl s Ar subclass Oc Not using line breaks is an easy way to make any code less readable, one familiar technique in Perl golfing and code obfuscation contests. The normal way to write that is .Oo .Fl c Ar class .Op Fl p Ar end-class .Op Fl s Ar subclass .Oc Looks quite readable to me - "optional flag s with argument subclass, ..." If you want, you can even use indentation, though BSD traditionally doesn't do that: .Oo . Fl c Ar class . Op Fl p Ar end-class . Op Fl s Ar subclass .Oc How is that harder than: .RB [ \-c .I class .RB [ \-p .IR end-class ] .RB [ \-s .IR subclass ]] > OTOH, I certainly wouldn't object if someone rewrote all the Groff man > pages in mdoc. It might be a good warmup to whacking down that > Texinfo beast. ;-) Seems less urgent since on most systems, access to even low-portability manual pages is easier than to texinfo that most people will completely overlook (which is what started this subthread). Less urgent in particular now since mandoc supports the existing groff manuals, so they now also work on BSD systems out of the box. But sure, if people want it, i can do that... It would certainly make many things better: more uniform and semantic markup, better HTML, semantic search support for free (both on systems having mandoc and on online on websites), and so on... By the way, a texinfo2mdoc(1) program exists - even though the output will require lots of manual postprocessing. The toolchain to get started with a man->mdoc conversion would probably be doclifter(1), then docbook2mdoc(1) on the result, which is even more fragile and will likely require at least as much manual postprocessing. Yours, Ingo
