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

[G. Branden Robinson]

At 2023-04-05T14:20:44+0000, Michał Kruszewski wrote:
> > For this, you need the "pdfpagename" macro.
> 
> Where do you get all of this knowledge from?

Five or six years of developing groff.  😂

> I use man groff, man groff_ms, man gropdf, google and I do not come
> across all of these.

No.  I don't think the gropdf(1) page is complete.  I once started a
comprehensive revision of it (along with grops(1)) but put that work on
the shelf in part because I felt there was more I needed to learn to do
the job right.

The commented sources of the pdf.tmac macro file have been helpful to
me.

> Using .XN with groff does not include heading numbers in the ToC.

That difference is my fault.

commit 57ccb455e793cd43ae44da74417aaa28864049fb
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Wed Sep 21 12:04:45 2022 -0500

    [ms]: Slightly simplify new `XN` macro feature.

    ...to align it more closely with Berkeley TOC macro behavior; don't
    prepend the table of contents entry with the section number (`\*[SN]`).
    If desired, a document can define `XN-REPLACEMENT`.  This does not
    regress "pdfmark.ms" because it uses an alternative, older
    implementation of these features from "spdf.tmac".

    * tmac/s.tmac (XH-UPDATE-TOC): Update comments.
      (XN-REPLACEMENT): Do it.

> With pdfroff heading numbers were included in the ToC automatically
> when using .XN. 

Yes, that was a decision of Keith's when he first implemented it for
spdf.tmac.  There's nothing wrong with it, but I felt it was more
orthogonal this way, and would make it easier to migrate historical ms
documents, including dozens of historical Unix papers, to PDF.

Your paper is not yet what we might call historical, so the change did
not serve you as well.

I'm attaching another demonstrator document, this one much shorter,
focused on preparation of section headings.  It also includes the
aforementioned XN-REPLACEMENT, one which includes the section numbers in
the table of contents entries.

Perhaps we could introduce an extension register to groff ms that would
just add the section numbers to the TOC entries without requiring the
user to define `XN-REPLACEMENT`.  I have already filed a ticket about
another wart in the same neighborhood.

https://savannah.gnu.org/bugs/?63158

> I have also realized, that .bp does not work when it is the first
> command, right after .TL. .AU etc.

What was it you were trying to achieve with a page break at the
beginning of the document?

This sort of thing sometimes happens when mixing macro calls and
low-level requests (`bp` is a "request", interpreted by the formatter
itself).  Like `br` (break line), though, `bp` is _often_ usable with
any macro package without causing much in the way of interference.
(Macro packages like man(7), mdoc(7), and mom(7) discourage the document
author from resorting to formatter requests at all, and provide macros
for all supported operations.)

If the formatter believes the page has just been broken, further `bp`
requests will have no effect.  `br` is similar; explicit breaks
immediately after a break has occurred, for any reason, have no effect.

> I would like to have simple structure: custom cover page -> ToC ->
> custom page -> text.  No matter how I try always some kind of mess is
> generated.

The issue that prompted me to join groff development in 2017 was my
frustration with what I regarded as the under-documentation of the
man(7) macro package.  This got me involved with documenting more and
more aspects of the system, because as I looked around, I found
deficiencies just about everywhere (Peter Schaffter's "mom" package
being a notable exception).

Your struggles are a reminder that we still have a way to go, even with
respect to documents where I felt we'd reached something like a
completion state, such as ms.ms.  On the other hand, it does not attempt
to document PDF support features because they are not all in place yet
(when they are, they absolutely will require proper documentation).

More volunteers to support the ongoing improvement of groff are always
welcome, of course.

Let me know how well the attached example addresses your needs.

Regards,
Branden

replacing_XN.ms
Description: Troff MS-macros document

replacing_XN.pdf
Description: Adobe PDF document

signature.asc
Description: PGP signature