Hi Ingo, At 2021-08-11T14:37:58+0200, Ingo Schwarze wrote: > G. Branden Robinson wrote on Wed, Aug 11, 2021 at 01:16:45AM +1000: > > but I reckon I should actually step up and try to improve one of the > > generator tools, like pod2man > > That would be a noble deed because pod2man(1) is a very useful tool > and produces almost decent man(7) code in most respects, though i > don't doubt it can be made even better. Also, helping Russ Allbery > would feel like giving something back to a venerable greybeard of > of outstanding merit.
Strongly agree. When I attended a DebConf for the first time in many years in Montréal in 2017, Russ was a person I sought out for a handshake. He's done great service on the Debian Technical Committee. (Nowadays, the notions of handshakes and in-person technical conferences seem quaint...) > > or docbook-to-man, before making this claim. > > I pity you if you try, but you would be a hero if you succeeded. I'm not sure I have that strong a lust for glory. :P > Feedback regarding mandoc -Tman is also welcome. I admit maintenance > done on it petered out a bit during the last few years. It appears > systems not supporting mdoc(7) and hence requiring distribution of > auto-generated man(7) pages in release tarballs alongside the original > mdoc(7) code become less and less common, so mandoc -Tman is seeing > less and less use, seemingly. I am sometimes surprised to see pre-generated mandoc-generated man(7) in manual trees. I don't recall seeing anything in the markup that alarmed me. Surely if I had, I would have rushed to this mailing list to thunder to you about correctness... ;-) > Indeed, in mandoc(1), man_validate.c function post_IP(), which checks > for content to automatically tag, does not tag the recommended .IP > content you describe above: > > /* > * Skip leading whitespace, dashes, backslashes, and font escapes, > * then create a tag if the first following byte is a letter. > * Priority is high unless whitespace is present. > */ > > And in fact, it also does not tag if that first character is > a character escape sequence, for example \(bu. Perfectly reasonable, if you want to take on the business of parsing the paragraph tags. > >> Sure, .TP/.IP lists cannot nest, or is there another problem with > >> them i'm missing? > > > Au contraire! You can nest them if you use .RS/.RE. My struggles > > with mixing .RS and .IP was in fact the issue that inflicted me on > > all of you[1][2]. > > > > $ ./build/test-groff -Tutf8 -man -rLL=72n EXPERIMENTS/nested-IP.man > [...] > > Technically, that's not nesting, but one .IP list, then a second, > indented .IP list, then another .IP list: Or even one "list" per IP call... > $ man -l -T tree nested-IP.man > [...] > IP (block) *10:2 > IP (head) 10:2 > \(bu (text) 10:5 > IP (body) 10:2 > Hire gnomes. (text) *11:1. > RS (block) *12:2 > RS (head) 12:2 > RS (body) 12:2 > IP (block) *13:2 > IP (head) 13:2 > \(dg (text) 13:5 > IP (body) 13:2 > Collect underpants. (text) *14:1. > IP (block) *15:2 > IP (head) 15:2 > \(dg (text) 15:5 > IP (body) 15:2 > ??? (text) *16:1. > IP (block) *17:2 > IP (head) 17:2 > \(dg (text) 17:5 > IP (body) 17:2 > Profit! (text) *18:1. > IP (block) *20:2 > IP (head) 20:2 > \(bu (text) 20:5 > IP (body) 20:2 > Retire to tropical paradise. (text) *21:1. Yup. I get you completely. I had Presentationitis from reading a lot of linux-man list traffic recently. So, you're right, what we really need here are begin- and end-list tags. The instant problem comes from IP, like all paragraph tags, being "spot" markup rather than "block" markup. (There are probably more correct terms for these.) I don't know if blockifying man(7) paragraph tags in worth the trouble or likely to get update, but people compose lists _all the time_ in man(7) pages and they so often turn out badly that I'm warming up to the idea of taking that on as my next big man(7) reform..._after_ I get MR implemented, a feature that is drumming its fingers on the table in my brain. Regards, Branden
signature.asc
Description: PGP signature
