[Groff] Mysteries of .em request

[Werner LEMBERG]

I've just revised the documentation of .em -- maybe you haven't known
these limitations...


    Werner


======================================================================

 -- Request: .em macro
     Set a trap at the end of input.  MACRO is executed after the last
     line of the input file has been processed.

     For example, if the document had to have a section at the bottom
     of the last page for someone to approve it, the `em' request could
     be used.

          .de approval
          \c
          .  ne 3v
          .  sp (\\n[.t]u - 3v)
          .  in +4i
          .  lc _
          .  br
          Approved:\t\a
          .  sp
          Date:\t\t\a
          ..
          .
          .em approval

     The `\c' in the above example needs explanation.  For historical
     reasons (and for compatibility with AT&T `troff'), the end macro
     exits as soon as it causes a page break and no remaining data is
     in the partially collected line.

     Let us assume that there is no `\c' in the above `approval' macro,
     and that the page is full and has been ended with, say, a `br'
     request.  The `ne' request now causes the start of a new page,
     which in turn makes `troff' exit immediately for the reasons just
     described.  In most situations this is not intended.

     To always force processing the whole end macro independently of
     this behaviour it is thus advisable to insert something which
     starts an empty partially filled line (`\c') whenever there is a
     chance that a page break can happen.  In the above example, the
     call of the `ne' request assures that the remaining code stays on
     the same page, so we have to insert `\c' only once.

     The next example shows how to append three lines, then starting a
     new page unconditionally.  Since `.ne 1' doesn't give the desired
     effect - there is always one line available or we are already at
     the beginning of the next page - we temporarily increase the page
     length by one line so that we can use `.ne 2'.

          .de EM
          .pl +1v
          \c
          .ne 2
          line one
          .br
          \c
          .ne 2
          line two
          .br
          \c
          .ne 2
          line three
          .br
          .pl -1v
          \c
          'bp
          ..
          .em EM

     Note that this specific feature affects only the first potential
     page break caused by the end macro; further page breaks emitted by
     the end macro are handled normally.