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> 12<a href="definitions.html#TOP">Prev</a> 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 31As 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 34or for document processing. The difference between the two is 35that in straight typesetting, every macro is a literal 36typesetting instruction that determines precisely how text 37following it will look. Document processing, on the other hand, 38uses markup "tags" (e.g. <kbd>.PP</kbd> for 39paragraphs, <kbd>.HEAD</kbd> for heads, <kbd>.FOOTNOTE</kbd> 40for footnotes, etc.) that make a lot of typesetting decisions 41automatically. 42<p> 43You tell <strong>mom</strong> that you want to use the document 44processing macros with the 45<a href="docprocessing.html#START">START</a> 46macro, explained below. After <strong>START</strong>, 47<strong>mom</strong> determines the appearance of text following 48the markup tags automatically, although you, the user, can easily 49change how <strong>mom</strong> interprets the tags. This gives you 50nearly complete control over document design. In addition, the 51typesetting macros, in combination with document processing, let you 52meet all sorts of typesetting needs that just can't be covered by 53"one macro fits all" markup tags. 54<p> 55<a name="USING_MACROS"> 56 <h2><u>How to input mom's macros</u></h2> 57</a> 58 59Regardless of which way you use <strong>mom</strong>, the 60following 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 ("text of 98 string"). 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 115It's important that formatted documents be easy to read/interpret 116when you're looking at them in a text editor. One way to achieve 117this is to group macros that serve a similar purpose together, and 118separate them from other groups of macros with a blank comment line. 119In groff, that's done with <kbd>\#</kbd> on a line by itself. 120Consider the following, which is a template for starting the 121chapter 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 142After you've finished your document, naturally you will want to 143print it. This involves invoking groff from the command line. 144In all likelihood, you already know how to do this, but in case 145you don't, here are two common ways to do it. 146<p> 147<pre> 148 groff -mom -l <filename> 149 groff -mom <filename> | lpr 150</pre> 151 152In the first, the <strong>-l</strong> option to groff tells 153groff to send the output to your printer. In the second, you're 154doing the same thing, except you're telling groff to pipe the 155output to your printer. Basically, they're the same thing. The 156only advantage to the second is that your system may be set up 157to use something other than <strong>lpr</strong> as your print 158command, in which case, you can replace <strong>lpr</strong> 159with whatever is appropriate to your box. 160<p> 161Sadly, it is well beyond the scope of this manual to tell you 162how to set up a printing system. See the README file for 163minimum requirements to run groff with <strong>mom</strong>. 164<p> 165<strong>NOTE FOR ADVANCED USERS:</strong> I've sporadically had groff 166choke on perfectly innocent sourced files within <strong>mom</strong> 167documents. You'll know you have this problem when groff complains that 168it can't find the sourced file even when you can plainly see that the 169file exists, and that you've given <code>.so</code> the right path and 170name. Should this happen, pass groff the <code>-U</code> (unsafe mode) 171option along with the other options you require. Theoretically, you 172only need <code>-U</code> with <code>.open, .opena, .pso, .sy,</code> 173and <code>.pi</code>, however reality seems, at times, to dictate 174otherwise. 175<p> 176<a name="USING_PREVIEWING"> 177 <h2><u>How to preview documents</u></h2> 178</a> 179 180Other than printing out hard copy, there are two well-established 181methods for previewing your work. Both assume you have a working 182X server. 183<p> 184Groff itself comes with a quick and dirty previewer called 185gxditview. Invoke it with 186<p> 187<pre> 188 groff -X -mom filename 189</pre> 190 191It's not particularly pretty, doesn't have many navigation 192options, requires a lot of work if you want to use other than 193the "standard" groff PostScript fonts, and occasionally 194has difficulty accurately reproducing some of 195<strong>mom</strong>'s macro effects 196(<a href="goodies.html#SMARTQUOTES">smartquotes</a> 197and 198<a href="goodies.html#LEADER">leaders</a> 199come to mind). What it does have going for it is that it's fast and 200doesn't gobble up system resources. 201<p> 202A surer way to preview documents is with <strong>gv</strong> 203(ghostview). This involves processing documents with groff, 204and directing the output to a PostScript file, like this, 205<p> 206<pre> 207 groff -mom filename > filename.ps 208</pre> 209then opening .ps file in <strong>gv</strong>. 210<p> 211While 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 213needs previewing/checking, I fire up <strong>gv</strong> with the 214"Watch File" option turned on. To look at the file, I 215tell elvis to process it (with groff) and send it to a temporary 216file (<kbd>groff -mom filename > filename.ps</kbd>), then open 217the file inside <strong>gv</strong>. Ever after, when I want to 218look at any changes I make, I simply tell elvis to work his magic 219again. The Watch File option in <strong>gv</strong> registers that 220the file has changed, and automatically loads the new version. 221Voil�! --instant previewing. 222 223<p> 224<hr> 225<a href="typesetting.html#TOP">Next</a> 226<a href="definitions.html#TOP">Prev</a> 227<a href="#TOP">Top</a> 228<a href="toc.html">Back to Table of Contents</a> 229</body> 230</html> 231