Re: groff performance and a critique of mandoc(1)'s PDF generation

"G. Branden Robinson" <[email protected]> Sun, 9 Aug 2026 03:35:57 -0500
Newsgroups	gmane.comp.printing.groff.general
Message-ID	<20260809083557.6zay5w5hwk5ihbsd@illithid>
Hi Ingo,

Just some brief comments since you solicited suggestions on wording of
mandoc(1)'s own man pages.

At 2026-08-07T18:08:29+0200, Ingo Schwarze wrote:
> 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.

You might recast this as:

  ...and man, the predominant language of Linux and historical Unix
  manuals.

That is, if the word "Linux" is utterable in OpenBSD man pages.  ;-)

And I'll note for any GNU police happening past that GNU _has_ no
preferred macro language for man pages, because _respectable_ GNU users
stay in Emacs and read _only_ Info documentation.

https://www.gnu.org/prep/standards/html_node/Man-Pages.html

> 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.

I would recast to avoid passive voice.  _Who_ discourages use of roff(7)
requests in mdoc documents?

Admittedly, groff_man{,_style}(7) uses the phrase "is discouraged" too,
and I'll get rid of that.  We don't employ it in the
"Portability" subsection, but rather here.

   Deprecated features
     Use of the following in man pages for public distribution is
     discouraged.

     .AT [system [release]]

The only other use of the verb "discourage" occurs in
groff_man_style(7)'s "Notes" section, a sort of FAQ.

       Unicode defines an ellipsis code point, and some fonts have an
       ellipsis glyph, which some man pages have accessed non‐portably
       with the font‐dependent \N escape sequence.  We discourage their
       use; on terminals, they may crowd the dots into a half‐width
       character cell, and do not render at all if the output device
       lacks the glyph.  In synopses, missing ellipses can mislead the
       reader.  Dots and space are universally supported.

> 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.

I'd recast as follows.

  The man(7) language was used universally for Unix man pages up to
  1989; it remains popular in Linux.  When composing BSD manual pages,
  use mdoc(7) instead; it has more extensive semantic markup features.

> In roff(7), i fail to see anything that could be considered
> "arrogant".

I skimmed over mandoc_roff(7) on my system and saw little to remark
upon.  I look forward to seeing the new requests I've added since groff
1.22.4 show up.  ;-)

stringup
stringdown

msoquiet
soquiet

hydefault

pstream
pline
phw
pcomposite
pchar
pcolor
pwh (renamed from `ptr`)

> 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.

I'm curious?  Who needs PostScript or PDF in a hurry but doesn't need it
to be all that good?

Wouldn't such people be better off using an external converter to
transform mandoc(1)'s high-quality HTML output to a PDF?

That shouldn't take the _user_ any longer; the effort has already been
expended by the people who maintain such converters.

> > 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.

Maybe I can coax John into helping me improve groff's (X)HTML output. :)

Regards,
Branden
signature.asc (application/pgp-signature, 833 B)