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