Info Catalog groff: Leading Spaces Traps groff: Traps

groff: End-of-input Traps

 
 5.24.6 End-of-input Traps
 -------------------------
 
  -- 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 that 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.
 
      Another possible use of the 'em' request is to make 'gtroff' emit a
      single large page instead of multiple pages.  For example, one may
      want to produce a long plain-text file for reading on-screen.  The
      idea is to set the page length at the beginning of the document to
      a very large value to hold all the text, and automatically adjust
      it to the exact height of the document after the text has been
      output.
 
           .de adjust-page-length
           .  br
           .  pl \\n[nl]u   \" \n[nl] holds the current page length
           ..
           .
           .de single-page-mode
           .  pl 99999
           .  em adjust-page-length
           ..
           .
           .\" activate the above code
           .single-page-mode
 
      Since only one end-of-input trap does exist and other macro
      packages may already use it, care must be taken not to break the
      mechanism.  A simple solution would be to append the above macro to
      the macro package's end-of-input macro using the '.am' request.
 

Info Catalog groff: Leading Spaces Traps groff: Traps