contrib/groff/contrib/mom/momdoc/intro.html

   1 <html>
   2 <head>
   3 <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
   4 <title>What is mom?</title>
   5 </head>
   6 <body bgcolor="#dfdfdf">
   7
   8 <!====================================================================>
   9
  10 <a href="definitions.html#TOP">Next</a>&nbsp;&nbsp;
  11 <a href="toc.html">Back to Table of Contents</a>
  12
  13 <a name="TOP"></a>
  14 <a name="INTRO">
  15         <h1 align="center"><u>WHAT IS MOM?</u></h1>
  16 </a>
  17
  18 <a href="#INTRO_INTRO">Who is mom meant for?</a>
  19 <br>
  20 <a href="#INTRO_TYPESETTING">Typesetting with mom</a>
  21 <br>
  22 <a href="#INTRO_DOCPROCESSING">Document processing with mom</a>
  23 <br>
  24 <a href="#INTRO_PHILOSOPHY">Mom's philosophy</a>
  25 <br>
  26 <a href="#INTRO_DOCUMENTATION">A note on mom's documentation</a>
  27 <br>
  28 <a href="#MACRO_ARGS">How to read macro arguments</a>
  29
  30 <h2><a name="INTRO_INTRO"><u>Who is mom meant for?</u></a></h2>
  31
  32 <strong>Mom</strong> (&quot;my own macros&quot;, &quot;my other
  33 macros&quot;, &quot;maximum overdrive macros&quot;...) is a macro set for
  34 groff, designed to format documents for PostScript output.
  35 She's aimed at three kinds of users:
  36 <br>
  37 <ol>
  38         <li>typesetters who suspect groff might be &quot;the right
  39                 tool for the job&quot; but who are
  40                 frustrated/intimidated by groff's terse, geeky,
  41                 not-always-typographically-intuitive
  42                 <a href="definitions.html#TERMS_PRIMITIVES">primitives</a>;
  43         <br>
  44         <li>non-scientific writers (novelists, short story writers,
  45                 journalists, students) who just want their work to
  46                 look good;
  47         <br>
  48         <li>newbies to computer typesetting, document processing, or
  49                 groff who need a well-documented macro set to help them get
  50                 started.
  51 </ol>
  52 <p>
  53 As might be infered from the above, <strong>mom</strong> is two macro
  54 packages in one: a set of typesetting macros, and a set of document
  55 processing macros.  The typesetting macros govern the physical
  56 aspects of page layout and provide sane, comprehensible control over
  57 typographic refinements.  The document processing macros let you focus
  58 on a document's content and logical structure without worrying about
  59 typesetting or page layout at all.
  60 <p>
  61 Because <strong>mom</strong> provides both typesetting and document
  62 processing macros, it's safe to say she blurs the distinction between
  63 document processing and document design.  While her basic document style
  64 comes with pretty spiffy defaults (okay -- change &quot;spiffy&quot;
  65 to &quot;typographically professional&quot;), you can easily control
  66 how all the various document elements look: titles, page headers and
  67 footers, page numbering, heads, subheads, footnotes and so on can be
  68 made to come out exactly the way you want.  And should you need precise
  69 typographic control over elements in a document that fall outside the
  70 range of <strong>mom</strong>'s document element tags, you don't have to
  71 read up on groff
  72 <a href="definitions.html#TERMS_PRIMITIVES">primitives</a>
  73 in order to accomplish what you want; the typesetting macros take
  74 care of that.
  75
  76 <a name="INTRO_TYPESETTING">
  77         <h2><u>Typesetting with mom</u></h2>
  78 </a>
  79
  80 <strong>Mom</strong>'s typesetting macros control the basic parameters
  81 of type: margins, line length, type family, font, point size,
  82 linespacing, and so on.  In addition, they allow you to move around
  83 on the page horizontally and vertically, and to set up tabs, indents,
  84 and columns.  Finally, they let you adjust such typographic details as
  85 justification style, letter spacing, word spacing, hyphenation, and
  86 kerning.
  87
  88 <p>
  89 In terms of typographic control, these macros resemble the
  90 commands used on dedicated typesetting computers like Compugraphics and
  91 Linotronics.  Most of them simply give access to groff's typesetting
  92 primitives in a way that's consistent and easy to use.  A few of
  93 them (tabs and indents, for example) handle fundamental typesetting
  94 requirements in ways radically different from groff primitives.
  95
  96 <p>
  97 With <strong>mom</strong>'s typesetting macros, you can, if you wish,
  98 create individual output pages that you design from the ground up.
  99 Provided you have not signalled to <strong>mom</strong> that you
 100 want document processing (via the
 101 <a href="docprocessing.html#START">START</a>
 102 macro; see below), every macro is a literal command that remains in
 103 effect until you modify it or turn it off.  This means that if you
 104 want to create flyers, document covers, surveys, tabulated forms,
 105 curricula vitae and so on, you may do so in the good old-fashioned
 106 way: one step at a time with complete control over every element on
 107 the page.
 108 <p>
 109 Years of reading various mailing lists dealing with computer
 110 typesetting (groff, TeX, and friends) have convinced me that no progam
 111 can ever replace the human eye and human input when it comes to high
 112 quality typesetting.  As of this writing, a thread on the subject of
 113 &quot;micro typography&quot; in groff has been going on for nearly a
 114 month.  The reason for the lengthy thread is obvious; words and
 115 punctuation on the printed page are too variable, too fluid, to be
 116 rendered flawlessly by any algorithm, no matter how clever.  (For
 117 whatever it's worth, a similar problem exists with engraving musical
 118 scores by computer.)
 119 <p>
 120 <strong>Mom</strong> does not try to solve the problems posed by
 121 things like hanging punctuation, left-margin adjustments for those
 122 annoying &quot;space-y&quot; upper case letters like T and W, and
 123 so on.  She merely tries to provide tools that allow knowledgeable
 124 typesetters to come up with solutions to these problems
 125 in ways that are somewhat easier and more intuitive than manipulating
 126 groff at the
 127 <a href="definitions.html#TERMS_PRIMITIVES">primtive</a>
 128 level.  As a professional typesetter of more than two decades, and a
 129 writer, I have encountered few situations that cannot be handled by
 130 <strong>mom</strong>'s typesetting macros.
 131 <p>
 132 <strong>Author's note:</strong> One area where groff itself needs
 133 serious rethinking is in the matter of an algorithm that takes into
 134 account both word AND letter spacing when
 135 <a href="definitions.html#TERMS_JUST">justifying</a>
 136 lines.  At present, only word spacing is adjusted, requiring what I
 137 consider an unnecessary amount of user intervention whenever
 138 letter spacing is required.
 139
 140 <a name="INTRO_DOCPROCESSING">
 141         <h2><u>Document processing with mom</u></h2>
 142 </a>
 143
 144 <strong>Mom</strong>'s document processing macros let you format
 145 documents without having to worry about the typographic details.
 146 In this respect, <strong>mom</strong> is similar to other groff macro
 147 packages, as well as to html and LaTeX.  Where <strong>mom</strong>
 148 differs is in the degree of control you have over the look and
 149 placement of the various elements of a document.  For example, if you
 150 don't want your heads underlined, or you want them bigger/smaller,
 151 or you'd prefer them to be in a different font, or you'd rather they
 152 were flush left instead of centered, you can make the changes easily
 153 and have them apply to the whole document.  Temporary and one-off
 154 changes are easy, too.
 155 <p>
 156 <strong>Mom</strong> has some nifty features other macro sets
 157 don't provide.  For example, you can switch between draft-style and
 158 final-copy output.  If you regularly make submissions to publishers
 159 and editors who insist on "typewritten, double-spaced," there's a
 160 special macro --
 161 <a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>
 162 -- that changes typeset documents into ones that would make your
 163 high-school typing teacher proud.  Footnotes, multiple columns,
 164 recto/verso printing and user designable headers and footers are also
 165 part of the fun.
 166
 167 <a name="INTRO_PHILOSOPHY">
 168         <h2><u>Mom's philosophy</u></h2>
 169 </a>
 170
 171 Formatting documents should be easy, from soup to nuts.  Writers need
 172 to focus on what they're writing, not on how it looks.  From the
 173 moment you fire up an editor to the moment you add "FINIS"
 174 to your opus, nothing should interfere with the flow of your words.
 175 The commands needed to format your work should be easy to remember,
 176 comprehensible, and stand out well from the text.  There shouldn't
 177 be too much clutter.  Your documents should be as readable inside a
 178 text editor as they are on the printed page.
 179 <p>
 180 Unfortunately, in computerland, &quot;easy,&quot;
 181 &quot;comprehensible,&quot; and &quot;readable&quot; often mean
 182 &quot;you're stuck with what you're get.&quot; No document formatting
 183 system can give you exactly what you want all the time, every time.
 184 Documents, it seems, always need to be tweaked, either to satisfy a
 185 typographic whim or to clarify some aspect of their content.
 186 <p>
 187 Groff has traditionally solved the problem of formatting vs. tweaking
 188 by requiring users of the common macro packages (mm, ms, me and their
 189 offspring) to resort to groff
 190 <a href="definitions.html#TERMS_PRIMITIVES">primitives</a>
 191 and
 192 <a href="definitions.html#TERMS_INLINES">inline escapes</a>
 193 for their special typesetting needs.  Not to put too fine a point on
 194 it, groff primitives tend toward the abstruse, and most inline escapes
 195 are about as readable in-line as an encrypted password.  This does
 196 not make for happy-camper writers, who either find themselves stuck
 197 with document formatting style they don't really like, or are forced to
 198 learn groff from the ground up -- a daunting task, to say the least.
 199 <p>
 200 <strong>Mom</strong> aims to make creating documents a simple matter,
 201 but with no corresponding loss of user control.  The document
 202 processing macros provide an excellent set of defaults, but if
 203 something is not to your liking, you can change it.  And in combination
 204 with the typesetting macros, you have all the tools you need to
 205 massage passages and tweak pages until they look utterly professional.
 206 <p>
 207 One rarely hears the word &quot;user interface&quot; in conjunction
 208 with document processing.  Since the user formatting takes place
 209 inside a text editor, little thought is given to the look and feel
 210 of the formatting commands.  <strong>Mom</strong> attempts to rectify
 211 this by providing users with a consistent, readable &quot;coding&quot;
 212 style.  Most of the macros (especially in the document processing set)
 213 have humanly-readable names.  Not only does this speed up learning
 214 the macros, it makes the sense of what's going on in a document,
 215 typographically and structurally, easier to decipher.
 216 <p>
 217 <strong>Mom</strong> does not try to be all things to all people.
 218 In contrast to the normal groff philosophy, she does not try to
 219 produce output that looks good no matter where it's displayed.
 220 She's designed for printed output, although with
 221 <a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>
 222 she produces acceptable terminal copy.  She makes no attempt to be
 223 compatible with older versions of troff.  And she remains largely
 224 untested with the groff preprocessors (tbl, pic, eqn, etc.)
 225 <p>
 226 One special feature in <strong>mom</strong>'s design is the attention
 227 she pays to aligning the bottom margins of every page.  Nothing screams
 228 &quot;shoddy&quot; in typeset documents louder than bottom margins
 229 that wander, or, in typesetter jargon, &quot;hang.&quot; There are,
 230 of course, situations where whitespace at the bottom of a page may
 231 be desirable (for example, you wouldn't want a head to appear at the
 232 bottom of the page without some text underneath it), but in all cases
 233 where hanging bottom margins can be avoided, <strong>mom</strong> does
 234 avoid them, by clever adjustments to leading (&quot;line spacing&quot;)
 235 and the spacing between different elements on the page.
 236
 237 <a name="INTRO_DOCUMENTATION">
 238         <h2><u>A note on mom's documentation</u></h2>
 239 </a>
 240
 241 Writing documentation is tough, no doubt about it.  One is never
 242 quite sure of the user's level of expertise.  Is s/he new to the
 243 application, new to its underlying protocols and programs, new to
 244 the operating system, new to computers?  At some point, one has to
 245 decide who the documentation is for.  Making the wrong decision can
 246 mean the difference between a program that gets used and a program
 247 that gets tossed.
 248 <p>
 249 <strong>Mom</strong>'s documentation assumes users know their way
 250 around GNU/Linux.  It further assumes they at least know what groff
 251 is, even if they don't know much about it.  Lastly, it assumes that
 252 everyone -- groff newbies and experts alike -- learns faster from
 253 a few well-placed examples than from manpage-style reference docs.
 254 What <strong>mom</strong>'s documentation doesn't assume is that
 255 you know everything -- not about groff, not about typesetting,
 256 not about document processing.  Even experts have odd lacunae in
 257 their knowledge base.  Therefore, whenever I suspect that a term
 258 or procedure will cause head scratching, I offer an explanation.
 259 And when explanations aren't enough, I offer examples.
 260 <a name="CANONICAL"></a>
 261 <p>
 262 The canonical reference materials for groff are <strong>cstr54</strong>
 263 (a downloadable PostScript copy of which is available
 264 <a href="http://www.kohala.com/start/troff/">here</a>)
 265 and the <strong>troff</strong> and <strong>groff_diff</strong> manpages.
 266 I've tried to avoid reiterating them, however, in a few places, this has
 267 proved impossible.  Be forewarned: I have no qualms about sidestepping
 268 excrutiating completeness about groff usage; I'm more concerned with
 269 getting <strong>mom</strong> users up and running. <em>Mea culpa.</em>
 270 <p>
 271 <strong>Note:</strong> <strong>Mom</strong>'s macro file
 272 (om.tmac) is heavily commented.  Each macro is preceded by a
 273 description of its arguments, function, and usage, which may
 274 give you information in addition to what's contained in this
 275 documentation.
 276
 277 <a name="MACRO_ARGS">
 278         <h3><u>How to read macro arguments</u></h3>
 279 </a>
 280
 281 <p>
 282 The concise descriptions of macros in this documentation typically
 283 look like this:
 284 <blockquote>
 285 Macro: <strong>NAME</strong> <var>arguments</var>
 286 </blockquote>
 287 <var>arguments</var> lists the macro's arguments using conventions that
 288 should be familiar to anyone who has ever read a manpage.  Briefly:
 289 <p>
 290 <ol>
 291         <li>Macro arguments are separated from each other by spaces.
 292         <li>If an argument is surrounded by chevrons
 293                 (&nbsp;&lt;&nbsp;&gt;&nbsp;), it's a description of the argument,
 294                 not the argument itself.
 295         <li>If an argument begins with or is surrounded by double-quotes, the
 296                 double quotes MUST be included in the argument.
 297         <li>If the user has a choice between several arguments, each of the
 298                 choices is separated by the pipe character (&nbsp;|&nbsp;),
 299                 which means &quot;or.&quot;
 300         <li>Arguments that are optional are surrounded by square brackets.
 301         <li>&lt;off&gt; in an argument list means that any argument
 302                 turns the macro off.
 303 </ol>
 304
 305 <a name="TOGGLE_MACRO"><h3><u>Toggle macros</u></h3></a>
 306 <p>
 307 Some macros don't require an argument.  They simply start something.
 308 When you need to turn them off, the same macro with <em>any</em>
 309 argument will do the trick.  That's right: ANY argument.  This permits
 310 choosing whatever works for you: OFF, END, QUIT, DONE, Q, X...  Hell,
 311 it could even be I_LOVE_MOM.
 312 <p>
 313 Since these macros toggle things on and off, the argument list
 314 simply reads
 315 <blockquote>
 316 <var>toggle</var>
 317 </blockquote>
 318 <hr>
 319
 320 <h3>Example 1: an argument requiring double-quotes</h3>
 321 <blockquote>
 322 Macro: <strong>TITLE</strong> <var>&quot;&lt;title of document&gt;&quot;</var>
 323 </blockquote>
 324 The required argument to <strong>TITLE</strong> is the title of your
 325 document.  Since it's surrounded by double-quotes, you must
 326 include them in the argument, like this:
 327 <p>
 328 <pre>
 329         .TITLE "My Pulitzer Novel"
 330 </pre>
 331
 332 <h3>Example 2: a macro with required and optional arguments</h3>
 333 <blockquote>
 334 Macro: <strong>TAB_SET</strong> <var>&lt;tab #&gt;  &lt;indent&gt;  &lt;length&gt;  [ L | R | C | J [ QUAD ] ]</var>
 335 </blockquote>
 336 The first required argument is a number that identifies the tab (say,
 337 "3").  The second required argument is an indent from the left margin
 338 (say, 6 picas).  The third required argument is the length of the tab
 339 (say, 3 picas).  Therefore, at a minimum, when using this macro,
 340 you would enter:
 341 <p>
 342 <pre>
 343         .TAB_SET 3 6P 3P
 344 </pre>
 345
 346 The remaining two arguments are optional.  The first is a single
 347 letter, either L, R, C or J.  The second, which is itself optional
 348 after L, R, C or J, is the word QUAD.  Therefore, depending on
 349 what additional information you wish to pass to the macro,
 350 you could enter:
 351 <p>
 352 <pre>
 353         .TAB_SET 3 6P 3P L
 354                 or
 355         .TAB_SET 3 6P 3P L QUAD
 356 </pre>
 357
 358 <a name="TOGGLE_EXAMPLE"><h3>Example 3: a sample toggle macro:</h3></a>
 359
 360 <blockquote>
 361 Macro: <strong>QUOTE</strong> <var>toggle</var>
 362 </blockquote>
 363
 364 <strong>QUOTE</strong> begins a section of quoted text in a document
 365 and doesn't require an argument.  When the quote's finished,
 366 you have to tell <strong>mom</strong> it's done.
 367 <p>
 368 <pre>
 369         .QUOTE
 370         So runs my dream, but what am I?
 371         An infant crying in the night
 372         An infant crying for the light
 373         And with no language but a cry.
 374         .QUOTE OFF
 375 </pre>
 376
 377 Alternatively, you could have turned the quote off with END, or
 378 X, or something else.
 379
 380 <p>
 381 <hr>
 382 <a href="definitions.html#TOP">Next</a>&nbsp;&nbsp;
 383 <a href="#TOP">Top</a>&nbsp;&nbsp;
 384 <a href="toc.html">Table of Contents</a>
 385 </body>
 386 </html>