contrib/mom/momdoc/intro.html

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!--
   3 This file is part of groff, the GNU roff type-setting system.
   4
   5 Copyright (C) 2004-2018 Free Software Foundation, Inc.
   6 Written by Peter Schaffter (peter@schaffter.ca).
   7
   8 Permission is granted to copy, distribute and/or modify this document
   9 under the terms of the GNU Free Documentation License, Version 1.3 or
  10 any later version published by the Free Software Foundation; with no
  11 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  12 Texts.
  13
  14 A copy of the Free Documentation License is included as a file called
  15 FDL in the main directory of the groff source package.
  16 -->
  17
  18 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  19 <html xmlns="http://www.w3.org/1999/xhtml">
  20
  21 <head>
  22   <meta http-equiv="content-type" content="text/html;charset=utf-8"/>
  23   <title>What is mom?</title>
  24   <link rel="stylesheet" type="text/css" href="stylesheet.css" />
  25 </head>
  26
  27 <body style="background-color: #f5faff;">
  28
  29 <!-- ==================================================================== -->
  30
  31 <div id="top" class="page">
  32
  33 <!-- Navigation links -->
  34 <table style="width: 100%;">
  35   <tr>
  36     <td><a href="toc.html">Back to Table of Contents</a></td>
  37     <td style="text-align: right;"><a href="definitions.html#top">Next: Definitions</a></td>
  38   </tr>
  39   </table>
  40
  41 <h1 id="intro" class="docs">What is mom?</h1>
  42
  43 <div style="text-align: center;">
  44 <ul class="no-enumerator" style="margin-left: -2.5em;">
  45   <li ><a href="#intro-intro">Who is mom meant for?</a></li>
  46   <li ><a href="#intro-typesetting">Typesetting with mom</a></li>
  47   <li ><a href="#intro-docprocessing">Document processing with mom</a></li>
  48   <li ><a href="#intro-philosophy">Mom&#8217;s philosophy</a></li>
  49   <li ><a href="#intro-documentation">A note on mom&#8217;s documentation</a></li>
  50   <li ><a href="#canonical">Canonical reference materials</a></li>
  51   <li ><a href="#macro-args">How to read macro arguments</a></li>
  52 </ul>
  53 </div>
  54
  55 <div class="rule-short" style="margin-top: 18px;"><hr/></div>
  56
  57 <h2 id="intro-intro" class="docs">Who is mom meant for?</h2>
  58
  59 <p>
  60 Mom (&#8220;my own macros&#8221;, &#8220;my other macros&#8221;,
  61 &#8220;maximum overdrive macros&#8221;...) is a macro set for groff,
  62 designed to format documents in Portable Document Format (.pdf) and
  63 PostScript (.ps).  She&#8217;s aimed at three kinds of users:
  64 </p>
  65
  66 <ol style="margin-top: -.5em; margin-bottom: -.5em;">
  67   <li>Typesetters who suspect groff might be &#8220;the right
  68       tool for the job&#8221; but who are frustrated,
  69       intimidated, or puzzled by groff&#8217;s terse,
  70       not-always-typographically-intuitive
  71       <a href="definitions.html#primitives">primitives</a>;
  72   </li>
  73   <li>Writers who need to format their work easily, with a
  74       minimum of clutter;
  75   </li>
  76   <li>Newcomers to groff, typesetting, or document processing
  77       who need a well-documented macro set to get them started.
  78   </li>
  79 </ol>
  80
  81 <p>
  82 Mom is actually two macro packages in one: a very complete set
  83 of typesetting macros, and an equally thorough set of document
  84 formatting macros.  The typesetting macros afford fine-grained
  85 control over all visible aspects of page layout and design (margins,
  86 fonts, sizes, kerning, etc), while the document formatting macros
  87 focus on the logical structure of a document (titles, headings,
  88 paragraphs, lists, etc) and call on groff to render logical
  89 structure into pleasing type.
  90 </p>
  91
  92 <h2 id="intro-typesetting" class="docs">Typesetting with mom</h2>
  93
  94 <p>
  95 Mom&#8217;s typesetting macros control the basic parameters
  96 of type: margins, line lengths, type family, font, point size,
  97 linespacing, and so on.  In addition, they allow you to move
  98 around on the page horizontally and vertically, and to set up
  99 tabs, indents, and columns.  Finally, they let you adjust such
 100 typographic details as justification style, letter spacing, word
 101 spacing, hyphenation, and kerning.
 102 </p>
 103
 104 <p>
 105 The typesetting macros also provide the means to create horizontal
 106 and vertical rules, rectangles (boxes, frames), and ellipses
 107 (circles).
 108 </p>
 109
 110 <p>
 111 In terms of typographic control, the typesetting macros provide
 112 access to groff&#8217;s primitives in a way that&#8217;s consistent,
 113 sensible, and easy to use.  With them, you can create individual
 114 pages designed from the ground up.  Provided you have not signalled
 115 to mom that you want document processing (via the
 116 <kbd><a href="docprocessing.html#start">START</a></kbd>
 117 macro; see below), every typesetting macro is a literal command
 118 that remains in effect until you modify it or turn it off.  This
 119 means that if you want to create flyers, surveys, tabulated forms,
 120 curricula vitae and so on, you may do so in the good old-fashioned
 121 way: one step at a time with complete control over every element on
 122 the page.
 123 </p>
 124
 125 <p>
 126 Years of experience have convinced me that no program can ever
 127 replace the human eye and human input when it comes to high quality
 128 typesetting.  Words and punctuation on the printed page are too
 129 variable, too fluid, to be rendered flawlessly by any algorithm,
 130 no matter how clever.
 131 </p>
 132
 133 <p>
 134 Mom, therefore, does not try to guess solutions for issues like
 135 hanging punctuation, or left-margin adjustments for troublesome
 136 letters like T, V and W.  Rather, she provides tools that allow
 137 knowledgeable typesetters to handle these typographic challenges in
 138 ways that are easier and more intuitive than manipulating groff at
 139 the primitive level.
 140 </p>
 141
 142 <h2 id="intro-docprocessing" class="docs">Document processing with mom</h2>
 143
 144 <p>
 145 Mom&#8217;s document processing macros let you format documents
 146 without having to worry about the typographic details.  In this
 147 respect, mom is similar to other groff macro packages, as well as
 148 to html and LaTeX.  Where mom differs is in the degree of control
 149 you have over the look and placement of the various elements of a
 150 document.  For example, if you&#8217;d like your headings underlined,
 151 or in caps, or centred rather than flush left, you can make the
 152 changes easily and have them apply to the whole document.  Temporary
 153 and one-off changes are easy, too.
 154 </p>
 155
 156 <p>
 157 Mom has some features other macro sets don&#8217;t provide.  For
 158 example, you can switch between draft-style and final-copy output.
 159 If you regularly make submissions to publishers and editors who
 160 insist on "typewritten, double-spaced," there&#8217;s a special
 161 macro&mdash;
 162 <a href="docprocessing.html#printstyle"><kbd>PRINTSTYLE TYPEWRITE</kbd></a>&mdash;
 163 that changes typeset documents into ones that would make an
 164 old-school typing teacher proud.  Footnotes, endnotes, tables of
 165 contents, multiple columns, nested lists, recto/verso printing and
 166 user designable headers and footers are also part of the fun.
 167 </p>
 168
 169 <h2 id="intro-philosophy" class="docs">Mom&#8217;s philosophy</h2>
 170
 171 <p>
 172 Formatting documents should be easy, from soup to nuts.  Writers
 173 need to focus on what they&#8217;re writing, not on how it looks.
 174 From the moment you fire up an editor to the moment you add
 175 "FINIS" to your opus, nothing should interfere with the flow of
 176 your words.  The commands needed to format your work should be
 177 easy to remember, comprehensible, and stand out well from the
 178 text.  There shouldn&#8217;t be too much clutter.  Your documents
 179 should be as readable inside a text editor as they are on the
 180 printed page.
 181 </p>
 182
 183 <p>
 184 Unfortunately, in computerland, &#8220;easy,&#8221;
 185 &#8220;comprehensible,&#8221; and &#8220;readable&#8221; often
 186 mean &#8220;you&#8217;re stuck with what you get.&#8221; No
 187 document formatting system can give you exactly what you want all
 188 the time, every time.  Documents always need to be tweaked, either
 189 to satisfy a typographic whim or to clarify some aspect of their
 190 content.
 191 </p>
 192
 193 <p>
 194 Groff has traditionally solved the problem of formatting vs.
 195 tweaking by requiring users of the common macro packages (mm, ms,
 196 me and their offspring) to resort to groff
 197 <a href="definitions.html#primitives">primitives</a>
 198 and
 199 <a href="definitions.html#inlines">inline escapes</a>
 200 for their special typesetting needs.  Not to put too fine a point
 201 on it, groff primitives tend toward the abstruse, and most inline
 202 escapes are about as readable as an encrypted password.  This does
 203 not make for happy-camper writers, who either find themselves stuck
 204 with a formatting style they don&#8217;t like, or are forced to
 205 learn groff from the ground up&mdash;a daunting task, to say the
 206 least.
 207 </p>
 208
 209 <p>
 210 Mom aims to make creating documents a simple matter, but with no
 211 corresponding loss of user control.  The document processing macros
 212 provide an initial set of reasonable defaults, but anything that
 213 is not to your liking can be changed.  In combination with the
 214 typesetting macros, you have all the tools you need to massage
 215 passages and tweak pages until they look utterly professional.
 216 </p>
 217
 218 <p>
 219 One rarely hears the term &#8220;user interface&#8221; in
 220 conjunction with document processing.  Since formatting takes
 221 place inside a text editor, little thought is given to the
 222 look and feel of the formatting commands.  Mom attempts to
 223 rectify this by providing users with a consistent, readable
 224 &#8220;coding&#8221; style.  Most of the macros (especially in
 225 the document processing set) have humanly-readable names.  Not
 226 only does this speed up learning the macros, it makes the sense
 227 of what&#8217;s going on in a document easier to decipher,
 228 typographically and structurally.
 229 </p>
 230
 231 <p>
 232 Mom does not try to be all things to all people.  In contrast to
 233 the normal groff philosophy, she does not try to produce output
 234 that looks good no matter where it&#8217;s displayed.  She&#8217;s
 235 designed for primarily for PDF or PostScript output, although
 236 with <a href="docprocessing.html#printstyle"><kbd>PRINTSTYLE
 237 TYPEWRITE</kbd></a>
 238 she produces acceptable terminal copy.  No attempt is made to be
 239 compatible with older versions of troff.
 240 </p>
 241
 242 <p>
 243 One special feature in mom&#8217;s design is the attention she pays
 244 to aligning the bottom margins of every page.  Nothing screams
 245 shoddy in typeset documents louder than bottom margins that
 246 wander, or, in typesetter jargon, &#8220;hang.&#8221; There are,
 247 of course, situations where whitespace at the bottom of a page
 248 may be unavoidable (for example, you wouldn&#8217;t want a head
 249 to appear at the bottom of the page without some text underneath
 250 it), but in all cases where hanging bottom margins can be avoided,
 251 mom does avoid them, by clever adjustments to leading (&#8220;line
 252 spacing&#8221;) and the spacing between different elements on the
 253 page.
 254 </p>
 255
 256 <h2 id="intro-documentation" class="docs">A note on mom&#8217;s documentation</h2>
 257
 258 <p>
 259 Writing documentation is tough, no doubt about it.  One is never
 260 quite sure of the user&#8217;s level of expertise.  Is s/he new to
 261 the application, new to its underlying protocols and programs, new
 262 to the operating system?  At some point, one has to decide for whom
 263 the documentation is intended.  Making the wrong choice can mean the
 264 difference between a program that gets used and a program that gets
 265 tossed.
 266 </p>
 267
 268 <p>
 269 Mom&#8217;s documentation assumes users know their way around
 270 their own operating system (basic file management, how to use
 271 the command line, how to use a text editor, etc).  I run GNU/Linux,
 272 and while the documentation may exhibit a GNU/Linux bias, mom
 273 and groff can, in fact, be run on other platforms.
 274 </p>
 275
 276 <p>
 277 The documentation further assumes users at least know what groff
 278 is, even if they don&#8217;t know much about it.  Lastly,
 279 it assumes that everyone&mdash;groff newbies and experts
 280 alike&mdash;learns faster from a few well-placed examples than
 281 from manpage-style reference docs.  What mom&#8217;s documentation
 282 doesn&#8217;t assume is that you know everything&mdash;not about
 283 groff, not about typesetting, not about document processing.  Even
 284 experts have odd lacunae in their knowledge base.  Therefore,
 285 whenever I suspect that a term or procedure will cause head
 286 scratching, I offer an explanation.  And when explanations
 287 aren&#8217;t enough, I offer examples.
 288 </p>
 289
 290 <h3 id="canonical" class="docs">Canonical reference materials</h3>
 291
 292 <p>
 293 The canonical reference materials for groff are
 294 <strong>cstr54</strong> (a downloadable PostScript copy of which
 295 is available
 296 <a href="http://www.kohala.com/start/troff/cstr54.ps">here</a>)
 297 and the <strong>troff</strong> and <strong>groff_diff</strong>
 298 manpages.  The most complete and up-to-date source of information is
 299 the groff info pages, available by typing <kbd>info groff</kbd> at
 300 the command line (assuming you have the TeXinfo standalone browser
 301 installed on your system, which is standard for most GNU/Linux
 302 distributions).  And for inputting special characters, see <kbd>man
 303 groff_char</kbd>.
 304 </p>
 305
 306 <p style="margin-top: 24px;">
 307 I&#8217;ve tried to avoid reiterating the information contained
 308 in these documents; however, in a few places, this has proved
 309 impossible.  But be forewarned: I have no qualms about
 310 sidestepping excruciating completeness concerning groff usage;
 311 I&#8217;m more interested in getting mom users up and running.
 312 <i>Mea culpa.</i>
 313 </p>
 314
 315 <p>
 316 Groff has ancillary programmes (pre-processors) for generating
 317 tables (<strong>tbl</strong>), diagrams (<strong>pic</strong>), and
 318 equations (<strong>eqn</strong>), which may be used in conjuction
 319 with mom.  The manuals describing their usage are found at:
 320 <br/>
 321 <span style="display:block; margin-top: .5em">
 322 <kbd>&nbsp;&nbsp;tbl</kbd>&nbsp;<a href="http://www.kohala.com/start/troff/v7man/tbl/tbl.ps">http://www.kohala.com/start/troff/v7man/tbl/tbl.ps</a>
 323 <br/>
 324 <kbd>&nbsp;&nbsp;pic</kbd>&nbsp;<a href="http://www.kohala.com/start/troff/gpic.raymond.ps">http://www.kohala.com/start/troff/gpic.raymond.ps</a>
 325 <br/>
 326 <kbd>&nbsp;&nbsp;eqn</kbd>&nbsp;<a href="http://www.kohala.com/start/troff/v7man/eqn/eqn2e.ps">http://www.kohala.com/start/troff/v7man/eqn/eqn2e.ps</a>
 327 </span>
 328 </p>
 329
 330 <div class="box-tip">
 331 <p class="tip-top" style="padding-bottom: 9px;">
 332 <b>Note:</b> Mom&#8217;s macro file (om.tmac) is heavily
 333 commented.  Each macro is preceded by a description of its
 334 arguments, function and usage, which may give you information in
 335 addition to what&#8217;s contained in this documentation.
 336 </p>
 337 </div>
 338
 339 <div class="box-tip">
 340 <p class="tip-top" style="padding-bottom: 9px; text-indent: 0px;">
 341 <strong>Addendum:</strong> The main macro file, om.tmac, is stripped
 342 of comments when groff is built from sources. om.tmac in the sources
 343 themselves still contains the comments, as do the tarballs posted on
 344 mom&#8217;s homepage.
 345 </p>
 346 </div>
 347
 348 <div class="rule-short" style="padding-top: 6px; padding-bottom: 3px;"><hr/></div>
 349
 350 <h2 id="macro-args" class="docs">How to read macro arguments</h2>
 351
 352 <p>
 353 The concise descriptions of macros in this documentation typically
 354 look like this:
 355 </p>
 356
 357 <div class="box-macro-args">
 358 Macro: <b>MACRO_NAME</b> <kbd class="macro-args">arguments</kbd>
 359 </div>
 360
 361 <p>
 362 <kbd>arguments</kbd> lists the macro&#8217;s
 363 arguments using conventions that should be familiar to anyone who
 364 has ever read a manpage.  Briefly:
 365 </p>
 366
 367 <ol>
 368   <li>Macro arguments are separated from each other by spaces.</li>
 369   <li>If an argument is surrounded by chevrons
 370       (<kbd>&lt;&nbsp;&gt;</kbd>), it&#8217;s a description
 371       of the argument, not the argument itself.
 372   </li>
 373   <li>If an argument begins with or is surrounded by double-quotes, the
 374       double quotes must be included in the argument.
 375   </li>
 376   <li>If the user has a choice between several arguments, each of the
 377       choices is separated by the pipe character
 378       (<kbd>|</kbd>), which means &#8220;or.&#8221;
 379   </li>
 380   <li>Arguments that are optional are surrounded by square brackets.</li>
 381   <li><kbd>&lt;off&gt;</kbd> or <kbd>&lt;anything&gt;</kbd> in an argument
 382       list means that any argument other than those in the argument
 383       list turns the macro off.
 384   </li>
 385 </ol>
 386
 387 <h3 id="toggle-macro" class="docs">Toggle macros</h3>
 388
 389 <p>
 390 Some macros don&#8217;t require an argument.  They simply start
 391 something.  When you need to turn them off, the same macro with
 392 any argument will do the trick.  That&#8217;s right: <em>any</em>
 393 argument (in caps, lowercase or a mixture thereof).  This permits
 394 choosing whatever works for you: <kbd>OFF, end, Quit, Q, X</kbd>,
 395 and so on.
 396 </p>
 397
 398 <p>
 399 Since these macros toggle things on and off, the argument list
 400 simply reads <kbd>toggle</kbd>.
 401 </p>
 402
 403 <div id="examples" class="examples-container">
 404 <h2 class="docs" style="margin-top: .5em;">Examples</h2>
 405
 406 <div class="examples">Example 1: An argument requiring double-quotes</div>
 407
 408 <div class="box-macro-args" style="max-width: 684px;">
 409 Macro: <b>TITLE</b> <kbd class="macro-args">&quot;&lt;title of document&gt;&quot;</kbd>
 410 </div>
 411
 412 <p>
 413 The required argument to TITLE is the title of your document.
 414 Since it&#8217;s surrounded by double-quotes, you must include
 415 them in the argument, like this:
 416 <br/>
 417 <span class="pre-in-pp">
 418   .TITLE "My Pulitzer Novel"
 419 </span>
 420 </p>
 421
 422 <div class="examples" style="margin-top: -1em;">Example 2: A macro with required and optional arguments</div>
 423
 424 <div class="box-macro-args"  style="width: 684px;">
 425 Macro: <b>TAB_SET</b> <kbd class="macro-args">&lt;tab number&gt;  &lt;indent&gt;  &lt;length&gt;  [ L | R | C | J [ QUAD ] ]&nbsp;</kbd>
 426 </div>
 427
 428 <p>
 429 The first required argument is a number that identifies the tab
 430 (say, "3").  The second required argument is an indent from the
 431 left margin (say, 6 picas).  The third required argument is the
 432 length of the tab (say, 3 picas).  Therefore, at a minimum, when
 433 using this macro, you would enter:
 434 <br/>
 435 <span class="pre-in-pp">
 436   .TAB_SET 3 6P 3P
 437 </span>
 438 The remaining two arguments are optional.  The first is a
 439 single letter, either <kbd>L, R, C</kbd> or
 440 <kbd>J</kbd>.  The second, which is itself
 441 optional after <kbd>L, R, C</kbd> or
 442 <kbd>J</kbd>, is the word <kbd>QUAD</kbd>.
 443 Therefore, depending on what additional information you wish to
 444 pass to the macro, you could enter:
 445 <br/>
 446 <span class="pre-in-pp">
 447   .TAB_SET 3 6P 3P L
 448 </span>
 449 or
 450 <br/>
 451 <span class="pre-in-pp">
 452   .TAB_SET 3 6P 3P L QUAD
 453 </span>
 454 </p>
 455
 456 <div id="toggle-example" class="examples" style="margin-top: -1em;">Example 3: A sample toggle macro:</div>
 457
 458 <div class="box-macro-args" style="max-width: 684px;">
 459 Macro: <b>QUOTE</b> <kbd class="macro-args">toggle</kbd>
 460 </div>
 461
 462 <p>
 463 <kbd>QUOTE</kbd> begins a section of quoted text
 464 in a document and doesn&#8217;t require an argument.  When the
 465 quote&#8217;s finished, you have to tell mom it&#8217;s done.
 466 <span class="pre">
 467   .QUOTE
 468   So runs my dream, but what am I?
 469   An infant crying in the night
 470   An infant crying for the light
 471   And with no language but a cry.
 472   .QUOTE OFF
 473 </span>
 474 </p>
 475
 476 <p>
 477   Alternatively, you could have turned the quote off with
 478   <kbd>END</kbd>, or <kbd>X</kbd>, or something else.
 479   </p>
 480 </div>
 481
 482 <!-- Navigation links -->
 483 <table style="width: 100%; margin-top: 12px;">
 484 <tr>
 485   <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
 486   <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td>
 487   <td style="width: 33%; text-align: right;"><a href="definitions.html#top">Next: Definitions</a></td>
 488 </tr>
 489 </table>
 490
 491 </div>
 492
 493 <div class="bottom-spacer"><br/></div>
 494
 495 </body>
 496 </html>