[groff] vertical resolution and page location traps

[Dave Kemper]

I'm having trouble understanding the .V register and how it interacts with page 
location traps.

The info manual's sole phrase describing this register is "Vertical resolution 
in basic units."  This is less than illuminating because it doesn't address: 
basic units per what?  A resolution should have two units to be meaningful, 
unless the term is being used in some unconventional way (in which case, that 
should be explained).

The actual numbers returned under various conditions add only more confusion.

$ groff -Tascii <<< '.tm \n(.V' > /dev/null
40
$ groff -Tps <<< '.tm \n(.V' > /dev/null
1
$ groff -Tpdf <<< '.tm \n(.V' > /dev/null
1

I don't see how the vertical resolution of the ascii device can be 40 times 
that of the ps and pdf devices.

This came up as a practical matter when trying to understand this behavior:

$ groff -a << EOF
.de trap1
.tm trap 1
..
.de trap2
.tm trap 2
..
.de trap3
.tm trap 3
..
.de trap4
.tm trap 4
..
.de trap5
.tm trap 5
..
.de trap6
.tm trap 6
..
.wh 2.1i trap1
.wh 2.2i trap2
.wh 2.3i trap3
.wh 2.4i trap4
.wh 2.5i trap5
.wh 2.6i trap6
.nf
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
EOF

which produces the following (a mix of stdout and stderr):

1
2
3
4
5
6
7
8
9
10
11
12
13
trap 1
14
trap 2
15
trap 4
16
trap 6
17
18
19
20

I don't understand why some of the traps never get triggered.  I dimly suspect 
it has something to do with these bits from the .wh documentation:

  ".wh dist [macro]"

  "values of DIST are always rounded to be multiples of the vertical resolution 
(as given in register '.V')."

  "to have more than one trap at the same location... the traps must be defined 
at different locations, then moved together...; otherwise the second trap would 
replace the first one."

That is, while the six .wh requests specify six distinct locations, it's 
possible rounding is causing .wh to consider traps 3 and 4 to be in the same 
location, and the same with 5 and 6.  Thus trap 4 would replace trap 3, and 
trap 6 replace trap 5.  But I don't understand the mechanism.

For the default ps device, the value of the .V register is 1.  "Rounded to the 
nearest multiple of one" should mean "rounded to the nearest integer."  But 
this still leaves two possible ways to interpret how that rounding is done, and 
neither explains the observed behavior.

 - each number provided to .wh is rounded to the nearest integer.  So 2.1, 2.2, 
2.3, and 2.4 should be rounded to 2, and 2.5 and 2.6 should be rounded to 3.  
In this scenario, there should be output from only traps 4 and 6.  (That is, 
traps 1 to 4 would all be set at 2i, and trap 4, being the last set of those, 
would persist.  Then traps 5 and 6 would be set at 3i, and trap 6 would replace 
5.)

 - each number is converted to basic units, and then rounded to the nearest 
integer.  All six numbers are different in basic units; therefore, all six 
traps should get called.

So I cannot fathom what causes only traps 1, 2, 4, and 6 to be triggered.

(Specifying "-Tascii" changes which traps are triggered -- now it's 2, 4, 5, 
and 6 -- but still gives me no insight into the behavior.)

Have I overlooked something in the documentation that explains this?