Hi John, John Gardner wrote on Sat, Aug 01, 2026 at 03:05:41PM +1000: > At 2026-07-26T16:40:39-0500, G. Branden Robinson wrote:
>> mandoc(1), unsurprisingly, doesn't typeset pic(1) diagrams (p. 117). >> Unfortunately because it also doesn't set a man(7) `EX`/`EE` display in a >> monospaced typeface, the fallback ASCII art is mostly unintelligible. > I'm surprised mandoc(1) hasn't adopted Pikchr > <https://pikchr.org/home/doc/trunk/doc/differences.md> as a[n] > alternative to pic(1). The main resason is that pic(1) usage in manual pages is quite rare, and the priority of mandoc(1) has always been to catch up with formatting of existing real-world manual pages, rather than introducing new features visible to documentation authors, so it never really came up so far. That said, i just added this entry to the TODO file, below "missing misc features": - John Gardner suggests looking at pikchr Sat, 1 Aug 2026 15:05:41 +1000 https://pikchr.org/home/doc/trunk/doc/differences.md I chose the "misc" category because i did not yet investigate whether this is relevant only to -T html output, what the relationship to the -T markdown output mode would be, and what to do about other output modes. [...] > Pikchr is a project closely connected to SQLite, and it's used to render > railroad diagrams of SQL clause syntax. It's quite efficient, Yes. SQLite's is a good (and rare) example of high-quality documentation that cannot easily be handled by the traditional roff(1)+man(1) toolchain, and i dimly remember that Kristaps has invented some workarounds for the OpenBSD ports tree for the issues the combination of "good and important documentation" with "unusual formatting methods" causes. > though their disparaging remarks about Troff being a historically > significant but now obsolete markup language low-key pisses me off, > especially knowing they implicitly mean Markdown is Troff's "modern" > replacement. I sympathize with your feeling expressed here, but it wouldn't necessarily exclude using such parts of their work as are valuable and can be integrated in a reasoable way. > But hey, a tone of similarly-undeserved arrogance can be felt reading > mandoc(1)'s description of the Troff typesetting system or the Roff > language in general (it's more subdued, but you damn well know they wish > request-free mdoc(7) was the only macro package the world uses and cares > about). It seems quite possible to me that some stuff needs toning down further, though i do not immediately find it, https://mandoc.bsd.lv/index.html does not seem to imply any such undertones: mandoc is a suite of tools compiling mdoc, the roff macro language of choice for BSD manual pages, and man, the predominant historical language for UNIX manuals. Then, the mdoc(7) manual says: DESCRIPTION [...] However, using roff(7) requests in mdoc documents is discouraged; mandoc(1) supports some of them merely for backward compatibility. The man(7) manual is admittedly giving quite explicit advice: DESCRIPTION The man language was the standard formatting language for AT&T UNIX manual pages from 1979 to 1989. Do not use it to write new manual pages: it is a purely presentational language and lacks support for semantic markup. Use the mdoc(7) language, instead. In roff(7), i fail to see anything that could be considered "arrogant". So where exactly do you think the tone could be improved? Ideas would be appreciated. > Anyway, Mandoc isn't a typesetting system, and it makes no allusions to > being one. I'm not even sure why they bothered with PDF output (because it > really *is* shit), Originally, Kristaps being a playchild, then me neither caring enough to invest into the work nor being willing to rip it out entirely, in particular given that on rare occasions, a few people do speeak up to say that sometimes, it does come up handy for them when they are in a hurry and have no real typesetting needs. > and even its HTML output could do with some sanding, so to speak. You massively helped with that already, thank you very much once more. Then again, the only TODO entries related to -T html that have your name in them are related to "flexbox for .Bl -tag" (which feels relatively difficult, but maybe i'm just too squeamish) and using "white-space: nowrap" for .Aq Mt (which feels relatively minor). So pointing out specific aspects that still suck, in particular low-hanging fruit, may still be helpful. Yours, Ingo
