groff: Page Motions

 
 5.25 Page Motions
 =================
 
 ⇒Manipulating Spacing, for a discussion of the most commonly used
 request for vertical motion, 'sp', which spaces downward by one vee.
 
  -- Request: .mk [reg]
  -- Request: .rt [dist]
      You can "mark" a location on a page for subsequent "return".  'mk'
      takes an argument, a register name in which to store the current
      page location.  If given no argument, it stores the location in an
      internal register.  This location can be used later by the 'rt' or
      the 'sp' requests (or the '\v' escape).
 
      The 'rt' request returns _upward_ to the location marked with the
      last 'mk' request.  If used with an argument, it returns to a
      vertical position DIST from the top of the page (no previous call
      to 'mk' is necessary in this case).  The default scaling unit is
      'v'.
 
      If a page break occurs between a 'mk' request and its matching 'rt'
      request, the 'rt' request is silently ignored.
 
      A simple implementation of a macro to set text in two columns
      follows.
 
           .nr column-length 1.5i
           .nr column-gap 4m
           .nr bottom-margin 1m
           .
           .de 2c
           .  br
           .  mk
           .  ll \\n[column-length]u
           .  wh -\\n[bottom-margin]u 2c-trap
           .  nr right-side 0
           ..
           .
           .de 2c-trap
           .  ie \\n[right-side] \{\
           .    nr right-side 0
           .    po -(\\n[column-length]u + \\n[column-gap]u)
           .    \" remove trap
           .    wh -\\n[bottom-margin]u
           .  \}
           .  el \{\
           .    \" switch to right side
           .    nr right-side 1
           .    po +(\\n[column-length]u + \\n[column-gap]u)
           .    rt
           .  \}
           ..
 
      Now let us apply our two-column macro.
 
           .pl 1.5i
           .ll 4i
           This is a small test that shows how the
           rt request works in combination with mk.
 
           .2c
           Starting here, text is typeset in two columns.
           Note that this implementation isn't robust
           and thus not suited for a real two-column
           macro.
               => This is a small test that shows how the
               => rt request works in combination with mk.
               =>
               => Starting  here,    isn't    robust
               => text is typeset    and   thus  not
               => in two columns.    suited  for   a
               => Note that  this    real two-column
               => implementation     macro.
 
    Several escape sequences enable fine control of movement about the
 page.
 
  -- Escape sequence: \v'expr'
      Vertically move the drawing position.  EXPR indicates the magnitude
      of motion: positive is downward and and negative upward.  The
      default scaling unit is 'v'.  The motion is relative to the current
      drawing position unless EXPR begins with the boundary-relative
      motion operator '|'.  ⇒Numeric Expressions.
 
      Text processing continues at the new drawing position; usually,
      vertical motions should be in balanced pairs to avoid a confusing
      page layout.
 
      '\v' will not spring a vertical position trap.  This can be useful;
      for example, consider a page bottom trap macro that prints a marker
      in the margin to indicate continuation of a footnote.  ⇒
      Traps.
 
    A few escape sequences that produce vertical motion are unusual.
 They are thought to originate early in AT&T 'nroff' history to achieve
 super- and subscripting by half-line motions on line printers and
 teletypewriters before the phototypesetter made more precise positioning
 available.  They are reckoned in ems--not vees--to maintain continuity
 with their original purpose of moving relative to the size of the type
 Motions-Footnote-1::)
 
  -- Escape sequence: \r
  -- Escape sequence: \u
  -- Escape sequence: \d
      Move upward 1m, upward .5m, and downward .5m, respectively.
 
 Let us see these escape sequences in use.
 
      Obtain 100 cm\u3\d of \ka\d\092\h'|\nau'\r233\dU.
 
    In the foregoing we have paired '\u' and '\d' to typeset a
 superscript, and later a full em negative ("reverse") motion to place a
 superscript above a subscript.  A numeral-width horizontal motion escape
 sequence aligns the proton and nucleon numbers, while '\k' marks a
 horizontal position to which '\h' returns so that we could stack them.
 (We shall discuss these horizontal motion escape sequences presently.)
 In serious applications, we often want to alter the type size of the
 -scripts and to fine-tune the vertical motions, as the 'groff' 'ms'
 package does with its super- and subscripting string definitions.
 
  -- Escape sequence: \h'expr'
      Horizontally move the drawing position.  EXPR indicates the
      magnitude of motion: positive is rightward and negative leftward.
      The default scaling unit is 'm'.  The motion is relative to the
      current drawing position unless EXPR begins with the
      boundary-relative motion operator '|'.  ⇒Numeric
      Expressions.
 
 Motions-Footnote-2::)
 
      .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X\"
 
    There are a number of special-case escape sequences for horizontal
 motion.
 
  -- Escape sequence: \<SP>
      Move right one word space.  (The input is a backslash followed by a
      space.)  This escape sequence can be thought of as a
      non-adjustable, unbreakable space.  Usually you want '\~' instead;
      see ⇒Manipulating Filling and Adjustment.
 
  -- Escape sequence: \|
      Move one-sixth em to the right on typesetting output devices.  If a
      glyph named '\|' is defined in the current font, its width is used
      instead, even on terminal output devices.
 
  -- Escape sequence: \^
      Move one-twelfth em to the right on typesetting output devices.  If
      a glyph named '\^' is defined in the current font, its width is
      used instead, even on terminal output devices.
 
  -- Escape sequence: \0
      Move right by the width of a numeral in the current font.
 
    Horizontal motions are not discarded at the end of an output line as
 word spaces are.  ⇒Breaking.
 
  -- Escape sequence: \w'anything'
  -- Register: \n[st]
  -- Register: \n[sb]
  -- Register: \n[rst]
  -- Register: \n[rsb]
  -- Register: \n[ct]
  -- Register: \n[ssc]
  -- Register: \n[skw]
      Interpolate the width of ANYTHING in basic units.  This escape
      sequence allows several properties of formatted output to be
      measured without writing it out.
 
           The length of the string 'abc' is \w'abc'u.
               => The length of the string 'abc' is 72u.
 
      ANYTHING is processed in a dummy environment: this means that font
      and type size changes, for example, may occur within it without
      affecting subsequent output.
 
      After each use, '\w' sets several registers.
 
      'st'
      'sb'
           The maximum vertical displacements of the text baseline above
           and below, respectively.  The sign convention is opposite that
           of relative vertical motions; that is, depth below the
           (original) baseline is negative.  These registers are
           incorrectly documented in the AT&T 'troff' manual as "the
           highest and lowest extent of [the argument to '\w'] relative
           to the baseline".
 
      'rst'
      'rsb'
           Like 'st' and 'sb', but taking account of the heights and
           depths of glyphs.  In other words, these registers store the
           highest and lowest vertical positions attained by ANYTHING,
           doing what AT&T 'troff' documented 'st' and 'sb' as doing.
 
      'ct'
           Characterizes the geometry of glyphs occurring in ANYTHING.
 
           0
                only short glyphs, no descenders or tall glyphs
 
           1
                at least one descender
 
           2
                at least one tall glyph
 
           3
                at least one each of a descender and a tall glyph
 
      'ssc'
           The amount of horizontal space (possibly negative) that should
           be added to the last glyph before a subscript.
 
      'skw'
           How far to right of the center of the last glyph in the '\w'
           argument, the center of an accent from a roman font should be
           placed over that glyph.
 
  -- Escape sequence: \kp
  -- Escape sequence: \k(ps
  -- Escape sequence: \k[position]
      Store the current horizontal position in the _input_ line in a
      register with the name POSITION (one-character name P,
      two-character name PS).  Use this, for example, to return to the
      beginning of a string for highlighting or other decoration.
 
  -- Register: \n[hp]
      The current horizontal position at the input line.
 
  -- Register: \n[.k]
      A read-only register containing the current horizontal output
      position (relative to the current indentation).
 
  -- Escape sequence: \o'abc...'
      Overstrike the glyphs of characters A, B, C, ...; the glyphs are
      centered, written, and the drawing position advanced by the widest
      of the glyphs.
 
  -- Escape sequence: \zc
      Format the character C with zero width; that is, without advancing
      the drawing position.  Use '\z' to overstrike glyphs aligned to
      their left edges, in contrast to '\o''s centering.
 
  -- Escape sequence: \Z'anything'
      Save the drawing position, format ANYTHING, then restore it.  Tabs
      and leaders in the argument are ignored with an error diagnostic.
 
      We might implement a strike-through macro thus.
 
           .de ST
           .nr width \w'\\$1'
           \Z@\v'-.25m'\l'\\n[width]u'@\\$1
           ..
           .
           This is
           .ST "a test"
           an actual emergency!