Hi Larry, At 2026-08-04T22:11:17-0400, Larry Kollar wrote: > John Gardner <[email protected]> wrote: > > 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. > > > > […] > > > > Pikchr is a project closely connected to SQLite, and it's used to > > render railroad diagrams of SQL clause syntax. It's quite efficient, > > 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 like Markdown for what it is, and I in no way consider it a “modern > replacement” for *roff. Each has its strengths—Markdown for web-based > documents, *roff for PDF and printed documents. Markdown is great for > rapid composition as well,
I agree that Markdown has its place in a documentary ecosystem. The problem, as is often the case, is less the technology itself, than the blinkered subculture of "insanely great" that grows up around it. Steve Jobs might have given a lot of engineers jobs, but he served as a major force of destruction upon engineering as a profession. Much analysis has been discouraged and punished in favor of marketing and "narrative". And Jobs's is only the most celebrated face of many tech "visionaries" with similar objectives and methods. We know that Markdown wasn't the be-all, end-all of documentation formats because it promptly sprouted divergent implementations to solve problems that Markdown itself could not. ReStructured Text and Asciidoc bolted a sort of semantic layer on top of it, trading away the approachability and simplicity of the original vision. John Gruber proved savvy by refusing to bless any descendant of his implementation. I suspect he appreciated that it was impossible for Markdown to be all things to all people despite the claims of a significant proportion of its userbase, which was already factionalized in 2014. Orzabal and Smith had warned us 29 years earlier that "everybody wants to rule the world". > and utilities like Pandoc or lowdown can transform it into *roff > -ms/-man/-mdoc for further refinement. Yes. Pandoc and lowdown both do the first two. Only lowdown attempts mdoc(7) as an output format. I wonder where its author gets all the semantic data from. I gather that he uses some extensions to Markdown after all? Definition lists and "extended attributes"? I'm not sure; this stuff is beyond the margins of my expertise. > I need to look into Pikchr, to see if it’s possible to create diagrams > that work for both it and pic(1). That could be a fun digression, now > that the kids are all in school and I won’t be on the hook to watch > them all day. I'm curious to hear more about this! > > 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), and even its HTML output could do > > with some sanding, so to speak. It's great at what it does: render > > manual pages for terminal display quickly and competently […] > > Very good point. Each formatter has its strengths: > > * Mandoc for rendering manpages on a terminal display[...] > * *roff for PDF or printed output (or rendering manpages on a > terminal) > * Markdown[...] for web-based output > > If you have to do all three, I would seriously suggest either Markdown > or XML[...] as a starting point. Transform to whichever *roff macro > package is most relevant for any non-web deliverables. I'd like to make groff better at producing (X)HTML, but this is a long-term project. > [1] If you have a *roff that supports -mdoc, why would you need > Mandoc? I know of exactly one real-world application where mandoc(1)'s speed makes a practical difference. The NixOS project generates a 9.8-megabyte man page. Everybody brings it up all the time and, since the document is unreadable at that length, instantly starts a full-text search, likely with less(1)'s `/` command. https://github.com/NixOS/nixpkgs/pull/514498 Sadly, despite my offers to develop an extension to grotty(1) and to the man(7)--and, because I value parity and completism, mdoc(7)--to exercise that extension, and to help them better engineer their tool that _generates_ this 300,000-line man page so that groff(1) can render it more quickly, I've received no feedback in almost 3 months. They reverted a groff 1.24.0 bug fix, switched to mandoc(1)[1], and stopped talking to me. Also see <https://github.com/NixOS/nixpkgs/pull/514839#issuecomment-4416082780>. Maybe I upset someone. Or there just isn't time to reconsider how a 9.8-megabyte man page interacts with the rest of the system. > You can display -mdoc, -man, -ms, -mm, -mom, etc on a terminal with > any *roff formatter (you might need Groff for -mdoc and -mom, not > sure). Certainly you need groff for mom(7). The original BSD implementation of mdoc(7) (even "version 3", the last revision) still exists--you can find it at the TUHS archive[2]--but I don't know of anyone that ships it. groff mdoc(7) has, for about 25 years (and like mom(7)), been written with GNU troff extensions in mind. You can't use it in compatibility mode (and don't need to, as no known mdoc(7) document requires that). I don't know that any formatters besides groff and mandoc(1) are used with mdoc(7) documents in the wild. Theoretically, Heirloom Doctools troff could do so, but I've seen/read no accounts thereof. Checking the source of the last of these, I see that they ship an implementation of mdoc(7) that is neither 4.4BSD's nor groff's! It seems Heirloom Doctools took 4.4BSD mdoc and added some AT&T- incompatible string names (using identifiers too long for AT&T troff). https://github.com/n-t-roff/heirloom-doctools/blob/2e9b0c67ed0f8efcf81c376e067d5256370dbc23/troff/troff.d/tmac.d/doc-common#L470 https://github.com/n-t-roff/heirloom-doctools/blob/2e9b0c67ed0f8efcf81c376e067d5256370dbc23/troff/troff.d/tmac.d/doc-ditroff.in#L98 https://github.com/n-t-roff/heirloom-doctools/blob/2e9b0c67ed0f8efcf81c376e067d5256370dbc23/troff/troff.d/tmac.d/doc-nroff#L95 https://github.com/n-t-roff/heirloom-doctools/blob/2e9b0c67ed0f8efcf81c376e067d5256370dbc23/troff/troff.d/tmac.d/doc-syms#L149 Regards, Branden [1] https://github.com/PerchunPak/nixos-dotfiles/commit/4cba63bf80a6b151e3686403734f7b8fab12d54c [2] https://www.tuhs.org/cgi-bin/utree.pl
signature.asc
Description: PGP signature
