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