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