Re: [Groff] Cannot understand this error from prfroff

[James K. Lowden]

On Mon, 26 Oct 2015 23:04:36 +1300
Koz Ross <address@hidden> wrote:

> :0: macro error: diversion open while ejecting page (recovering)

It's interesting that the phrase "macro error" relies on a bit of
intution: 

        $ printf '.di foo\nhello\n.bp\n' | groff
        troff: automatically ending diversion `foo' on exit

        $ printf '.di foo\nhello\n.bp\n' | groff -ms
        :0: macro error: diversion open while ejecting page (recovering)

        $ printf '.di foo\nhello\n.bp\n' | groff -me
        Line  -- Unclosed block, footnote, or other diversion (foo)

        $ printf '.di foo\nhello\n.bp\n' | groff -mm
        troff: automatically ending diversion `foo' on exit

Whether or not the open diversion is a "macro error" depends not on
whether a macro was in force, but on whether the ms macro set was in
use.  It's a shame the name of the open diversion is available to ms
but isn't mentioned in the message.  

> What does this mean, and how can I avoid this?

The simple answer is that if you see a diversion error, look for the
use of a macro pair -- e.g., DS/DE, KS/KE, FS/FE -- where you opened a
pair and didn't close it.  The ms documentation calls a diversion a
"keep". Unfortunately it's not rigorous in noting which macros open
diversions, and there's no mention of one in AB/AE.  

To really understand the message, you'd have to know what a troff
diversion is.  Diversions are described in Kernighan's Troff User's
Manual and (more approachably) in Dougherty's Unix Text Processing
(http://www.oreilly.com/openbook/utp/).  

HTH.  

--jkl