Re: [Groff] Confused over diversions

[Werner LEMBERG]

> I am attempting to understand how diversions work, but I am getting
> results that don't match the examples in the info file.

They do match (at least with the version coming with 1.19.2).  Please
read the explanation below -- maybe the section in the info file can
be improved.  Suggestions are highly welcome.

> I put a little test file together based on the example in the info
> file, but things get re-ordered so it looks like the text in the
> line before the first '.di xxx' line ("Before the diversion.") is
> also diverted.  What is going on here?

It is correct that the line before `.di xxx' is diverted also.
groff.info says exactly that.

I'll add comments to the right to explain the meaning:

>  > .ft C
>  > .sp |2i                         \" This causes a break, making
>  > .                               \" the current `partially-filled
>  > .                               \" line' empty.
>  > .ll 4.5i
>  > Before the diversion.           \" This is put into the
>  > .                               \" `partially-filled line'.
>  > .di xxx                         \" The diversion starts
>  > .                               \" collecting data from the
>  > .                               \" `partially-filled line'.
>  > 1 Inside the diversion.
>  > 2 Inside the diversion.
>  > 3 Inside the diversion.
>  > 4 Inside the diversion.
>  > 5 Inside the diversion.
>  > 6 Inside the diversion.
>  > 7 Inside the diversion.
>  > 8 Inside the diversion.
>  > 9 Inside the diversion.
>  > .br                             \" This break flushes the
>  > .                               \" `partially-filled' line to
>  > .                               \" diversion.  Were there no
>  > .                               \" diversion, the data would be
>  > .                               \" flushed to the `top-level
>  > .                               \" diversion' which is the
>  > .                               \" normal output stream.
>  > .di                             \" End of redirection.
>  > After the diversion.
>  > .br                             \" The data is no longer
>  > .                               \" redirected, thus it is
>  > .                               \" flushed to the normal output
>  > .                               \" stream.

Hope this helps.  To not include the partially-filled line into the
diversion, either use `.box' or switch to a new environment.


    Werner