Re: pdfroff in groff 1.23.0.rc3 changes compared to 1.22.4

[G. Branden Robinson]

Hi Michał,

At 2023-04-05T08:25:28+0000, Michał Kruszewski wrote:
> I have encountered few problems.
> 
> 1. .pdfswitchtopage puts ToC always as the first page, and I would
> like to put it after the cover page.

For this, you need the "pdfpagename" macro.

Here's another diff to doc/ms.ms, for illustration.

diff --git a/doc/ms.ms b/doc/ms.ms
index 6526b1a04..db042d526 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -14,6 +14,8 @@
 .\" along with this program. If not, see <http://www.gnu.org/licenses/>.
 .
 .\" Handle font requests with families, for instance in tbl(1) tables.
+.RP
+.if '\*[.T]'pdf' .pdfpagename COVER
 .if n \{\
 .  ftr CR B \" for a visible distinction from roman
 .  ftr CB B
@@ -41,6 +43,12 @@
 .EF ''''
 .OH 'Using \f[I]groff\f[] with the \f[I]ms\f[] macros''%'
 .OF ''''
+.if '\*[.T]'pdf' \{\
+.  pdfinfo /Title Using groff with the ms Macro Package
+.  pdfinfo /Author Larry Kollar, G. Branden Robinson
+.  pdfinfo /Subject composing documents in 2023 with a 1975 macro package
+.  pdfinfo /Keywords groff ms troff nroff
+.\}
 .TL
 Using
 .BI groff
@@ -4429,6 +4437,7 @@ the curious may consult its source in the file
 .I ms.ms
 to see how its formatting was achieved.
 .\" ------------------------
+.if '\*[.T]'pdf' .pdfswitchtopage after COVER
 .TC
 .
 .

> 2. There is a page number shift between the actual page number and the
> one I need to input into the evince to jump to particular heading.

This one I haven't figured out yet.  There is a PDF feature to give
pages alternate numbers, but I don't know what it is nor whether we
expose access to it via our 'pdf' output device's macros.  I looked over
the implementation, tmac/pdf.tmac, and didn't see anything obvious.

So this may be a missing groff feature, or I may need to ask one of our
resident PDF wizards, like Deri James, for help.

> 3. What is the preferred way to automatically add .XS and .XE?

New to groff 1.23.0 are ms XN and XH macros, modeled on those in Keith
Marshall's spdf.tmac (and also implemented by him).  So they're full
groff ms features now.  For usage, see page 22 of the attached document.

> 4. In doc/groff.pdf I am able to quickly jump to the heading by
> clicking on it in the ToC. How is this achieved?

With PDF bookmarks and hotspots.  Unfortunately these features aren't
completely integrated with groff ms yet, for technical reasons.[1]

Right now Peter Schaffter's "mom" is the only groff macro package with
first-class support for PDF hyperlinking.  groff man(7) and mdoc(7) have
what you might call second-class support for them.[2]  ms, mm, and "me"
have none.  I'd like to address these gaps for groff 1.24.

> I can see that doc/groff.pdf has perfectly formatted ToC, this is
> exactly what I would like to achieve.

That's good news for the Texinfo folks, then--doc/groff.pdf was produced
with Texinfo, not groff.

> However, trying to figure out how it was achieved is not so easy as it
> looks like there is quite a lot *nix wizardry behind it.

A whole different formatting system, including TeX wizardry.

Meanwhile, here's a patch to doc/doc.am I'm using to generate
doc/ms.pdf.

diff --git a/doc/doc.am b/doc/doc.am
index 8ef9aabf7..4cf1b7e7c 100644
--- a/doc/doc.am
+++ b/doc/doc.am
@@ -349,6 +349,10 @@ doc/ms.ps: $(doc_srcdir)/ms.ms eqn tbl
        $(GROFF_V)$(MKDIR_P) `dirname $@` \
        && $(DOC_GROFF) -et -Tps -ms $(doc_srcdir)/ms.ms >$@

+doc/ms.pdf: $(doc_srcdir)/ms.ms eqn tbl
+       $(GROFF_V)$(MKDIR_P) `dirname $@` \
+       && $(DOC_GROFF) -et -ms -Tpdf -P-e $(doc_srcdir)/ms.ms >$@
+
 doc/pic.ps: $(doc_srcdir)/pic.ms eqn pic tbl
        $(GROFF_V)$(MKDIR_P) `dirname $@` \
        && $(DOC_GROFF) -pet -Tps -ms $(doc_srcdir)/pic.ms >$@

I'm attaching updated versions of ms.ms and ms.pdf for your perusal.[3]

Regards,
Branden

[1] ...the notorious diversion sanitization feature, and adjacent design
    problems.

    https://savannah.gnu.org/bugs/?63074
    https://savannah.gnu.org/bugs/?62787
    https://savannah.gnu.org/bugs/?62264

[2] Deri James has contributed patches to realize first-class support
    for man(7); they bring the feature gaps in footnote #1 into sharp
    relief.  Separately, they demand two-pass processing for
    applications like the collected groff man pages built in
    doc/groff-man-pages.pdf.  I'd like to see if we can eliminate that
    by passing the formatter a string of "known internal references"
    (since these are in fact known prior to formatting--troff
    essentially has them all in its argv array [but doesn't know how
    they might map to bookmarks]).  But that is going to require the
    design of a syntax for listing such internal bookmarks and it will
    also require string parsing in the macro package, which is painful
    without a string iterator like that proposed in Savannah #62264.

[3] The PDF is much bigger this time because I've embedded the fonts as
    recommended by the PDF standard after noticing that the ms.pdf I
    sent you looked wrong when I reviewed it on my tablet.  (Courier
    didn't look like Courier but more like Arial.)  PDFs generated by
    gropdf can be post-processed to do font subsetting, which can often
    reduce their file sizes.  Deri has also expressed interest in
    integrating this feature directly into gropdf, which would be a cool
    development!

ms.ms
Description: Troff MS-macros document

ms.pdf
Description: Adobe PDF document

signature.asc
Description: PGP signature