contrib/mom/momdoc/using.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>Using mom</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="typesetting.html#top">Next: The typesetting macros</a></td>
  38   </tr>
  39   </table>
  40
  41 <h1 id="using" class="docs">Using mom</h1>
  42
  43 <div style="text-align: left; margin-left: 33%">
  44 <ul class="no-enumerator" style="margin-left: -2.5em;">
  45   <li><a href="#using-intro">Introduction</a></li>
  46   <li><a href="#using-macros">How to input mom&#8217;s macros</a></li>
  47   <li><a href="#viewing">Processing and viewing documents</a>
  48     <ul>
  49     <li class="item"><a href="#pdf">Mom and PDF</a></li>
  50     <li class="item"><a href="#pdfmom">pdfmom</a></li>
  51   </ul></li>
  52   <li><a href="#previewing">Automatic previewing of documents</a></li>
  53 </ul>
  54 </div>
  55
  56 <div class="rule-short" style="margin-top: 18px;"><hr/></div>
  57
  58 <h2 id="using-intro" class="docs">Introduction</h2>
  59
  60 <p>
  61 As explained in the section
  62 <a href="intro.html#top">What is mom?</a>,
  63 mom can be used in two ways: for straightforward typesetting or for
  64 document processing.  The difference between the two is that in
  65 straightforward typesetting, every macro is a literal instruction
  66 that determines precisely how text following it will look.  Document
  67 processing, on the other hand, uses markup tags (e.g. <kbd>.PP</kbd>
  68 for paragraphs, <kbd>.HEADING</kbd> for different levels of heads,
  69 <kbd>.FOOTNOTE</kbd> for footnotes, etc.) that perform typesetting
  70 operations automatically.
  71 </p>
  72
  73 <p>
  74 You tell mom that you want to use the document processing macros
  75 with the
  76 <a href="docprocessing.html#start"><kbd>START</kbd></a>
  77 macro.  After <kbd>START</kbd>, mom determines the appearance of
  78 text following the markup tags automatically, although you, the
  79 user, can easily change how the tags are interpreted.
  80 </p>
  81
  82 <h2 id="using-macros" class="docs">How to input mom&#8217;s macros</h2>
  83
  84 <p>
  85 Regardless of whether you&#8217;re preparing a term paper or making a
  86 flyer for your lost dog, the following apply.
  87 </p>
  88
  89 <ol style="margin-top: -.5em; margin-bottom: -.5em;">
  90   <li>
  91     You need a good text editor for inputting mom files.
  92     <br/>
  93     <span style="display: block; margin-top: .25em; margin-bottom: .5em;">
  94     I cannot recommend highly enough that you use an editor that
  95     lets you write syntax highlighting rules for mom&#8217;s
  96     macros and
  97     <a href="definitions.html#inlines">inline escapes</a>.
  98     Simply colourizing macros and inlines to half-intensity can be
  99     enough to make text stand out clearly from formatting commands.
 100     Mom herself comes with a complete set of syntax highlighting
 101     rules for the vim editor.
 102     </span>
 103   </li>
 104   <li>
 105     Macros begin with a period (dot) at the left margin of your text
 106     editor's screen, and must be entered in upper case (capital)
 107     letters.
 108   </li>
 109   <li>
 110     Macro
 111     <a href="definitions.html#arguments">arguments</a>
 112     are separated from the macro itself by spaces.  Multiple
 113     arguments to the same macro are separated from each
 114     other by spaces.  Any number of spaces may be used.
 115   </li>
 116   <li>
 117     Arguments to a macro must appear on the same line as the
 118     macro.
 119     <br/>
 120     <span style="display: block; margin-top: .25em; margin-bottom: .5em;">
 121     If the argument list is very long, you may use the
 122     backslash character (<kbd>\</kbd>) to break the line visually.
 123     From groff&#8217;s point of view, the backslash and newline are
 124     invisible.  Thus, for example,
 125     <span class="pre" style="margin-bottom: -2.25em">
 126   .HEADING_STYLE 1 FAMILY Garamond FONT B SIZE +2
 127     </span>
 128     and
 129     <span class="pre" style="margin-bottom: -2.25em">
 130   .HEADING_STYLE 1 \
 131    FAMILY Garamond \
 132    FONT B \
 133    SIZE +2
 134     </span>
 135     are exactly equivalent.
 136   </li>
 137   <li>
 138     Any argument (except a
 139     <a href="definitions.html#stringargument">string argument</a>)
 140     that is not a digit must be entered in upper case
 141     (capital) letters.
 142   </li>
 143   <li>
 144     Any argument that requires a plus or minus sign must
 145     have the plus or minus sign prepended to the argument
 146     with no intervening space (e.g. <kbd>+2</kbd>).
 147   </li>
 148   <li>
 149     Any argument that requires a
 150     <a href="definitions.html#unitofmeasure">unit of measure</a>
 151     must have the unit appended directly to the argument, with no
 152     intervening space (e.g. <kbd>.5i</kbd>).
 153   </li>
 154   <li>
 155     <a href="definitions.html#stringargument">String arguments</a>,
 156     in the sense of this manual, must be surrounded by double-quotes
 157     (e.g., <kbd>"text"</kbd>).  Multiple
 158     string arguments are separated from each other by spaces (with
 159     each argument surrounded by double-quotes).
 160     <br/>
 161     <span style="display: block; margin-top: .25em; margin-bottom: .5em;">
 162     If a string argument becomes
 163     uncomfortably long, you may break it into two or more lines
 164     with the backslash character.
 165     <span class="pre">
 166   .SUBTITLE "An In-Depth Consideration of the \
 167   Implications of Forty-Two as the Answer to Life, \
 168   The Universe, and Everything"
 169     </span>
 170   </li>
 171 </ol>
 172
 173 <div class="box-tip">
 174 <p class="tip">
 175 <span class="tip">Tip:</span>
 176 It&#8217;s important that your documents be easy to read and
 177 understand in a text editor.  One way to achieve this is to group
 178 macros that serve a similar purpose together, and separate them from
 179 other groups of macros with a comment line.  In groff, that&#8217;s
 180 done with <kbd>\#</kbd> (backslash-pound) or <kbd>.\"</kbd>
 181 (period-backslash-doublequote) on a line by itself.  Either
 182 instructs groff to ignore the remainder of the line, which may or
 183 may not contain text.  Consider the following, which is a template
 184 for starting the chapter of a book.
 185 <br/>
 186 <span class="pre-in-pp">
 187   \# Reference/meta-data
 188   .TITLE   "My Pulitzer Novel"
 189   .AUTHOR  "Joe Blow"
 190   .CHAPTER  1
 191   \# Template
 192   .DOCTYPE    CHAPTER
 193   .PRINTSTYLE TYPESET
 194   \# Type style
 195   .FAM     P
 196   .PT_SIZE 10
 197   .LS      12
 198   \#
 199   .START
 200 </span>
 201 You may also, if you wish, add a comment to the end of a line with
 202 <kbd>\"</kbd> (no period), like this:
 203 <br/>
 204 <span class="pre-in-pp">
 205   .FAMILY P \" Maybe Garamond instead?
 206 </span>
 207 </p>
 208 </div>
 209
 210 <h2 id="viewing" class="docs">Processing and viewing documents</h2>
 211
 212 <p>
 213 The most basic command-line usage for processing a file formatted
 214 with the mom macros is
 215 <br/>
 216 <span class="pre-in-pp">
 217   groff -mom filename.mom &gt; filename.ps
 218 </span>
 219 which processes the .mom file and dumps the output into a
 220 viewable/printable PostScript file.
 221 </p>
 222
 223 <h3 id="pdf" class="docs">Mom and PDF</h3>
 224
 225 <p>
 226 Adobe's Portable Document Format (PDF) has largely supplanted
 227 PostScript, of which it is a subset, as the standard for typeset
 228 documents.  While printed versions of documents in either format
 229 will be identical, PDF documents, when viewed at the screen, may
 230 also contain clickable links and a number of other special features.
 231 </p>
 232
 233 <p>
 234 As of version 2.0, mom supports full PDF integration.  The creation
 235 and processing of mom files into PostScript documents remains
 236 unchanged from 1.x, but the expected and recommended format of final
 237 documents is now PDF.
 238
 239 <p>
 240 The manual,
 241 <a href="http://www.schaffter.ca/mom/pdf/mom-pdf.pdf"><span class="book-title">Producing PDFs with groff and mom</span></a>,
 242 explains and demonstrates the PDF-specific macros that are available
 243 in mom, as well as the use of <strong>pdfmom</strong>, the
 244 recommended way to process mom files.
 245 </p>
 246
 247 <h4 id="pdfmom" class="docs">pdfmom</h4>
 248
 249 <p>
 250 Groff provides more than one way to generate PDF documents,
 251 but when processing files formatted with the mom macros,
 252 <strong>pdfmom</strong> is the recommended and most robust way to do
 253 it:
 254 <br/>
 255 <span class="pre-in-pp">
 256   pdfmom filename.mom &gt; filename.pdf
 257 </span>
 258 <strong>pdfmom</strong> is a wrapper around groff, and accepts all
 259 groff's command-line options as listed in the groff manpage.
 260 Full usage is explained in the manual,
 261 <a href="http://www.schaffter.ca/mom/pdf/mom-pdf.pdf"><span class="book-title">Producing PDFs with groff and mom</span></a>.
 262 </p>
 263
 264 <p>
 265 PDF links in a document, including linked entries in the
 266 Table of Contents, are identified by colour.  When printing
 267 documents with links, you will most likely not want the link
 268 text coloured.  The groff option, <kbd>-c</kbd>, disables colour
 269 throughout a document; thus, when preparing a document for printing,
 270 you should use:
 271 <br/>
 272 <span class="pre-in-pp">
 273   pdfmom -c filename.mom  &gt; filename.pdf
 274 </span>
 275 <strong>pdfmom</strong> tends to produce large files.  You may
 276 reduce their size by piping them through ps2pdf:
 277 <br/>
 278 <span class="pre-in-pp">
 279   pdfmom -c filename.mom  | ps2pdf - filename.pdf
 280 </span>
 281 Be aware, though, that files piped through ps2pdf will lose some pdf
 282 metadata, notably the document window title set with PDF_TITLE.
 283 </p>
 284
 285 <h2 id="previewing" class="docs">Automatic previewing of documents</h2>
 286
 287 <p>
 288 Most PDF viewers have a &#8220;Watch File&#8221; option, which
 289 automaticaly updates a displayed document whenever there&#8217;s
 290 a change.  This is useful when preparing documents that require
 291 judgment calls.  I recommend creating a keymapping in your
 292 text editor that both saves the mom file and processes it with
 293 <strong>pdfmom</strong>.  The displayed PDF then automatically
 294 reflects whatever changes you save to the mom file.
 295 </p>
 296
 297 <div class="rule-long"><hr/></div>
 298
 299 <!-- Navigation links -->
 300 <table style="width: 100%; margin-top: 12px;">
 301   <tr>
 302     <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
 303     <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td>
 304     <td style="width: 33%; text-align: right;"><a href="typesetting.html#top">Next: The typesetting macros</a></td>
 305 </tr>
 306 </table>
 307
 308 </div>
 309
 310 <div class="bottom-spacer"><br/></div>
 311
 312 </body>
 313 </html>