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-2014 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 the
  11 Invariant Sections being this comment section, with no Front-Cover
  12 Texts, and with no Back-Cover 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 Table of contents</a></li>
  58   </ul></li>
  59   <li><a href="#pdfmom">The <strong>pdfmom</strong> wrapper around groff</a></li>
  60   <li><a href="#install-font">The <strong>install-font.sh</strong> script</a></li>
  61 </ol>
  62 </div>
  63
  64 <div class="rule-medium"><hr/></div>
  65
  66 <h2 id="prefatory" class="docs">1. Prefatory comments</h2>
  67
  68 <p>
  69 Version 2.0 comes about as a result of Deri James&#8217;
  70 contribution of <strong>gropdf</strong> to <strong>groff</strong>,
  71 and his subsequent work integrating the device with
  72 <strong>mom</strong>.
  73 </p>
  74
  75 <p>
  76 Whereas the 1.x releases were oriented toward PostScript output,
  77 2.0 focuses on PDF output, a bias reflected throughout this
  78 documentation.  Users are strongly encouraged to process their files
  79 with
  80 <a href="#pdfmom"><strong>pdfmom</strong></a>,
  81 a wrapper around <strong>groff&nbsp;-Tpdf</strong>, in order to take
  82 full advantage of all PDF has to offer.
  83 </p>
  84
  85 <p>
  86 While portions of mom have been rewritten, and new features
  87 introduced, 2.0 is backwardly compatible with 1.x releases.  Changes
  88 are either transparent, or accompanied by notifications on stderr.
  89 </p>
  90
  91 <p>
  92 The implementation of nested heads has been completely rethought,
  93 as has the manner of styling of them.  There are no limits on
  94 how deep the nesting can go.  The 1.x macros <kbd>HEAD</kbd>,
  95 <kbd>SUBHEAD</kbd>, and <kbd>SUBSUHEAD</kbd> may still be used, but
  96 must be re-designed with the new <kbd>HEADING_STYLE</kbd> macro
  97 if their 1.x defaults are not desired.
  98 </p>
  99
 100 <p>
 101 In conjunction with the changes to nested heads, Table of Contents
 102 generation has also been rethought.  Greater flexibility in the
 103 inclusion of toc entry numbering been added.  Like nested heads,
 104 there&#8217;s a new macro, <kbd>TOC_ENTRY_STYLE</kbd>, that permits
 105 styling of each level in the toc hierarchy separately.  The default
 106 overall layout has also been significantly improved, achieving a
 107 level of typographical elegance formerly lacking.  Best of all, the
 108 Table of Contents can now be repositioned to the correct spot at the
 109 top of a document from within the mom source file.
 110 </p>
 111
 112 <p>
 113 When mom files are processed with <strong>pdfmom</strong>, a PDF
 114 outline for the Contents panel of PDF viewers is automatically
 115 generated.  In addition, entries in the Table of Contents
 116 are clickable links when a document is viewed at the screen.
 117 <strong>pdfmom</strong> also permits setting a document&#8217;s
 118 papersize within the source file without the corresponding need for
 119 <kbd>-P-p&lt;papersize&gt;</kbd> on the command line.
 120 </p>
 121
 122 <p>
 123 Lastly, while not strictly part of mom, a bash script,
 124 <strong>install-font.sh</strong>, has been posted at the
 125 <a href="http://www.schaffter.ca/mom/">mom site</a>.
 126 The script significantly eases the installation of new
 127 groff families and fonts, with conversion to .pfa
 128 and .t42 being performed by <strong>fontforge</strong>.
 129 </p>
 130
 131 <h2 id="differences" class="docs">2. Differences between v2.0 and v1.x</h2>
 132
 133 <h3 id="pdf-support" class="docs">2.1. PDF support</h3>
 134
 135 <p>
 136 PDF support has been added, with features including the automatic
 137 generation of PDF outlines, embedding of images in PDF format (via
 138 the
 139 <a href="images.html#pdf-image">PDF_IMAGE</a>
 140 macro) and PDF linking (internal and external).
 141 </p>
 142
 143 <h4 id="mom-pdf" class="docs">2.1.1. Producing PDFs with groff and mom</h4>
 144
 145 <p>
 146 A manual in PDF format,
 147 <span class="book-title">Producing PDFs with groff and mom</span>,
 148 has been added to the documentation.  The file,
 149 <strong>mom-pdf.pdf</strong> can be found in
 150 <br/>
 151 <span class="pre-in-pp">
 152   /usr/local/share/doc/groff-1.21/pdf/
 153 </span>
 154 or
 155 <br/>
 156 <span class="pre-in-pp">
 157   /usr/share/doc/groff-base/pdf/
 158 </span>
 159 or at
 160 <br/>
 161 <span class="pre-in-pp">
 162   <a href="http://www.schaffter.ca/mom/momdoc/mom-pdf.pdf">http://www.schaffter.ca/mom/momdoc/mom-pdf.pdf</a>
 163 </span>
 164 PDF usage, and all associated macros except
 165 <a href="#pdf-image">PDF_IMAGE</a>,
 166 are fully explained in the manual, which should be considered an
 167 integral part of the present documentation.  In addition, the mom
 168 source file for the manual can be found in
 169 <br/>
 170 <span class="pre-in-pp">
 171   /usr/local/share/doc/groff-1.21/examples/mom
 172 </span>
 173 or
 174 <br/>
 175 <span class="pre-in-pp">
 176   /usr/share/doc/groff-base/examples/mom/
 177 </span>
 178 and provides an excellent demonstration of mom usage.
 179 </p>
 180
 181 <h4 id="pdf-image" class="docs">2.1.2. PDF_IMAGE</h4>
 182
 183 <p>
 184 A new macro for embedding PDF images has been added,
 185 <a href="images.html#pdf-image"><kbd>PDF_IMAGE</kbd></a>.
 186 </p>
 187
 188 <p>
 189 <kbd>PDF_IMAGE</kbd> functions similarly to <kbd>PSPIC</kbd> and
 190 accepts the same arguments.  Differences in implementation are that
 191 PDF_IMAGE requires the image dimensions (the bounding box) to be
 192 supplied.  Instructions for getting the bounding box are included in
 193 the documentation entry for PDF_IMAGE.  Two additional options,
 194 <kbd>SCALE</kbd> and <kbd>ADJUST</kbd>, allow scaling of the image
 195 and optical centering.
 196 </p>
 197
 198 <h3 id="covers" class="docs">2.2. Covers</h3>
 199
 200 <p>
 201 Arguments to
 202 <a href="cover.html#cover"><kbd>COVER</kbd></a>
 203 and
 204 <a href="cover.html#doc-cover"><kbd>DOC_COVER</kbd></a>
 205 may now be given in any order.
 206 </p>
 207
 208 <h3 id="headings" class="docs">2.3. Headings</h3>
 209
 210 <p>
 211 The 1.x macros
 212 <br/>
 213 <span class="pre-in-pp">
 214   HEAD SUBHEAD SUBSUBHEAD
 215 </span>
 216 are now deprecated and have been replaced by a single macro,
 217 <br/>
 218 <span class="pre-in-pp">
 219   <a href="docelement.html#heading"><kbd>HEADING &lt;n&gt;</kbd></a>
 220 </span>
 221 where <kbd>&lt;n&gt;</kbd> is the heading level.  The deprecated
 222 macros may still be used, and conform in style to their original
 223 defaults; they are, however, wrappers around
 224 <kbd>HEADING</kbd> levels 1 - 3.
 225 Both the wrappers and <kbd>HEADING</kbd> itself can take a
 226 <kbd>NAMED &lt;id&gt;</kbd> argument, specifying a PDF link
 227 destination.
 228 </p>
 229
 230 <p>
 231 Styling of headings is managed by a single macro,
 232 <br/>
 233 <span class="pre-in-pp">
 234   <a href="docelement.html#heading"><kbd>HEADING_STYLE &lt;n&gt;</kbd></a>
 235 </span>
 236 where <kbd>&lt;n&gt;</kbd> conforms to a <kbd>HEADING</kbd> level.
 237 The control macros for HEAD, SUBHEAD and SUBSUBHEAD have been
 238 removed.  Users wishing to style the wrappers must use
 239 <kbd>HEADING_STYLE</kbd>.
 240 </p>
 241
 242 <p>
 243 <kbd>PARAHEAD</kbd> is no longer valid.  Paragraph heads in
 244 2.0 are created by passing the <kbd>PARAHEAD</kbd> argument to
 245 <kbd>.HEADING</kbd>.  Mom will abort with an informational message
 246 whenever she encounters <kbd>.PARAHEAD</kbd>.
 247 </p>
 248
 249 <h3 id="margin-notes" class="docs">2.4. Margin notes</h3>
 250
 251 <p>
 252 The macro for setting margin note parameters,
 253 <a href="docelement.html#mn-init"><kbd>MN_INIT</kbd></a>,
 254 has been re-written such that each parameter now has the form
 255 <br/>
 256 <span class="pre-in-pp">
 257   &lt;PARAMETER&gt; &lt;value&gt;
 258 </span>
 259 This differs from 1.x where parameters were entered without a
 260 preceding <kbd>&lt;PARAMETER&gt;</kbd> flag.  Parameters may be
 261 entered in any order.  Any that are skipped are set to default
 262 values.  Documents created with 1.x will have to have their
 263 <kbd>MN_INIT</kbd> updated accordingly.
 264 </p>
 265
 266 <h3 id="floats" class="docs">2.5. Floats</h3>
 267
 268 <p>
 269 A
 270 <a href="images.html#floats-intro">FLOAT</a>
 271 macro has been added, which functions similarly to the <kbd>ms</kbd>
 272 macros&#8217; <kbd>.KF/.KE</kbd>, ie the contents of the float are
 273 output immediately if there&#8217;s room on the page; otherwise,
 274 normal text processing continues and the contents are output at the
 275 top of the next page.  An <kbd>ADJUST</kbd> argument to FLOAT allows
 276 for optical centering.
 277 </p>
 278
 279 <h3 id="table-of-contents" class="docs">2.6. Table of contents</h3>
 280
 281 <p>
 282 The default look of the Table of Contents has been overhauled to
 283 produce a more typographically pleasing result.  All control macros
 284 for TOC title and entry styles have been removed, replaced by the
 285 macros
 286 <br/>
 287 <span class="pre-in-pp">
 288   <a href="tables-of-contents.html#toc-title-style">TOC_TITLE_STYLE</a>
 289 </span>
 290 and
 291 <br/>
 292 <span class="pre-in-pp">
 293   <a href="tables-of-contents.html#toc-title-style">TOC_ENTRY_STYLE &lt;n&gt;</a>
 294 </span>
 295 where <kbd>&lt;n&gt;</kbd> corresponds to a <kbd>HEADING</kbd>
 296 level.  Both macros permit setting any or all of the style
 297 parameters for TOC titles (ie chapters or major sections/divisions
 298 of a collated document) and TOC entries (nested heading levels) at
 299 once.  Documents created with 1.x that contain TOCs will need to
 300 have their TOC style updated if the new defaults are unsatisfactory.
 301 </p>
 302
 303 <p>
 304 Two new TOC control macros have been added,
 305 <br/>
 306 <span class="pre-in-pp">
 307   <a href="tables-of-contents.html#space-toc-items">SPACE_TOC_ITEMS</a>
 308 </span>
 309 and
 310 <br/>
 311 <span class="pre-in-pp">
 312   <a
 313   href="tables-of-contents.html#auto-relocate-toc">AUTO_RELOCATE_TOC</a>
 314 </span>
 315 <kbd>SPACE_TOC_ITEMS</kbd> groups TOC entry levels and separates
 316 them with a discrete amount of whitespace.  This leads to improved
 317 legibility, and is highly recommended even though it is not
 318 mom&#8217;s default. <kbd>AUTO_RELOCATE_TOC</kbd> intelligently
 319 repositions the Table of Contents to the top of a document when
 320 the mom source file is processed with
 321 <a href="pdfmom"><strong>pdfmom</strong></a>.
 322 </p>
 323
 324 <h2 id="pdfmom" class="docs">3. pdfmom</h2>
 325
 326 <p>
 327 Deri James has provided <strong>pdfmom</strong>, a wrapper around
 328 groff that processes mom source files with all the PDF bells and
 329 whistles.  Its use is highly recommended.  Usage is explained in the
 330 manual,
 331 <a href="http://www.schaffter.ca/mom/pdf/mom-pdf.pdf"><span class="book-title">Producing PDFs with groff and mom</span></a>.
 332 A significant convenience of <strong>pdfmom</strong> is that it can,
 333 with the <kbd>-Tps</kbd> flag, be used to pass processing over to Keith
 334 Marshall&#8217;s <strong>pdfroff</strong>.  This is useful when
 335 processing files that contain PostScript images embedded with
 336 <kbd>PSPIC</kbd>. <strong>pdfmom</strong>, without the flag, uses
 337 groff&#8217;s PDF device (<strong>gropdf</strong>), which only
 338 recognizes PDF images that have been embedded with
 339 <a href="images.html#pdf-image"><kbd>PDF_IMAGE</kbd></a>.
 340 </p>
 341
 342 <h2 id="install-font" class="docs">4. install-font.sh</h2>
 343
 344 <p>
 345 A bash script, <strong>install-font.sh</strong>, has been posted at the
 346 <a href="http://www.schaffter.ca/mom/mom-01.html">mom site</a>.
 347 There&#8217;s nothing mom-specific about the script, and it is not
 348 an official part of groff.
 349 </p>
 350
 351 <p>
 352 Installing groff fonts is a multi-step procedure, which, while not
 353 difficult, can be a nuisance.  <strong>install-font.sh</strong> takes
 354 care of all the details, including converting fonts to formats
 355 acceptable to <strong>grops</strong> and <strong>gropdf</strong>,
 356 creating and installing the groff fonts in the appropriate
 357 directories, updating the <strong>download</strong> files, and
 358 installing the original fonts in a system-wide directory, if
 359 desired.
 360 </p>
 361
 362 <div class="rule-long"><hr/></div>
 363
 364 <!-- Navigation links -->
 365 <table style="width: 100%; margin-top: 12px;">
 366 <tr>
 367   <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
 368   <td style="width: 20%; text-align: center;"><a href="#top">Top</a></td>
 369   <td style="width: 46%; text-align: right;"><a href="intro.html">Next: Introduction to mom</a></td>
 370 </tr>
 371 </table>
 372
 373 </div>
 374
 375 <div class="bottom-spacer"><br/></div>
 376
 377 </body>
 378 </html>
 379 <!-- vim: fileencoding=utf-8: nomodified: -->