Last-Updated: 2021-08-30
In this macro (2008-12/msg00006) written by Tadziu Hoffmann, we have a block of text made of multiple paragraphs and we want this block to be of a certain height. To do so, we will adjust the spacing between paragraphs. We will not change the line length.
This macro is commented for clarity but it may be clearer if we explained .YY and .EB (2021-08/msg00096). The .YY diversion is only used as a container to reflow the text output by the .XX macro, it should not be used outside of this use case. And the .EB macro doesn't need to be defined, it's irrelevant to the goal of the macro and is only used here to output "finished reading text" to standard error.
.\" ----------------------------------------------------------------
.\" begin block of text for multiple processing
.de BB
.tm starting to read text...
.de XX EB
..
.\" ----------------------------------------------------------------
.\" end block
.de EB
.tm finished reading text.
..
.\" ----------------------------------------------------------------
.\" delayed space macro, counts occurrences as well
.de SP
.nr NN +1
.sp \\n(QQu
..
.\" ----------------------------------------------------------------
.\" now gather text
.BB
This text can be
.SP
processed
.SP
multiple
.SP
times.
.EB
.\" ----------------------------------------------------------------
.\" process text once to determine height
.nr QQ 0
.nr NN 0
.di YY
.XX
.br
.di
.tm the text has a height of \n(dn units
.\" ----------------------------------------------------------------
.\" now make text fit into exactly 2 cm
.nr QQ 2c-\n(dnu/\n(NNu \" note left-to-right, no precedence rules
.\" reprocessing to verify is not really necessary, just for demo
.di YY
.XX
.br
.di
.nr OO 2c
.tm the text now has a height of \n(dn units, 2 cm is \n(OO units
.\" ----------------------------------------------------------------
.\" output text
.sp 3c
Preceding text
.br
\M[yellow]\h'-.1c'\v'-.75v'\D'P 0 2c \n(dlu+.2c 0 0 -2c'
This yellow box has a height of 2 cm.
.sp -1
.XX
.br
Following text.