Re: groff performance and a critique of mandoc(1)'s PDF generation (was: Git snapshot tarballs, multiple-pass formatting, and pdfmom)

"G. Branden Robinson" <[email protected]> Sat, 8 Aug 2026 01:24:34 -0500
Newsgroups	gmane.comp.printing.groff.general
Message-ID	<20260808062434.xrjfek3cxjrgc7ri@illithid>
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 (application/pgp-signature, 833 B)