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

[Michał Kruszewski]

There are so many differences between pdfroff 1.22.4 <-> groff 1.22.4 and 
between groff 1.22.4 <-> 1.23.0rc3 that I think I am lost.
I have started doing small changes.

Firstly I have switched from pdfroff 1.22.4 to groff 1.22.4.
The layout of the document did not change in case of this switch.
The ToC is of course broken, but lets ignore it for now.

Secondly I have switched from groff 1.22.4 to groff 1.23.0rc3.
However, the layout is now broken, as some of .sp and .bp in my document are 
ignored in the newer version.
I do not see in man groff_ms any macros for page break or vertical space.
I am attaching a little reproducer.
Compile with groff 1.22.4 and groff 1.23.0rc3.
You will easily see the changes in the generated layout.

Best regards,
Michał Kruszewski


Sent with Proton Mail secure email.

------- Original Message -------
On Wednesday, April 5th, 2023 at 6:06 PM, G. Branden Robinson 
<g.branden.robinson@gmail.com> wrote:


> 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

FBDL.ms
Description: Text Data