OpenBSD groff package's troffrc file

[G. Branden Robinson]

Hi Ingo,

While poking my nose around the Web to observe groff 1.23.0 uptake, I
noticed OpenBSD's patch to groff's troffrc file.

https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/textproc/groff/patches/patch-tmac_troffrc?rev=1.6&content-type=text/x-cvsweb-markup

The following change concerns me:

+.\" Disable adjustment by default,
+.\" such that manuals look similar with groff and mandoc(1).
+.ad l
+.de ad
+..

This is pretty extreme overkill for trying to get rendering parity
between mandoc(1) and groff on OpenBSD.  Namely, you're (A) hitting
_every_ document and _every_ macro package with an altered default, not
just man pages, and (B) you're clobbering the formatter's `ad` request
so that _there is no way for any document using any macro package to
recover this feature_.  This cripples groff for non-man page
applications that you don't mean for mandoc(1) to support.

I believe I have heard you say before that you don't want to mess with
patching (or maybe even shipping) groff's man.local or mdoc.local files
to fine-tune its behavior.  If that is correct then I recommend the
following patch instead.

.do if !d AD .ds AD l

(Why "do"?  troffrc in groff 1.23.0 is much more careful about trying to
ensure that it works even if the user turns AT&T compatibility mode on
at the command line.)

This employs the new groff 1.23.0 `AD` string supported by groff's
man(7) and mdoc(7).  But it does so only if the user has not already set
that string on the [gnt]roff command line.

Because this does not destroy the `ad` request, it will be possible for
man pages to resurrect adjustment, and some do.  In particular, I have
in mind a relentlessly applied pattern in the Linux man-pages, where
tbl(7) tables are bracketed more or less as follows.

.ad l
.hy 0
.TS
.\" whatever
.TE
.hy
.ad

Not only is this bad practice, it is pointless for tables that don't use
text blocks (so is over-applied) and doesn't fully work as intended
anyway.  `hy` without an argument sets the automatic hyphenation mode to
`1`, not "the previous value", in the spirit of exuberant
non-orthogonality that animated early Bell Labs *roff development.

(I'm working on a sed-driven fix for Linux man-pages.)

(What if a table _does_ have text blocks?

groff tbl(1):

Text blocks are formatted as was the text prior to the table,
modified by applicable column descriptors.  Specifically, the
classifiers A, C, L, N, R, and S determine a text block’s alignment
within its cell, but not its adjustment.  Add na or ad requests to
the beginning of a text block to alter its adjustment distinctly
from other text in the document.  As with other table entries, when
a text block ends, any alterations to formatting parameters are
discarded.  They do not affect subsequent table entries, not even
other text blocks.
)

I think it is better to expose the errors of man pages using bad
practices (and/or poor portability to mandoc(1)) than to neuter a
fundamental feature of text formatting for all groff users on OpenBSD
who have gone to trouble to locate the port and install it.

What do you think?

Regards,
Branden


signature.asc
Description: PGP signature

Re: ms/mm page margins too large

[G. Branden Robinson]

Hi Robin,

I'm sorry it's taken a while for me to get back to you.  We finally got
groff 1.23.0 released and I was pretty preoccupied with that.

At 2023-06-24T02:29:26+0300, Robin Haberkorn wrote:
> I was trying to set up an ms-document with small page margins (see
> attachment), but I don't seem to get below a certain limit (especially
> on the bottom side).  In one-column mode, the bottom border is a bit
> smaller, but still larger than 1cm. I also cannot explain the spacing
> introduced by the .2C request (between BEFORE and AFTER). Build with
> 
> pdfroff -ms margins.ms >margins-ms.pdf
> 
> Does anybody understand what's going on?
> 
> I've tried something similar with mm (margins.mm), trying to set 1cm
> margins on all sides. This doesn't work as well when built with:
> 
> pdfroff -mm -P-pa4 -rW=19c -rO=1c -rL=27.7c margins.mm >margins-mm.pdf
> 
> Although, here we can at least set the page length to something
> oversized like 31c to get close to what we want. A4 has a height of
> 29.7cm, so this is also strange.
> 
> For my particular task, I will probably just switch from ms to mm. But
> it would be nice to understand why they behave this way.

There are a lot of interacting pieces, and places where things can go
wrong, in this scenario.

1.  You're using the pdfroff wrapper instead of groff directly.
2.  You're using a non-default paper size (the formatter and output
devices assume U.S. letter paper; we have mechanisms for overriding
this, but they require some care in usage).
3.  You're testing the margin configuration features of two different
macro packages.

To try to reduce the complexity and narrow down where problems exist, I
constructed my own attempt at getting an ms document with 1cm margins on
all sides of the page.

I'll give you the bad news first.

A.  groff 1.22.4 requires some corrective efforts in this scenario.
B.  The groff ms package arguably does not correctly document the
bottom footer size, and does not warn when its sign is wrong (or
perhaps should use the absolute value of the measurement given; see
below).

The good news is that I was able to get what looks to me like a
well-formatted ms document with 1cm margins on U.S. letter paper using
groff 1.23.

(The bottom margin still isn't a perfect 1cm, I don't think, but it
seems to be pretty close, with the slight excess size arising from the
default type size and vertical spacing not evenly dividing the printed
page area.  Adjustments to either or both of the `PS` and `VS` registers
could, I think, get the margins "perfect".  As long as there aren't any
footnotes.)

Here is my input.

.nr PO 1c
.nr LL 8.5i-\n[PO]u-1c
.nr LT \n[LT]u
.nr HM 1c
.nr FM -1c
.ds CH \" empty
.LP
.while (\n[%] < 2) \{\
a\:b\:c\:d\:e\:f\:g\:h\:i\:j\:k\:l\:m\:\
n\:o\:p\:q\:r\:s\:t\:u\:v\:w\:x\:y\:z
.\}

A few differences between your ms exhibit and mine leap out at me.

a.  I used a negative value for `FM`; since I happened to know that top
and bottom margins are implemented using page location traps in the
formatter, and that negative values for such traps indicate
distances from the bottom of the page, I played a hunch and, to
appearances, I guessed right.  I regard this as a deficiency in our
ms(7) documentation or implementation.

b.  I didn't bother to clear the center footer string `CF` since ms(7)
does not set it by default.

c.  I made sure to initialize the package with an `LP` call.  This is
important, and _is_ documented.

d.  I tried to fill the page with text to make it easier to see the
margins.

e.  I used a scaling unit when interpolating the `PO` register.  This
isn't strictly necessary (because the `nr` request can be said to
assume a scaling unit of "u"), but it's a good habit to get into
when using formatter requests.

f.  I regard my hard-coding of the U.S. letter paper width (8.5i) as
clumsy.  It would probably be better to use the strings defined in
"papersize.tmac", which is automatically loaded by "troffrc" in
the formatter's troff mode.

I'm attaching the foregoing document as rendered with groff 1.22.4 and
groff 1.23.0 (released 12 days ago).

The following "NEWS" item from 1.23 might provide a partial explanation
for why this new release works better.

o The s (ms) macro package now uses a default line length of 6.5 inches
  by default, resulting in 1-inch left and right margins.  When the
  "papersize.tmac" package is used by employing the "-d paper" groff(1)
  option on typesetting devices, the default page offset and line length
  are adjusted to maintain these margins.

I think next steps for troubleshooting this issue would involve:

I.Verifying that the same results can be achieved with ISO A4 paper.

II.   Verifying that the same results can be achieved groff mm(7).

III.  Verifying that the same results can be achieved using pdfroff.

In the meantime, I'll have a look at groff ms's internals, and
historical implementations, see why t

pic/-ms inconsistency in groff 1.23.0

[Douglas McIlroy]

Upon updating from 1.22.4 to 1.23.0 this pic delimiter
 .PS 6i
failed; it worked in 1.22.4. The updated pic turns it into
 .PS 6.000i 6.000i 6i
which causes groff -ms to barf:
 s.tmac: ... error: .PS: expected 2 arguments, got 3; not
preprocessed with pic?

groff, pic, and tmac.s were all updated. I can find no dregs from
1.22.4 on my computer.

A third party had their fingers on the code: cygwin. Is this
inconsistency their fault, is it inherent in 1.23.0, or is it
something more mysterious?

Doug

Re: pic/-ms inconsistency in groff 1.23.0

[ASSI]

Douglas McIlroy writes:
> groff, pic, and tmac.s were all updated. I can find no dregs from
> 1.22.4 on my computer.

Run setup.exe and select the previous version?

> A third party had their fingers on the code: cygwin. Is this
> inconsistency their fault, is it inherent in 1.23.0, or is it
> something more mysterious?

I haven't patched anything in that area.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptations for KORG EX-800 and Poly-800MkII V0.9:
http://Synth.Stromeko.net/Downloads.html#KorgSDada

Re: pic/-ms inconsistency in groff 1.23.0

[Dave Kemper]

On 7/17/23, Douglas McIlroy  wrote:
> Upon updating from 1.22.4 to 1.23.0 this pic delimiter
>  .PS 6i
> failed; it worked in 1.22.4. The updated pic turns it into
>  .PS 6.000i 6.000i 6i

1.22.4 pic also turned it into that, so it is -ms's behavior that has changed.

$ cat pictest
.PS 6i
circle
.PE
$ pic --version
GNU pic (groff) version 1.22.4
$ pic pictest | fgrep .PS
.PS 6.000i 6.000i 6i
$

Commit b16ad66b
(http://git.savannah.gnu.org/cgit/groff.git/commit/?id=b16ad66b) seems
the likely culprit:

Author: G. Branden Robinson 
Date:   Mon Aug 15 00:24:48 2022 -0500

[ms]: Validate `PS` arguments better.

* tmac/s.tmac (@PS): Validate better; check for 2 arguments exactly.

Also improve diagnostic message wording.

Re: pic/-ms inconsistency in groff 1.23.0

[G. Branden Robinson]

Hi Doug & Dave,

At 2023-07-17T10:33:30-0400, Douglas McIlroy wrote:
> which causes groff -ms to barf:
>  s.tmac: ... error: .PS: expected 2 arguments, got 3; not
> preprocessed with pic?

Thanks for trying out groff 1.23.0!  I hope it seems like an improvement
in respects other than this one.

At 2023-07-17T11:20:11-0500, Dave Kemper wrote:
> 1.22.4 pic also turned it into that, so it is -ms's behavior that has
> changed.
> 
> $ cat pictest
> .PS 6i
> circle
> .PE
> $ pic --version
> GNU pic (groff) version 1.22.4
> $ pic pictest | fgrep .PS
> .PS 6.000i 6.000i 6i
> $
> 
> Commit b16ad66b
> (http://git.savannah.gnu.org/cgit/groff.git/commit/?id=b16ad66b) seems
> the likely culprit:
> 
> Author: G. Branden Robinson 
> Date:   Mon Aug 15 00:24:48 2022 -0500
> 
> [ms]: Validate `PS` arguments better.
> 
> * tmac/s.tmac (@PS): Validate better; check for 2 arguments exactly.
> 
> Also improve diagnostic message wording.

Confirmed.  My incomplete understanding of pic(1), spottier even than my
understanding of eqn(1), created a problem here.

In a pinch, the following patch will disable the oversensitive
validation.

diff --git a/tmac/s.tmac b/tmac/s.tmac
index 5fc1237eb..f4a97eb0f 100644
--- a/tmac/s.tmac
+++ b/tmac/s.tmac
@@ -2095,7 +2095,7 @@ along with this program.  If not, see 
.
 .de @PS
 .br
 .sp \\n[DD]u
-.ie !\\n[.$]=2 \{\
+.ie 0 \{\
 .  ds pic*msg .PS: expected 2 arguments, got \\n[.$]\"
 .  as pic*msg ; not preprocessed with pic?\"
 .  @error \\*[pic*msg]

I will try to find out where on earth the rewriting of `PS` macro calls
is documented, what arguments beyond the third mean, and correct the
validation logic in groff ms.

Testing of DWB 3.3 and Heirloom pic suggests that all arguments given to
`PS` in the source document are simply stuck on to the same call as the
3rd and subsequent arguments in the output.  If there is no access to
these arguments in the pic language, it seems to me that it would have
been better to put a \" comment escape sequence ahead of them.

Regards,
Branden


signature.asc
Description: PGP signature