contrib/groff/contrib/mom/momdoc/using.html

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