contrib/mom/momdoc/using.html

   1 <html>
   2 <head>
   3 <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
   4 <title>Using mom</title>
   5 </head>
   6 <body bgcolor="#dfdfdf">
   7
   8 <!====================================================================>
   9
  10 <a href="toc.html">Back to Table of Contents</a>
  11
  12 <a name="TOP"></a>
  13 <a name="USING">
  14         <h1 align="center"><u>USING MOM</u></h1>
  15 </a>
  16
  17 <a href="#USING_INTRO">Introduction</a>
  18 <br>
  19 <a href="#USING_MACROS">Inputting macros</a>
  20 <br>
  21 <a href="#USING_INVOKING">Invoking groff</a>
  22 <br>
  23 <a href="#USING_PREVIEWING">Previewing documents</a>
  24 <br>
  25 <hr>
  26 <h2><a name="USING_INTRO"><u>Introduction</u></a></h2>
  27
  28 As explained in the section
  29 <a href="intro.html#INTRO">What is mom?</a>,
  30 <strong>mom</strong> can be used in two ways: for straight typesetting
  31 or for document processing.  The difference between the two is
  32 that in straight typesetting, every macro is a literal
  33 typesetting instruction that determines precisely how text
  34 following it will look.  Document processing, on the other hand,
  35 uses markup &quot;tags&quot; (e.g. <kbd>.PP</kbd> for
  36 paragraphs, <kbd>.HEAD</kbd> for heads, <kbd>.FOOTNOTE</kbd>
  37 for footnotes, etc.) that make a lot of typesetting decisions
  38 automatically.
  39 <p>
  40 You tell <strong>mom</strong> that you want to use the document
  41 processing macros with the
  42 <a href="docprocessing.html#START">START</a>
  43 macro, explained below.  After <strong>START</strong>,
  44 <strong>mom</strong> determines the appearance of text following
  45 the markup tags automatically, although you, the user, can easily
  46 change how <strong>mom</strong> interprets the tags.  This gives you
  47 nearly complete control over the look and feel of your documents.
  48 In addition, the typesetting macros, in combination with document
  49 processing, let you meet all sorts of typesetting needs that just
  50 can't be covered by &quot;one macro fits all&quot; markup tags.
  51
  52 <a name="USING_MACROS">
  53         <h2><u>How to input mom's macros</u></h2>
  54 </a>
  55
  56 Regardless of which way you use <strong>mom</strong>, the
  57 following apply.
  58 <br>
  59 <ol>
  60         <li>You need a good text editor for inputting
  61                 <strong>mom</strong> files.
  62                 <p>
  63                 I cannot recommend highly enough that you use an
  64                 editor that lets you write syntax highlighting
  65                 rules for <strong>mom</strong>'s macros and
  66                 <a href="definitions.html#TERMS_INLINES">inline escapes</a>.
  67                 I use the vi clone called elvis, and find it a pure
  68                 joy in this regard.  Simply colorizing macros and
  69                 inlines to half-intensity is enough to make text stand
  70                 out clearly from formattting commands.
  71         <li>All <strong>mom</strong>'s macros begin with a period
  72                 (dot) and must be entered in upper case (capital)
  73                 letters.
  74         <li>Macro
  75                 <a href="definitions.html#TERMS_ARGUMENTS">arguments</a>
  76                 are separated from the macro itself by spaces.  Multiple
  77                 arguments to the same macro are separated from each
  78                 other by spaces.  Any number of spaces may be used.  All
  79                 arguments to a macro must appear on the same line as the
  80                 macro.
  81         <li>Any argument (except a
  82                 <a href="definitions.html#TERMS_STRINGARGUMENT">string argument</a>)
  83                 that is not a digit must be entered in upper case
  84                 (capital) letters.
  85         <li>Any argument that requires a plus or minus sign must
  86                 have the plus or minus sign prepended to the argument
  87                 with no intervening space (e.g. +2, -4).
  88         <li>Any argument that requires a
  89                 <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>
  90                 must have the unit appended directly to the argument,
  91                 with no intervening space (e.g. 4P, .5i, 2v).
  92         <li><a href="definitions.html#TERMS_STRINGARGUMENT">String arguments</a>,
  93                 in the sense that the term is used in this manual, must
  94                 be surrounded by double-quotes (&quot;text of
  95                 string&quot;).  Multiple string arguments are separated
  96                 from each other by spaces (each argument surrounded by
  97                 double-quotes, of course).
  98         <li>If a string argument, as entered in your text editor,
  99                 becomes uncomfortably long (i.e. runs longer than the
 100                 visible portion of your screen or window), you may break
 101                 it into two or more lines by placing the backslash
 102                 character (<kbd>\</kbd>) at the ends of lines to break
 103                 them up, like this:
 104         <p>
 105         <pre>
 106         .SUBTITLE "An In-Depth Consideration of the \
 107         Implications of Forty-Two as the Meaning of Life, \
 108         The Universe, and Everything"
 109         </pre>
 110 </ol>
 111
 112 It's important that formatted documents be easy to read/interpret
 113 when you're looking at them in a text editor.  One way to achieve
 114 this is to group macros that serve a similar purpose together, and
 115 separate them from other groups of macros with a blank comment line.
 116 In groff, that's done with <kbd>\#</kbd> on a line by itself.
 117 Consider the following, which is a template for starting the
 118 chapter of a book.
 119 <p>
 120 <pre>
 121         .TITLE   "My Pulizter Novel"
 122         .AUTHOR  "Joe Blow"
 123         .CHAPTER  1
 124         \#
 125         .DOCTYPE    CHAPTER
 126         .PRINTSTYPE TYPESET
 127         \#
 128         .FAM P
 129         .PS  10
 130         .LS  12
 131         \#
 132         .START
 133 </pre>
 134
 135 <a name="USING_INVOKING">
 136         <h2><u>Printing -- invoking groff with mom</u></h2>
 137 </a>
 138
 139 After you've finished your document, naturally you will want to
 140 print it.  This involves invoking groff from the command line.
 141 In all likelihood, you already know how to do this, but in case
 142 you don't, here are two common ways to do it.
 143 <p>
 144 <pre>
 145         groff -mom -l &lt;filename&gt;
 146         groff -mom &lt;filename&gt; | lpr
 147 </pre>
 148
 149 In the first, the <strong>-l</strong> option to groff tells
 150 groff to send the output to your printer.  In the second, you're
 151 doing the same thing, except you're telling groff to pipe the
 152 output to your printer.  Basically, they're the same thing.  The
 153 only advantage to the second is that your system may be set up
 154 to use something other than <strong>lpr</strong> as your print
 155 command, in which case, you can replace <strong>lpr</strong>
 156 with whatever is appropriate to your box.
 157 <p>
 158 Sadly, it is well beyond the scope of this manual to tell you
 159 how to set up a printing system.  See the README file for
 160 minimum requirements to run groff with <strong>mom</strong>.
 161
 162 <a name="USING_PREVIEWING">
 163         <h2><u>How to preview documents</u></h2>
 164 </a>
 165
 166 Other than printing out hard copy, there are two well-established
 167 methods for previewing your work.  Both assume you have a working
 168 X server.
 169 <p>
 170 Groff itself comes with a quick and dirty previewer called
 171 gxditview. Invoke it with
 172 <p>
 173 <pre>
 174         groff -X -mom &lt;filename&gt;
 175 </pre>
 176
 177 It's not particularly pretty, doesn't have many navigation
 178 options, requires a lot of work if you want to use other than
 179 the &quot;standard&quot; groff PostScript fonts, and occasionally
 180 has difficulty accurately reproducing some of
 181 <strong>mom</strong>'s macro effects
 182 (<a href="goodies.html#SMARTQUOTES">smartquotes</a>
 183 and
 184 <a href="goodies.html#LEADER">leaders</a>
 185 come to mind).  What it does have going for it is that it's fast and
 186 doesn't gobble up system resources.
 187 <p>
 188 A surer way to preview documents is with <strong>gv</strong>
 189 (ghostview).  This involves processing documents with groff,
 190 directing the output to a temporary (PostScript) file, then opening
 191 the temporary file in <strong>gv</strong>.  While that may sound
 192 like a lot of work, I've set up my editor (elvis) to do it for me.
 193 Whenever I'm working on a document that needs previewing/checking,
 194 I fire up <strong>gv</strong> with the &quot;Watch File&quot;
 195 option turned on.  To look at the file, I tell elvis to process
 196 it (with groff) and send it to the temporary file (<kbd>groff
 197 -mom filename &gt; filename.ps</kbd>), then open the file inside
 198 <strong>gv</strong>.  Ever after, when I want to look at any changes
 199 I make, I simply tell elvis to work his magic again.  The Watch File
 200 option in <strong>gv</strong> registers that the file has changed,
 201 and automatically loads the new version.  Voilà! -- instant previewing.
 202
 203 <p>
 204 <hr>
 205 <a href="toc.html">Back to Table of Contents</a>
 206 </body>
 207 </html>