contrib/mom/momdoc/version-2.html

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!--
   3 This file is part of groff, the GNU roff type-setting system.
   4
   5 Copyright (C) 2004-2018 Free Software Foundation, Inc.
   6 Written by Peter Schaffter (peter@schaffter.ca).
   7
   8 Permission is granted to copy, distribute and/or modify this document
   9 under the terms of the GNU Free Documentation License, Version 1.3 or
  10 any later version published by the Free Software Foundation; with no
  11 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  12 Texts.
  13
  14 A copy of the Free Documentation License is included as a file called
  15 FDL in the main directory of the groff source package.
  16 -->
  17
  18 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  19 <html xmlns="http://www.w3.org/1999/xhtml">
  20
  21 <head>
  22   <meta http-equiv="content-type" content="text/html;charset=utf-8"/>
  23   <title>Mom -- Version 2.0 notes</title>
  24   <link rel="stylesheet" type="text/css" href="stylesheet.css" />
  25 </head>
  26
  27 <body style="background-color: #f5faff;">
  28
  29 <!-- ==================================================================== -->
  30
  31 <div id="top" class="page">
  32
  33 <!-- Navigation links -->
  34 <table style="width: 100%;">
  35 <tr>
  36   <td><a href="toc.html">Back to Table of Contents</a></td>
  37   <td style="text-align: right;"><a href="intro.html#top">Next: Introduction to mom</a></td>
  38 </tr>
  39 </table>
  40
  41 <h1 class="docs">Version 2.0 notes</h1>
  42
  43 <div style="width: 70%; margin: auto;">
  44 <ol style="margin-left: -1em;">
  45   <li><a href="#prefatory">Prefatory comments</a></li>
  46   <li><a href="#differences">Differences between 2.0 and 1.x</a>
  47   <ul class="no-enumerator" style="padding-left: 0">
  48     <li><a href="#pdf-support">2.1 PDF support</a>
  49     <ul class="no-enumerator" style="padding-left: 1em">
  50       <li><a href="#mom-pdf">2.1.1 The manual, <span class="book-title">Producing PDFs with groff and mom</span></a></li>
  51       <li><a href="#pdf-image">2.1.2 PDF_IMAGE</a></li>
  52     </ul></li>
  53     <li><a href="#covers">2.2 Covers</a></li>
  54     <li><a href="#headings">2.3 Headings</a></li>
  55     <li><a href="#margin-notes">2.4 Margin notes</a></li>
  56     <li><a href="#floats">2.5 Floats</a></li>
  57     <li><a href="#table-of-contents">2.5 Tables of contents</a></li>
  58   </ul></li>
  59   <li><a href="#v2.1-changes">Version 2.1 changes</a></li>
  60   <li><a href="#pdfmom">The <strong>pdfmom</strong> wrapper around groff</a></li>
  61   <li><a href="#install-font">The <strong>install-font.sh</strong> script</a></li>
  62 </ol>
  63 </div>
  64
  65 <div class="rule-medium"><hr/></div>
  66
  67 <h2 id="prefatory" class="docs">1. Prefatory comments</h2>
  68
  69 <p>
  70 Version 2.0 comes about as a result of Deri James&#8217;
  71 contribution of <strong>gropdf</strong> to <strong>groff</strong>,
  72 and his subsequent work integrating the device with
  73 <strong>mom</strong>.
  74 </p>
  75
  76 <p>
  77 Whereas the 1.x releases were oriented toward PostScript output,
  78 2.0 focuses on PDF output, a bias reflected throughout this
  79 documentation.  Users are strongly encouraged to process their files
  80 with
  81 <a href="#pdfmom"><strong>pdfmom</strong></a>,
  82 a wrapper around <strong>groff&nbsp;-Tpdf</strong>, in order to take
  83 full advantage of all PDF has to offer.
  84 </p>
  85
  86 <p>
  87 While portions of mom have been rewritten, and new features
  88 introduced, 2.0 is backwardly compatible with 1.x releases.  Changes
  89 are either transparent, or accompanied by notifications on stderr.
  90 </p>
  91
  92 <p>
  93 The implementation of nested heads has been completely rethought,
  94 as has the manner of styling of them.  There are no limits on
  95 how deep the nesting can go.  The 1.x macros <kbd>HEAD</kbd>,
  96 <kbd>SUBHEAD</kbd>, and <kbd>SUBSUHEAD</kbd> may still be used, but
  97 must be re-designed with the new <kbd>HEADING_STYLE</kbd> macro
  98 if their 1.x defaults are not desired.
  99 </p>
 100
 101 <p>
 102 In conjunction with the changes to nested heads, Table of Contents
 103 generation has also been rethought.  Greater flexibility in the
 104 inclusion of toc entry numbering been added.  Like nested heads,
 105 there&#8217;s a new macro <kbd>TOC_ENTRY_STYLE</kbd> that permits
 106 styling of each level in the toc hierarchy separately.  The default
 107 overall layout has also been significantly improved, achieving a
 108 level of typographical elegance formerly lacking.  Best of all, the
 109 Table of Contents can now be repositioned to the correct spot at the
 110 top of a document from within the mom source file.
 111 </p>
 112
 113 <p>
 114 When mom files are processed with <strong>pdfmom</strong>, a PDF
 115 outline for the Contents panel of PDF viewers is automatically
 116 generated.  In addition, entries in the Table of Contents
 117 are clickable links when a document is viewed at the screen.
 118 <strong>pdfmom</strong> also permits setting a document&#8217;s
 119 papersize within the source file without the corresponding need for
 120 <kbd>-P-p&lt;papersize&gt;</kbd> on the command line.
 121 </p>
 122
 123 <p>
 124 Lastly, while not strictly part of mom, a bash script,
 125 <strong>install-font.sh</strong>, has been posted at the
 126 <a href="http://www.schaffter.ca/mom/">mom site</a>.
 127 The script significantly eases the installation of new
 128 groff families and fonts, with conversion to .pfa
 129 and .t42 being performed by <strong>fontforge</strong>.
 130 </p>
 131
 132 <h2 id="differences" class="docs">2. Differences between v2.0 and v1.x</h2>
 133
 134 <h3 id="pdf-support" class="docs">2.1. PDF support</h3>
 135
 136 <p>
 137 PDF support has been added, with features including the automatic
 138 generation of PDF outlines, embedding of images in PDF format (via
 139 the
 140 <a href="images.html#pdf-image">PDF_IMAGE</a>
 141 macro) and PDF linking (internal and external).
 142 </p>
 143
 144 <h4 id="mom-pdf" class="docs">2.1.1. Producing PDFs with groff and mom</h4>
 145
 146 <p>
 147 A manual in PDF format,
 148 <span class="book-title">Producing PDFs with groff and mom</span>,
 149 has been added to the documentation.  The file,
 150 <strong>mom-pdf.pdf</strong> can be found in
 151 <br/>
 152 <span class="pre-in-pp">
 153   /usr/local/share/doc/groff-&lt;version&gt;/pdf/
 154 </span>
 155 or
 156 <br/>
 157 <span class="pre-in-pp">
 158   /usr/share/doc/groff-base/pdf/
 159 </span>
 160 or at
 161 <br/>
 162 <span class="pre-in-pp">
 163   <a href="http://www.schaffter.ca/mom/momdoc/mom-pdf.pdf">http://www.schaffter.ca/mom/momdoc/mom-pdf.pdf</a>
 164 </span>
 165 PDF usage, and all associated macros except
 166 <a href="#pdf-image">PDF_IMAGE</a>,
 167 are fully explained in the manual, which should be considered an
 168 integral part of the present documentation.  In addition, the mom
 169 source file for the manual can be found in
 170 <br/>
 171 <span class="pre-in-pp">
 172   /usr/local/share/doc/groff-&lt;version&gt;/examples/mom
 173 </span>
 174 or
 175 <br/>
 176 <span class="pre-in-pp">
 177   /usr/share/doc/groff-base/examples/mom/
 178 </span>
 179 and provides an excellent demonstration of mom usage.
 180 </p>
 181
 182 <h4 id="pdf-image" class="docs">2.1.2. PDF_IMAGE</h4>
 183
 184 <p>
 185 A new macro for embedding PDF images has been added,
 186 <a href="images.html#pdf-image"><kbd>PDF_IMAGE</kbd></a>.
 187 </p>
 188
 189 <p>
 190 <kbd>PDF_IMAGE</kbd> functions similarly to <kbd>PSPIC</kbd> and
 191 accepts the same arguments.  Differences in implementation are that
 192 PDF_IMAGE requires the image dimensions (the bounding box) to be
 193 supplied.  Instructions for getting the bounding box are included in
 194 the documentation entry for PDF_IMAGE.  Two additional options,
 195 <kbd>SCALE</kbd> and <kbd>ADJUST</kbd>, allow scaling of the image
 196 and optical centering.
 197 </p>
 198
 199 <h3 id="covers" class="docs">2.2. Covers</h3>
 200
 201 <p>
 202 Arguments to
 203 <a href="cover.html#cover"><kbd>COVER</kbd></a>
 204 and
 205 <a href="cover.html#doc-cover"><kbd>DOC_COVER</kbd></a>
 206 may now be given in any order.
 207 </p>
 208
 209 <h3 id="headings" class="docs">2.3. Headings</h3>
 210
 211 <p>
 212 The 1.x macros
 213 <br/>
 214 <span class="pre-in-pp">
 215   HEAD SUBHEAD SUBSUBHEAD
 216 </span>
 217 are now deprecated and have been replaced by a single macro
 218 <br/>
 219 <span class="pre-in-pp">
 220   <a href="docelement.html#heading"><kbd>HEADING &lt;n&gt;</kbd></a>
 221 </span>
 222 where <kbd>&lt;n&gt;</kbd> is the heading level.  The deprecated
 223 macros may still be used, and conform in style to their original
 224 defaults; they are, however, wrappers around
 225 <kbd>HEADING</kbd> levels 1 - 3.
 226 Both the wrappers and <kbd>HEADING</kbd> itself can take a
 227 <kbd>NAMED &lt;id&gt;</kbd> argument, specifying a PDF link
 228 destination.
 229 </p>
 230
 231 <p>
 232 Styling of headings is managed by a single macro
 233 <br/>
 234 <span class="pre-in-pp">
 235   <a href="docelement.html#heading"><kbd>HEADING_STYLE &lt;n&gt;</kbd></a>
 236 </span>
 237 where <kbd>&lt;n&gt;</kbd> conforms to a <kbd>HEADING</kbd> level.
 238 The control macros for HEAD, SUBHEAD and SUBSUBHEAD have been
 239 removed.  Users wishing to style the wrappers must use
 240 <kbd>HEADING_STYLE</kbd>.
 241 </p>
 242
 243 <p>
 244 <kbd>PARAHEAD</kbd> is no longer valid.  Paragraph heads in
 245 2.0 are created by passing the <kbd>PARAHEAD</kbd> argument to
 246 <kbd>.HEADING</kbd>.  Mom will abort with an informational message
 247 whenever she encounters <kbd>.PARAHEAD</kbd>.
 248 </p>
 249
 250 <h3 id="margin-notes" class="docs">2.4. Margin notes</h3>
 251
 252 <p>
 253 The macro for setting margin note parameters,
 254 <a href="docelement.html#mn-init"><kbd>MN_INIT</kbd></a>,
 255 has been re-written such that each parameter now has the form
 256 <br/>
 257 <span class="pre-in-pp">
 258   &lt;PARAMETER&gt; &lt;value&gt;
 259 </span>
 260 This differs from 1.x where parameters were entered without a
 261 preceding <kbd>&lt;PARAMETER&gt;</kbd> flag.  Parameters may be
 262 entered in any order.  Any that are skipped are set to default
 263 values.  Documents created with 1.x will have to have their
 264 <kbd>MN_INIT</kbd> updated accordingly.
 265 </p>
 266
 267 <h3 id="floats" class="docs">2.5. Floats</h3>
 268
 269 <p>
 270 A
 271 <a href="images.html#floats-intro">FLOAT</a>
 272 macro has been added, which functions similarly to the <kbd>ms</kbd>
 273 macros&#8217; <kbd>.KF/.KE</kbd>, ie the contents of the float are
 274 output immediately if there&#8217;s room on the page; otherwise,
 275 normal text processing continues and the contents are output at the
 276 top of the next page.  An <kbd>ADJUST</kbd> argument to FLOAT allows
 277 for optical centering.
 278 </p>
 279
 280 <h3 id="table-of-contents" class="docs">2.6. Tables of contents</h3>
 281
 282 <p>
 283 The default look of the Table of Contents has been overhauled to
 284 produce a more typographically pleasing result.  All control macros
 285 for TOC title and entry styles have been removed, replaced by the
 286 macros
 287 <br/>
 288 <span class="pre-in-pp">
 289   <a href="tables-of-contents.html#toc-title-style">TOC_TITLE_STYLE</a>
 290 </span>
 291 and
 292 <br/>
 293 <span class="pre-in-pp">
 294   <a href="tables-of-contents.html#toc-title-style">TOC_ENTRY_STYLE &lt;n&gt;</a>
 295 </span>
 296 where <kbd>&lt;n&gt;</kbd> corresponds to a <kbd>HEADING</kbd>
 297 level.  Both macros permit setting any or all of the style
 298 parameters for TOC titles (ie chapters or major sections/divisions
 299 of a collated document) and TOC entries (nested heading levels) at
 300 once.  Documents created with 1.x that contain TOCs will need to
 301 have their TOC style updated if the new defaults are unsatisfactory.
 302 </p>
 303
 304 <p>
 305 Two new TOC control macros have been added,
 306 <br/>
 307 <span class="pre-in-pp">
 308   <a href="tables-of-contents.html#space-toc-items">SPACE_TOC_ITEMS</a>
 309 </span>
 310 and
 311 <br/>
 312 <span class="pre-in-pp">
 313   <a
 314   href="tables-of-contents.html#auto-relocate-toc">AUTO_RELOCATE_TOC</a>
 315 </span>
 316 <kbd>SPACE_TOC_ITEMS</kbd> groups TOC entry levels and separates
 317 them with a discrete amount of whitespace.  This leads to improved
 318 legibility, and is highly recommended even though it is not
 319 mom&#8217;s default. <kbd>AUTO_RELOCATE_TOC</kbd> intelligently
 320 repositions the Table of Contents to the top of a document when
 321 the mom source file is processed with
 322 <a href="pdfmom"><strong>pdfmom</strong></a>.
 323 </p>
 324
 325 <h2 id="v2.1-changes" class="docs">3. Version 2.1 changes</h2>
 326
 327 <p>
 328 Version 2.1 adds these features:
 329 </p>
 330 <ul style="margin-top: -.5em; width: 90%">
 331   <li>expansion of cover, docheader, page header, and heading
 332   control macros to permit caps, smallcaps, color, and
 333   underscoring</li>
 334   <li>the ability to style every element appearing in docheaders and
 335   automatically-generated cover/title pages separately</li>
 336   <li>macros to place images on cover/title pages</li>
 337   <li>a new macro COVERTEXT that allows adding text (e.g. an
 338   Abstract) to automatically-generated cover/title pages or to
 339   create cover/title pages entirely by hand</li>
 340   <li>separate indent control macros for QUOTES and BLOCKQUOTES</li>
 341   <li>pseudo-smallcaps, including a control macro to choose the
 342   size, weight, and width of the small caps</li>
 343   <li>new &lt;element&gt;_STYLE macros that allow setting
 344   parameters for &lt;element&gt; with a single macro using
 345   keyword/value pairs</li>
 346 </ul>
 347
 348 <p>
 349 The following changes have been made:
 350 </p>
 351
 352 <ul style="margin-top: -.5em; width: 90%">
 353   <li>MISC_AUTOLEAD (including COVER_MISC_AUTOLEAD and
 354   DOC_COVER_MISC_AUTOLEAD) has been replaced in favour of MISC_LEAD,
 355   which takes an absolute leading value, rather than one derived
 356   from the point size</li>
 357   <li>COVER_UNDERLINE and DOC_COVER_UNDERLINE have been
 358   removed in favour of COVER_DOCTYPE_UNDERLINE and
 359   DOC_COVER_DOCTYPE_UNDERLINE</li>
 360   <li>DOCTYPE NAMED &lt;string&gt; no longer accepts a color
 361   argument; setting the color for &lt;string&gt; is accomplished with
 362   DOCTYPE_COLOR &lt;color&gt;; in addition, the string now has a
 363   complete set of control macros</li>
 364   <li>default underscoring of the DOCTYPE NAMED string has been
 365   removed, both in the docheader and on cover/title pages</li>
 366   <li>no cover/title page data persists, however formatting for the
 367   elements on them does</li>
 368 </ul>
 369
 370 <h2 id="v2.1-changes" class="docs">3. Version 2.2 changes</h2>
 371
 372 <p>
 373 Version 2.2 adds these features:
 374 </p>
 375 <ul style="margin-top: -.5em; width: 90%">
 376   <li>flex-spacing, an alternative to mom&#8217;s default shimming
 377   policy; flex-spacing balances vertical whitespace on the page by
 378   distributing any excess equally at sensible points so that running
 379   text always fills the page to the bottom margin (see
 380   <a href="docprocessing.html#vertical-whitespace-management">
 381     vertical whitespace management</a>
 382   </li>
 383   <li>improvements to auto-labelling, such that it is now possible
 384   to link symbollically to auto-labelled preprocessor material and
 385   PDF images</li>
 386 </ul>
 387
 388 <h2 id="pdfmom" class="docs">4. pdfmom</h2>
 389
 390 <p>
 391 Deri James has provided <strong>pdfmom</strong>, a wrapper around
 392 groff that processes mom source files with all the PDF bells and
 393 whistles.  Its use is highly recommended.  Usage is explained in the
 394 manual,
 395 <a href="http://www.schaffter.ca/mom/pdf/mom-pdf.pdf"><span class="book-title">Producing PDFs with groff and mom</span></a>.
 396 A significant convenience of <strong>pdfmom</strong> is that it can,
 397 with the <kbd>-Tps</kbd> flag, be used to pass processing over to Keith
 398 Marshall&#8217;s <strong>pdfroff</strong>.  This is useful when
 399 processing files that contain PostScript images embedded with
 400 <kbd>PSPIC</kbd>. <strong>pdfmom</strong>, without the flag, uses
 401 groff&#8217;s PDF device (<strong>gropdf</strong>), which only
 402 recognizes PDF images that have been embedded with
 403 <a href="images.html#pdf-image"><kbd>PDF_IMAGE</kbd></a>.
 404 </p>
 405
 406 <h2 id="install-font" class="docs">5. install-font.sh</h2>
 407
 408 <p>
 409 A bash script, <strong>install-font.sh</strong>, has been posted at the
 410 <a href="http://www.schaffter.ca/mom/mom-01.html">mom site</a>.
 411 There&#8217;s nothing mom-specific about the script, and it is not
 412 an official part of groff.
 413 </p>
 414
 415 <p>
 416 Installing groff fonts is a multi-step procedure, which, while not
 417 difficult, can be a nuisance.  <strong>install-font.sh</strong> takes
 418 care of all the details, including converting fonts to formats
 419 acceptable to <strong>grops</strong> and <strong>gropdf</strong>,
 420 creating and installing the groff fonts in the appropriate
 421 directories, updating the <strong>download</strong> files, and
 422 installing the original fonts in a system-wide directory, if
 423 desired.
 424 </p>
 425
 426 <div class="rule-long"><hr/></div>
 427
 428 <!-- Navigation links -->
 429 <table style="width: 100%; margin-top: 12px;">
 430 <tr>
 431   <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
 432   <td style="width: 20%; text-align: center;"><a href="#top">Top</a></td>
 433   <td style="width: 46%; text-align: right;"><a href="intro.html">Next: Introduction to mom</a></td>
 434 </tr>
 435 </table>
 436
 437 </div>
 438
 439 <div class="bottom-spacer"><br/></div>
 440
 441 </body>
 442 </html>