diff options
Diffstat (limited to 'contrib/mom/momdoc/intro.html')
| -rw-r--r-- | contrib/mom/momdoc/intro.html | 487 |
1 files changed, 487 insertions, 0 deletions
diff --git a/contrib/mom/momdoc/intro.html b/contrib/mom/momdoc/intro.html new file mode 100644 index 0000000..3e25631 --- /dev/null +++ b/contrib/mom/momdoc/intro.html @@ -0,0 +1,487 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004-2020 Free Software Foundation, Inc. +Written by Peter Schaffter (peter@schaffter.ca). + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>What is mom?</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> + <tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="definitions.html#top">Next: Definitions</a></td> + </tr> + </table> + +<h1 id="intro" class="docs">What is mom?</h1> + +<div style="text-align: center;"> +<ul class="no-enumerator" style="margin-left: -2.5em;"> + <li ><a href="#intro-intro">Who is mom meant for?</a></li> + <li ><a href="#intro-typesetting">Typesetting with mom</a></li> + <li ><a href="#intro-docprocessing">Document processing with mom</a></li> + <li ><a href="#intro-philosophy">Mom’s philosophy</a></li> + <li ><a href="#intro-documentation">A note on mom’s documentation</a></li> + <li ><a href="#canonical">Canonical reference materials</a></li> + <li ><a href="#macro-args">How to read macro arguments</a></li> +</ul> +</div> + +<div class="rule-short" style="margin-top: 18px;"><hr/></div> + +<h2 id="intro-intro" class="docs">Who is mom meant for?</h2> + +<p> +Mom (“my own macros”, “my other macros”, +“maximum overdrive macros”...) is a macro set for groff, +designed to format documents in Portable Document Format (.pdf) and +PostScript (.ps). She’s aimed at three kinds of users: +</p> + +<ol style="margin-top: -.5em; margin-bottom: -.5em;"> + <li>Typesetters who suspect groff might be the right + tool for the job but who are frustrated, + intimidated, or puzzled by groff’s terse, + not-always-typographically-intuitive + <a href="definitions.html#primitives">primitives</a>; + </li> + <li>Writers who need to format their work easily, with a + minimum of clutter; + </li> + <li>Newcomers to groff, typesetting, or document processing + who need a well-documented macro set to get them started. + </li> +</ol> + +<p> +Mom is actually two macro packages in one: a very complete set +of typesetting macros, and an equally thorough set of document +formatting macros. The typesetting macros afford fine-grained +control over all visible aspects of page layout and design (margins, +fonts, sizes, kerning, etc), while the document formatting macros +focus on the logical structure of a document (titles, headings, +paragraphs, lists, etc) and call on groff to render logical +structure into pleasing type. +</p> + +<h2 id="intro-typesetting" class="docs">Typesetting with mom</h2> + +<p> +Mom’s typesetting macros control the basic parameters +of type: margins, line lengths, type family, font, point size, +linespacing, and so on. In addition, they allow you to move +around on the page horizontally and vertically, and to set up +tabs, indents, and columns. Finally, they let you adjust such +typographic details as justification style, letter spacing, word +spacing, hyphenation, and kerning. +</p> + +<p> +The typesetting macros also provide the means to create horizontal +and vertical rules, rectangles (boxes, frames), and ellipses +(circles). +</p> + +<p> +In terms of typographic control, the typesetting macros provide +access to groff’s primitives in a way that’s consistent, +sensible, and easy to use. With them, you can create individual +pages designed from the ground up. Provided you have not signalled +to mom that you want document processing (via the +<a href="docprocessing.html#start">START</a> +macro; see below), every typesetting macro is a literal command +that remains in effect until you modify it or turn it off. This +means that if you want to create flyers, surveys, tabulated forms, +curricula vitae and so on, you may do so in the good old-fashioned +way: one step at a time with complete control over every element on +the page. +</p> + +<p> +Years of experience have convinced me that no program can ever +replace the human eye and human input when it comes to high quality +typesetting. Words and punctuation on the printed page are too +variable, too fluid, to be rendered flawlessly by any algorithm, +no matter how clever. +</p> + +<p> +Mom, therefore, does not try to guess solutions for issues like +hanging punctuation, or left-margin adjustments for troublesome +letters like T, V and W. Rather, she provides tools that allow +knowledgeable typesetters to handle these typographic challenges in +ways that are easier and more intuitive than manipulating groff at +the primitive level. +</p> + +<h2 id="intro-docprocessing" class="docs">Document processing with mom</h2> + +<p> +Mom’s document processing macros let you format documents +without having to worry about the typographic details. In this +respect, mom is similar to other groff macro packages, as well as +to html and LaTeX. Where mom differs is in the degree of control +you have over the look and placement of the various elements of a +document. For example, if you’d like your headings underlined, +or in caps, or centred rather than flush left, you can make the +changes easily and have them apply to the whole document. Temporary +and one-off changes are easy, too. +</p> + +<p> +Mom has some features other macro sets don’t provide. For +example, you can switch between draft-style and final-copy output. +If you regularly make submissions to publishers and editors who +insist on "typewritten, double-spaced," there’s a special +macro— +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>— +that changes typeset documents into ones that would make an +old-school typing teacher proud. Footnotes, endnotes, tables of +contents, multiple columns, nested lists, recto/verso printing and +user designable headers and footers are also part of the fun. +</p> + +<h2 id="intro-philosophy" class="docs">Mom’s philosophy</h2> + +<p> +Formatting documents should be easy, from soup to nuts. Writers +need to focus on what they’re writing, not on how it looks. +From the moment you fire up an editor to the moment you add +"FINIS" to your opus, nothing should interfere with the flow of +your words. The commands needed to format your work should be +easy to remember, comprehensible, and stand out well from the +text. There shouldn’t be too much clutter. Your documents +should be as readable inside a text editor as they are on the +printed page. +</p> + +<p> +Unfortunately, in computerland, “easy,” +“comprehensible,” and “readable” often +mean “you’re stuck with what you get.” No +document formatting system can give you exactly what you want all +the time, every time. Documents always need to be tweaked, either +to satisfy a typographic whim or to clarify some aspect of their +content. +</p> + +<p> +Groff has traditionally solved the problem of formatting vs. +tweaking by requiring users of the common macro packages (mm, ms, +me and their offspring) to resort to groff +<a href="definitions.html#primitives">primitives</a> +and +<a href="definitions.html#inlines">inline escapes</a> +for their special typesetting needs. Not to put too fine a point +on it, groff primitives tend toward the abstruse, and most inline +escapes are about as readable as an encrypted password. This does +not make for happy-camper writers, who either find themselves stuck +with a formatting style they don’t like, or are forced to +learn groff from the ground up—a daunting task, to say the +least. +</p> + +<p> +Mom aims to make creating documents a simple matter, but with no +corresponding loss of user control. The document processing macros +provide an initial set of reasonable defaults, but anything that +is not to your liking can be changed. In combination with the +typesetting macros, you have all the tools you need to massage +passages and tweak pages until they look utterly professional. +</p> + +<p> +One rarely hears the term “user interface” in +conjunction with document processing. Since formatting takes +place inside a text editor, little thought is given to the +look and feel of the formatting commands. Mom attempts to +rectify this by providing users with a consistent, readable +“coding” style. Most of the macros (especially in +the document processing set) have humanly-readable names. Not +only does this speed up learning the macros, it makes the sense +of what’s going on in a document easier to decipher, +typographically and structurally. +</p> + +<p> +Mom does not try to be all things to all people. In contrast to +the normal groff philosophy, she does not try to produce output +that looks good no matter where it’s displayed. She’s +designed for primarily for PDF or PostScript output, although +with +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a> +she produces acceptable terminal copy. No attempt is made to be +compatible with older versions of troff. +</p> + +<p> +One special feature in mom’s design is the attention she pays +to aligning the bottom margins of every page. Nothing screams +shoddy in typeset documents louder than bottom margins that +wander, or, in typesetter jargon, “hang.” There are, +of course, situations where whitespace at the bottom of a page +may be unavoidable (for example, you wouldn’t want a head +to appear at the bottom of the page without some text underneath +it), but in all cases where hanging bottom margins can be avoided, +mom does avoid them, by clever adjustments to leading (“line +spacing”) and the spacing between different elements on the +page. +</p> + +<h2 id="intro-documentation" class="docs">A note on mom’s documentation</h2> + +<p> +Writing documentation is tough, no doubt about it. One is never +quite sure of the user’s level of expertise. Is s/he new to +the application, new to its underlying protocols and programs, new +to the operating system? At some point, one has to decide for whom +the documentation is intended. Making the wrong choice can mean the +difference between a program that gets used and a program that gets +tossed. +</p> + +<p> +Mom’s documentation assumes users know their way around +their own operating system (basic file management, how to use +the command line, how to use a text editor, etc). I run GNU/Linux, +and while the documentation may exhibit a GNU/Linux bias, mom +and groff can, in fact, be run on other platforms. +</p> + +<p> +The documentation further assumes users at least know what groff +is, even if they don’t know much about it. Lastly, +it assumes that everyone—groff newbies and experts +alike—learns faster from a few well-placed examples than +from manpage-style reference docs. What mom’s documentation +doesn’t assume is that you know everything—not about +groff, not about typesetting, not about document processing. Even +experts have odd lacunae in their knowledge base. Therefore, +whenever I suspect that a term or procedure will cause head +scratching, I offer an explanation. And when explanations +aren’t enough, I offer examples. +</p> + +<h3 id="canonical" class="docs">Canonical reference materials</h3> + +<p> +The canonical reference materials for groff are +<strong>cstr54</strong> (a downloadable PostScript copy of which +is available +<a href="http://www.kohala.com/start/troff/cstr54.ps">here</a>) +and the <strong>troff</strong> and <strong>groff_diff</strong> +manpages. The most complete and up-to-date source of information is +the groff info pages, available by typing <kbd>info groff</kbd> at +the command line (assuming you have the TeXinfo standalone browser +installed on your system, which is standard for most GNU/Linux +distributions). And for inputting special characters, see <kbd>man +groff_char</kbd>. +</p> + +<p style="margin-top: 24px;"> +I’ve tried to avoid reiterating the information contained +in these documents; however, in a few places, this has proved +impossible. But be forewarned: I have no qualms about +sidestepping excruciating completeness concerning groff usage; +I’m more interested in getting mom users up and running. +<i>Mea culpa.</i> +</p> + +<p> +Groff has ancillary programmes (pre-processors) for generating +tables (<strong>tbl</strong>), diagrams (<strong>pic</strong>), and +equations (<strong>eqn</strong>), which may be used in conjunction +with mom. The manuals describing their usage are found at: +<br/> +<span style="display:block; margin-top: .5em"> +<kbd> tbl</kbd> <a href="http://www.kohala.com/start/troff/v7man/tbl/tbl.ps">http://www.kohala.com/start/troff/v7man/tbl/tbl.ps</a> +<br/> +<kbd> pic</kbd> <a href="http://www.kohala.com/start/troff/gpic.raymond.ps">http://www.kohala.com/start/troff/gpic.raymond.ps</a> +<br/> +<kbd> eqn</kbd> <a href="http://www.kohala.com/start/troff/v7man/eqn/eqn2e.ps">http://www.kohala.com/start/troff/v7man/eqn/eqn2e.ps</a> +</span> +</p> + +<div class="box-tip"> +<p class="tip-top" style="padding-bottom: 9px;"> +<b>Note:</b> Mom’s macro file (om.tmac) is heavily +commented. Each macro is preceded by a description of its +arguments, function and usage, which may give you information in +addition to what’s contained in this documentation. +</p> +</div> + +<div class="rule-short" style="padding-top: 6px; padding-bottom: 3px;"><hr/></div> + +<h2 id="macro-args" class="docs">How to read macro arguments</h2> + +<p> +The concise descriptions of macros in this documentation typically +look like this: +</p> + +<div class="box-macro-args"> +Macro: <b>MACRO_NAME</b> <kbd class="macro-args">arguments</kbd> +</div> + +<p> +<kbd>arguments</kbd> lists the macro’s +arguments using conventions that should be familiar to anyone who +has ever read a manpage. Briefly: +</p> + +<ol> + <li>Macro arguments are separated from each other by spaces.</li> + <li>If an argument is surrounded by chevrons + (<kbd>< ></kbd>), it’s a description + of the argument, not the argument itself. + </li> + <li>If an argument begins with or is surrounded by double-quotes, the + double quotes must be included in the argument. + </li> + <li>If the user has a choice between several arguments, each of the + choices is separated by the pipe character + (<kbd>|</kbd>), which means “or.” + </li> + <li>Arguments that are optional are surrounded by square brackets.</li> + <li><kbd><off></kbd> or <kbd><anything></kbd> in an argument + list means that any argument other than those in the argument + list turns the macro off. + </li> +</ol> + +<h3 id="toggle-macro" class="docs">Toggle macros</h3> + +<p> +Some macros don’t require an argument. They simply start +something. When you need to turn them off, the same macro with +any argument will do the trick. That’s right: <em>any</em> +argument (in caps, lowercase, or a mixture thereof). This permits +choosing whatever works for you: <kbd>OFF</kbd>, <kbd>end</kbd>, +<kbd>Quit</kbd>, <kbd>Q</kbd>, <kbd>X</kbd>, and so on. +</p> + +<p> +Since these macros toggle things on and off, the argument list +simply reads <kbd>toggle</kbd>. +</p> + +<div id="examples" class="examples-container"> +<h2 class="docs" style="margin-top: .5em;">Examples</h2> + +<div class="examples">Example 1: An argument requiring double-quotes</div> + +<div class="box-macro-args" style="max-width: 684px;"> +Macro: <b>TITLE</b> <kbd class="macro-args">"<title of document>"</kbd> +</div> + +<p> +The required argument to TITLE is the title of your document. +Since it’s surrounded by double-quotes, you must include +them in the argument, like this: +<br/> +<span class="pre-in-pp"> + .TITLE "My Pulitzer Novel" +</span> +</p> + +<div class="examples" style="margin-top: -1em;">Example 2: A macro with required and optional arguments</div> + +<div class="box-macro-args" style="width: 684px;"> +Macro: <b>TAB_SET</b> <kbd class="macro-args"><tab number> <indent> <length> [ L | R | C | J [ QUAD ] ] </kbd> +</div> + +<p> +The first required argument is a number that identifies the tab +(say, "3"). The second required argument is an indent from the +left margin (say, 6 picas). The third required argument is the +length of the tab (say, 3 picas). Therefore, at a minimum, when +using this macro, you would enter: +<br/> +<span class="pre-in-pp"> + .TAB_SET 3 6P 3P +</span> +The remaining two arguments are optional. The first is a +single letter, either <kbd>L, R, C</kbd> or +<kbd>J</kbd>. The second, which is itself +optional after <kbd>L, R, C</kbd> or +<kbd>J</kbd>, is the word <kbd>QUAD</kbd>. +Therefore, depending on what additional information you wish to +pass to the macro, you could enter: +<br/> +<span class="pre-in-pp"> + .TAB_SET 3 6P 3P L +</span> +or +<br/> +<span class="pre-in-pp"> + .TAB_SET 3 6P 3P L QUAD +</span> +</p> + +<div id="toggle-example" class="examples" style="margin-top: -1em;">Example 3: A sample toggle macro:</div> + +<div class="box-macro-args" style="max-width: 684px;"> +Macro: <b>QUOTE</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +<kbd>QUOTE</kbd> begins a section of quoted text +in a document and doesn’t require an argument. When the +quote’s finished, you have to tell mom it’s done. +<span class="pre"> + .QUOTE + So runs my dream, but what am I? + An infant crying in the night + An infant crying for the light + And with no language but a cry. + .QUOTE OFF +</span> +</p> + +<p> + Alternatively, you could have turned the quote off with + <kbd>END</kbd>, or <kbd>X</kbd>, or something else. + </p> +</div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="definitions.html#top">Next: Definitions</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> |