diff options
Diffstat (limited to 'contrib/mom/momdoc/intro.html')
| -rw-r--r-- | contrib/mom/momdoc/intro.html | 502 |
1 files changed, 502 insertions, 0 deletions
diff --git a/contrib/mom/momdoc/intro.html b/contrib/mom/momdoc/intro.html new file mode 100644 index 00000000..85ab852f --- /dev/null +++ b/contrib/mom/momdoc/intro.html @@ -0,0 +1,502 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>What is mom?</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="definitions.html#TOP">Next</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<p> +<a name="INTRO"><h1 align="center"><u>What is mom?</u></h1></a> + +<a href="#INTRO_INTRO">Who is mom meant for?</a> +<br/> + +<a href="#INTRO_TYPESETTING">Typesetting with mom</a> +<br/> + +<a href="#INTRO_DOCPROCESSING">Document processing with mom</a> +<br/> + +<a href="#INTRO_PHILOSOPHY">Mom's philosophy</a> +<br/> + +<a href="#INTRO_DOCUMENTATION">A note on mom's documentation</a> +<br/> + +<a href="#CANONICAL">Canonical reference materials</a> +<br/> + +<a href="#MACRO_ARGS">How to read macro arguments</a> +</p> + +<a name="INTRO_INTRO"><h2><u>Who is mom meant for?</u></h2></a> + +<p> +<strong>Mom</strong> ("my own macros", "my other +macros", "maximum overdrive macros"...) is a macro set for +groff, designed to format documents for PostScript output. +She's aimed at three kinds of users: +</p> + +<ol> + <li>typesetters who suspect groff might be "the right + tool for the job" but who are + frustrated/intimidated by groff's terse, geeky, + not-always-typographically-intuitive + <a href="definitions.html#TERMS_PRIMITIVES">primitives</a>; + </li> + <li>non-scientific writers (novelists, short story writers, + journalists, students) who just want their work to + look good; + </li> + <li>newbies to computer typesetting, document processing, or + groff who need a well-documented macro set to help them get + started. + </li> +</ol> + +<p> +As might be inferred from the above, <strong>mom</strong> is two macro +packages in one: a set of typesetting macros, and a set of document +formatting macros. The typesetting macros govern the physical +aspects of page layout and provide sane, comprehensible control over +typographic refinements. The document formatting macros let you focus +on a document's content and logical structure without worrying about +typesetting or page layout at all. +</p> + +<p> +Because <strong>mom</strong> provides both typesetting and document +formatting macros, it's safe to say she blurs the distinction between +document processing and document design. While her basic document style +come with pretty spiffy defaults (okay — change "spiffy" +to "typographically professional"), you can easily control +how all the various document elements look: titles, page headers and +footers, page numbering, heads, subheads, footnotes and so on can be +made to come out exactly the way you want. And should you need precise +typographic control over elements in a document that fall outside the +range of <strong>mom</strong>'s document element tags, you don't have to +read up on groff +<a href="definitions.html#TERMS_PRIMITIVES">primitives</a> +in order to accomplish what you want; the typesetting macros take +care of that. +</p> + +<a name="INTRO_TYPESETTING"><h2><u>Typesetting with mom</u></h2></a> + +<p> +<strong>Mom</strong>'s typesetting macros control the basic parameters +of type: margins, line length, 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> +In terms of typographic control, these macros resemble the +commands used on dedicated typesetting computers like Compugraphics and +Linotronics. Most of them simply give access to groff's typesetting +primitives in a way that's consistent and easy to use. A few of +them (tabs and indents, for example) handle fundamental typesetting +requirements in ways radically different from groff primitives. +</p> + +<p> +With <strong>mom</strong>'s typesetting macros, you can, if you wish, +create individual output pages that you design from the ground up. +Provided you have not signalled to <strong>mom</strong> that you +want document processing (via the +<a href="docprocessing.html#START">START</a> +macro; see below), every 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 reading various mailing lists dealing with computer +typesetting (groff, TeX, and friends) have convinced me that no program +can ever replace the human eye and human input when it comes to high +quality typesetting. As of this writing, a thread on the subject of +"micro typography" in groff has been going on for nearly a +month. The reason for the lengthy thread is obvious; words and +punctuation on the printed page are too variable, too fluid, to be +rendered flawlessly by any algorithm, no matter how clever. (For +whatever it's worth, a similar problem exists with engraving musical +scores by computer.) +</p> + +<p> +<strong>Mom</strong> does not try to solve the problems posed +by things like hanging punctuation, left-margin adjustments for +upper case letters like T and W, and so on. She merely tries to +provide tools that allow knowledgeable typesetters to come up with +solutions to these problems in ways that are easier and more +intuitive than manipulating groff at the +<a href="definitions.html#TERMS_PRIMITIVES">primitive</a> +level. As a professional typesetter of more than two decades, and a +writer, I have encountered few situations that cannot be handled by +<strong>mom</strong>'s typesetting macros. +</p> + +<p> +<strong>Author's note:</strong> One area where groff itself needs +serious rethinking is in the matter of an algorithm that takes into +account both word and letter spacing when +<a href="definitions.html#TERMS_JUST">justifying</a> +lines. At present, only word spacing is adjusted, requiring what I +consider an unnecessary amount of user intervention whenever +letter spacing is required. +</p> + +<a name="INTRO_DOCPROCESSING"><h2><u>Document processing with mom</u></h2></a> + +<p> +<strong>Mom</strong>'s document processing macros let you format +documents without having to worry about the typographic details. +In this respect, <strong>mom</strong> is similar to other groff macro +packages, as well as to html and LaTeX. Where <strong>mom</strong> +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 +don't want your heads underlined, or you want them bigger/smaller, +or you'd prefer them to be in a different font, or you'd rather they +were flush left instead of centred, you can make the changes easily +and have them apply to the whole document. Temporary and one-off +changes are easy, too. +</p> + +<p> +<strong>Mom</strong> has some nifty 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 TYPEWRITE</a> +— that changes typeset documents into ones that would make +your high-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> + +<a name="INTRO_PHILOSOPHY"><h2><u>Mom's philosophy</u></h2></a> + +<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, it seems, 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#TERMS_PRIMITIVES">primitives</a> +and +<a href="definitions.html#TERMS_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 in-line as an encrypted password. This does +not make for happy-camper writers, who either find themselves stuck +with a document formatting style they don't really like, or are +forced to learn groff from the ground up — a daunting task, to +say the least. +</p> + +<p> +<strong>Mom</strong> aims to make creating documents a simple matter, +but with no corresponding loss of user control. The document +processing macros provide an excellent set of defaults, but if +something is not to your liking, you can change it. And 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 word "user interface" in conjunction +with document processing. Since the user formatting takes place +inside a text editor, little thought is given to the look and feel +of the formatting commands. <strong>Mom</strong> 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, +typographically and structurally, easier to decipher. +</p> + +<p> +<strong>Mom</strong> 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 printed output, although with +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a> +she produces acceptable terminal copy. She makes no attempt to be +compatible with older versions of troff. +</p> + +<p> +One special feature in <strong>mom</strong>'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 desirable (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, <strong>mom</strong> does +avoid them, by clever adjustments to leading ("line spacing") +and the spacing between different elements on the page. +</p> + +<a name="INTRO_DOCUMENTATION"><h2><u>A note on mom's documentation</u></h2></a> + +<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, new to computers? At some point, one has to +decide who the documentation is for. Making the wrong decision can +mean the difference between a program that gets used and a program +that gets tossed. +</p> + +<p> +<strong>Mom</strong>'s documentation assumes users know their +way around their own operating system (basic file management, +how to invoke commands, how to use a text editor, etc). I use +GNU/Linux, and while the documentation may exhibit a GNU/Linux bias, +<strong>mom</strong> and groff can, in fact, be used on a variety of +other popular operating systems, including the one from Redmond, +Virginia, USA. +</p> + +<p> +The documentation further assumes they 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 <strong>mom</strong>'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> + +<a name="CANONICAL"><h3><u>Canonical reference materials</u></h3></a> + +<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/">here</a>) +and the <strong>troff</strong> and <strong>groff_diff</strong> +manpages. Another excellent source of information (maybe the best) +is the groff <strong>info</strong> pages, available by typing + +<pre> + info groff +</pre> + +at the command line (assuming you have the <strong>TeXinfo +standalone browser</strong> installed on your system, which is +standard for most GNU/Linux distributions). And for +inputting special characters, see <strong>man groff_char.</strong> +</p> + +<p> +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 +<strong>mom</strong> users up and running. <em>Mea culpa.</em> +</p> + +<p> +<strong>Note:</strong> <strong>Mom</strong>'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> + +<p> +<strong>Addendum:</strong> As of version 1.4-a, the main macro +file, om.tmac, is now stripped of comments when groff is built +from sources. om.tmac in the sources themselves still contains +the comments, as do the tarballs posted on <strong>mom</strong>'s +homepage. +</p> + +<hr/> + +<a name="MACRO_ARGS"><h2><u>How to read macro arguments</u></h2></a> + +<p> +The concise descriptions of macros in this documentation typically +look like this: + +<blockquote> + <nobr>Macro: <strong>NAME</strong> <kbd>arguments</kbd></nobr> +</blockquote> +</p> + +<p> +<kbd>arguments</kbd> lists the macro's arguments using conventions that +should be familiar to anyone who has ever read a manpage. Briefly: + +<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> in an argument list means that any + argument other than those in the argument list turns the + macro off. + </li> +</ol> +</p> + +<a name="TOGGLE_MACRO"><h3><u>Toggle macros</u></h3></a> + +<p> +Some macros don't require an argument. They simply start something. +When you need to turn them off, the same macro with <em>any</em> +argument will do the trick. That's right: ANY argument. This permits +choosing whatever works for you: OFF, END, QUIT, DONE, Q, X... Hell, +it could even be I_LOVE_MOM. +</p> + +<p> +Since these macros toggle things on and off, the argument list +simply reads + +<blockquote> + <kbd>toggle</kbd> +</blockquote> +</p> + +<h4><u>Example 1: An argument requiring double-quotes</u></h4> + +<blockquote> + <nobr>Macro: <strong>TITLE</strong> <kbd>"<title of document>"</kbd></nobr> +</blockquote> + +<p> +The required argument to <strong>TITLE</strong> is the title of your +document. Since it's surrounded by double-quotes, you must +include them in the argument, like this: + +<pre> + .TITLE "My Pulitzer Novel" +</pre> +</p> + +<h4><u>Example 2: A macro with required and optional arguments</u></h4> + +<blockquote> + <nobr>Macro: <strong>TAB_SET</strong> <kbd><tab #> <indent> <length> [ L | R | C | J [ QUAD ] ]</kbd></nobr> +</blockquote> + +<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: + +<pre> + .TAB_SET 3 6P 3P +</pre> +</p> + +<p> +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: + +<pre> + .TAB_SET 3 6P 3P L + or + .TAB_SET 3 6P 3P L QUAD +</pre> +</p> + +<a name="TOGGLE_EXAMPLE"><h4><u>Example 3: A sample toggle macro:</u></h4></a> + +<blockquote> + <nobr>Macro: <strong>QUOTE</strong> <kbd>toggle</kbd></nobr> +</blockquote> + +<p> +<strong>QUOTE</strong> begins a section of quoted text in a document +and doesn't require an argument. When the quote's finished, +you have to tell <strong>mom</strong> it's done. + +<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 +</pre> +</p> + +<p> +Alternatively, you could have turned the quote off with +<kbd>END</kbd>, or <kbd>X</kbd>, or something else. +</p> + +<hr/> + +<p> +<a href="definitions.html#TOP">Next</a> +<a href="#TOP">Top</a> +<a href="toc.html">Table of Contents</a> +</p> + +</body> +</html> +<!-- vim: fileencoding=latin1: nomodified: +--> |