make groff -Tpdf the default pdf-engine for the ms format

[lodwicz]

As referenced before, and upon suggestion of @jgm , I'd like to point out that groff stopped maintaining/distributing pdfmark/pdfroff since 1.24.0, 2026-02-28, which is now maintained and distributed separately, to favor the still supported -Tpdf flag, which calls the Perl script gropdf for similar purposes.

Thus, it seems to me that the groff should be the default pdf-engine for the ms format, which along with man is the groff macro package supported by pandoc.

pdfroff requires ghostscript to postprocess groff's native postscript output, which has ensued a discussion on the pdfmark-groff repo, while gropdf requires Perl; so both have extra requirements besides groff itself to produce PDF. This and other issues may need to be discussed before making a decision.

An issue has already been created related to this discussion, as I did not know exactly how to handle my proposal.

[jgm]

I think this makes sense, but I'd like to get comments from others who use the ms backend. One drawback is that groff does not provide the option to relocate the table of contents to the beginning of the document, as pdfroff does. There may be other differences as well.

[lodwicz]

I think this makes sense, but I'd like to get comments from others who use the ms backend. One drawback is that groff does not provide the option to relocate the table of contents to the beginning of the document, as pdfroff does. There may be other differences as well.

I don't know if pdfroff is that reliable even on that respect: in many of a test the --toc option does indeed add a toc at the beginng of the document, but somehow adds an extra page (a cover page, I assume), it fumbles pagination, and does not report section headings text. the --pdf-engine-opt=--no-toc-relocation simply omits the toc.

On the other hand, the alternative groff -Tpdf does indeed keep the toc at the end of document, as does groff by design for all other output devices, but keeps the section headings text, and produces a smaller PDF.

[g-branden-robinson]

@jgm:

I think this makes sense, but I'd like to get comments from others who use the ms backend. One drawback is that groff does not provide the option to relocate the table of contents to the beginning of the document, as pdfroff does.

It actually does. gropdf(1) has supported a pdfswitchtopage macro since 2012.

gropdf(1):

     .pdfpagename name
     \X'pdf: pagename name'
            Assign the current page a name.  All documents bear two
            default names, ‘top’ and ‘bottom’.
...
     .pdfswitchtopage when name
     \X'pdf: switchtopage when name'
            Normally each new page is appended to the end of the
            document, this command allows following pages to be inserted
            at a ‘named’ position within the document (see pagename
            command above).  ‘when’ can be either ‘after’ or ‘before’.
            If it is omitted it defaults to ‘before’.  It should be used
            at the end of the page before you want the switch to happen.
            This allows pages such as a TOC to be moved to elsewhere in
            the document, but more esoteric uses are possible.

Some of the documentation is more recent vintage, but the foregoing quote is from groff 1.24.0 (released February 2026).

[jgm]

Nice! If you want to suggest a change to the template that uses this to move the TOC, we could integrate it.

[jgm]

I'm going to make the change.

[g-branden-robinson]

Hi guys,

You might be interested in some groff ms PDF features we're getting into shape for our 1.25 release, planned for early July.

Details are subject to change still. Deri James is responsible for most of the real work. My pass with the belt sander and furniture polish is in progress.

ms.pdf

[g-branden-robinson]

At 2026-05-15T01:36:02-0700, John MacFarlane wrote:

Nice! If you want to suggest a change to the template that uses this to move the TOC, we could integrate it.

If I understand you, none should be necessary. Deri's enhanced the `TC` macro to do this (relocate the TOC to follow the cover page) automatically if the output device is "pdf". I expect you'll get this for free with _groff_ 1.25.

…

-- Reply to this email directly or view it on GitHub: #11560 (reply in thread) You are receiving this because you commented. Message ID: ***@***.***>