mom/momdoc/intro.html

1.1  christos <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
1.1  christos <html>
1.1  christos <head>
1.1  christos <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
1.1  christos <title>What is mom?</title>
1.1  christos </head>
1.1  christos <body bgcolor="#dfdfdf">
1.1  christos
1.1  christos <!====================================================================>
1.1  christos
1.1  christos <a href="definitions.html#TOP">Next</a>&nbsp;&nbsp;
1.1  christos <a href="toc.html">Back to Table of Contents</a>
1.1  christos
1.1  christos <a name="TOP"></a>
1.1  christos <a name="INTRO">
1.1  christos 	<h1 align="center"><u>WHAT IS MOM?</u></h1>
1.1  christos </a>
1.1  christos
1.1  christos <a href="#INTRO_INTRO">Who is mom meant for?</a>
1.1  christos <br>
1.1  christos <a href="#INTRO_TYPESETTING">Typesetting with mom</a>
1.1  christos <br>
1.1  christos <a href="#INTRO_DOCPROCESSING">Document processing with mom</a>
1.1  christos <br>
1.1  christos <a href="#INTRO_PHILOSOPHY">Mom's philosophy</a>
1.1  christos <br>
1.1  christos <a href="#INTRO_DOCUMENTATION">A note on mom's documentation</a>
1.1  christos <br>
1.1  christos <a href="#CANONICAL">Canonical reference materials</a>
1.1  christos <br>
1.1  christos <a href="#MACRO_ARGS">How to read macro arguments</a>
1.1  christos
1.1  christos <h2><a name="INTRO_INTRO"><u>Who is mom meant for?</u></a></h2>
1.1  christos
1.1  christos <strong>Mom</strong> (&quot;my own macros&quot;, &quot;my other
1.1  christos macros&quot;, &quot;maximum overdrive macros&quot;...) is a macro set for
1.1  christos groff, designed to format documents for PostScript output.
1.1  christos She's aimed at three kinds of users:
1.1  christos <br>
1.1  christos <ol>
1.1  christos 	<li>typesetters who suspect groff might be &quot;the right
1.1  christos 		tool for the job&quot; but who are
1.1  christos 		frustrated/intimidated by groff's terse, geeky,
1.1  christos 		not-always-typographically-intuitive
1.1  christos 		<a href="definitions.html#TERMS_PRIMITIVES">primitives</a>;
1.1  christos 	<br>
1.1  christos 	<li>non-scientific writers (novelists, short story writers,
1.1  christos 		journalists, students) who just want their work to
1.1  christos 		look good;
1.1  christos 	<br>
1.1  christos 	<li>newbies to computer typesetting, document processing, or
1.1  christos 		groff who need a well-documented macro set to help them get
1.1  christos 		started.
1.1  christos </ol>
1.1  christos <p>
1.1  christos As might be inferred from the above, <strong>mom</strong> is two macro
1.1  christos packages in one: a set of typesetting macros, and a set of document
1.1  christos processing macros.  The typesetting macros govern the physical
1.1  christos aspects of page layout and provide sane, comprehensible control over
1.1  christos typographic refinements.  The document processing macros let you focus
1.1  christos on a document's content and logical structure without worrying about
1.1  christos typesetting or page layout at all.
1.1  christos <p>
1.1  christos Because <strong>mom</strong> provides both typesetting and document
1.1  christos processing macros, it's safe to say she blurs the distinction between
1.1  christos document processing and document design.  While her basic document style
1.1  christos comes with pretty spiffy defaults (okay--change &quot;spiffy&quot;
1.1  christos to &quot;typographically professional&quot;), you can easily control
1.1  christos how all the various document elements look: titles, page headers and
1.1  christos footers, page numbering, heads, subheads, footnotes and so on can be
1.1  christos made to come out exactly the way you want.  And should you need precise
1.1  christos typographic control over elements in a document that fall outside the
1.1  christos range of <strong>mom</strong>'s document element tags, you don't have to
1.1  christos read up on groff
1.1  christos <a href="definitions.html#TERMS_PRIMITIVES">primitives</a>
1.1  christos in order to accomplish what you want; the typesetting macros take
1.1  christos care of that.
1.1  christos <p>
1.1  christos
1.1  christos <a name="INTRO_TYPESETTING">
1.1  christos 	<h2><u>Typesetting with mom</u></h2>
1.1  christos </a>
1.1  christos
1.1  christos <strong>Mom</strong>'s typesetting macros control the basic parameters
1.1  christos of type: margins, line length, type family, font, point size,
1.1  christos linespacing, and so on.  In addition, they allow you to move around
1.1  christos on the page horizontally and vertically, and to set up tabs, indents,
1.1  christos and columns.  Finally, they let you adjust such typographic details as
1.1  christos justification style, letter spacing, word spacing, hyphenation, and
1.1  christos kerning.
1.1  christos
1.1  christos <p>
1.1  christos In terms of typographic control, these macros resemble the
1.1  christos commands used on dedicated typesetting computers like Compugraphics and
1.1  christos Linotronics.  Most of them simply give access to groff's typesetting
1.1  christos primitives in a way that's consistent and easy to use.  A few of
1.1  christos them (tabs and indents, for example) handle fundamental typesetting
1.1  christos requirements in ways radically different from groff primitives.
1.1  christos
1.1  christos <p>
1.1  christos With <strong>mom</strong>'s typesetting macros, you can, if you wish,
1.1  christos create individual output pages that you design from the ground up.
1.1  christos Provided you have not signalled to <strong>mom</strong> that you
1.1  christos want document processing (via the
1.1  christos <a href="docprocessing.html#START">START</a>
1.1  christos macro; see below), every macro is a literal command that remains in
1.1  christos effect until you modify it or turn it off.  This means that if you
1.1  christos want to create flyers, surveys, tabulated forms, curricula vitae and
1.1  christos so on, you may do so in the good old-fashioned way: one step at a
1.1  christos time with complete control over every element on the page.
1.1  christos <p>
1.1  christos Years of reading various mailing lists dealing with computer
1.1  christos typesetting (groff, TeX, and friends) have convinced me that no program
1.1  christos can ever replace the human eye and human input when it comes to high
1.1  christos quality typesetting.  As of this writing, a thread on the subject of
1.1  christos &quot;micro typography&quot; in groff has been going on for nearly a
1.1  christos month.  The reason for the lengthy thread is obvious; words and
1.1  christos punctuation on the printed page are too variable, too fluid, to be
1.1  christos rendered flawlessly by any algorithm, no matter how clever.  (For
1.1  christos whatever it's worth, a similar problem exists with engraving musical
1.1  christos scores by computer.)
1.1  christos <p>
1.1  christos <strong>Mom</strong> does not try to solve the problems posed
1.1  christos by things like hanging punctuation, left-margin adjustments for
1.1  christos upper case letters like T and W, and so on.  She merely tries to
1.1  christos provide tools that allow knowledgeable typesetters to come up with
1.1  christos solutions to these problems in ways that are easier and more
1.1  christos intuitive than manipulating groff at the
1.1  christos <a href="definitions.html#TERMS_PRIMITIVES">primitive</a>
1.1  christos level.  As a professional typesetter of more than two decades, and a
1.1  christos writer, I have encountered few situations that cannot be handled by
1.1  christos <strong>mom</strong>'s typesetting macros.
1.1  christos <p>
1.1  christos <strong>Author's note:</strong> One area where groff itself needs
1.1  christos serious rethinking is in the matter of an algorithm that takes into
1.1  christos account both word and letter spacing when
1.1  christos <a href="definitions.html#TERMS_JUST">justifying</a>
1.1  christos lines.  At present, only word spacing is adjusted, requiring what I
1.1  christos consider an unnecessary amount of user intervention whenever
1.1  christos letter spacing is required.
1.1  christos <p>
1.1  christos <a name="INTRO_DOCPROCESSING">
1.1  christos 	<h2><u>Document processing with mom</u></h2>
1.1  christos </a>
1.1  christos
1.1  christos <strong>Mom</strong>'s document processing macros let you format
1.1  christos documents without having to worry about the typographic details.
1.1  christos In this respect, <strong>mom</strong> is similar to other groff macro
1.1  christos packages, as well as to html and LaTeX.  Where <strong>mom</strong>
1.1  christos differs is in the degree of control you have over the look and
1.1  christos placement of the various elements of a document.  For example, if you
1.1  christos don't want your heads underlined, or you want them bigger/smaller,
1.1  christos or you'd prefer them to be in a different font, or you'd rather they
1.1  christos were flush left instead of centred, you can make the changes easily
1.1  christos and have them apply to the whole document.  Temporary and one-off
1.1  christos changes are easy, too.
1.1  christos <p>
1.1  christos <strong>Mom</strong> has some nifty features other macro sets
1.1  christos don't provide.  For example, you can switch between draft-style and
1.1  christos final-copy output.  If you regularly make submissions to publishers
1.1  christos and editors who insist on "typewritten, double-spaced," there's a
1.1  christos special macro--
1.1  christos <a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>
1.1  christos --that changes typeset documents into ones that would make your
1.1  christos high-school typing teacher proud.  Footnotes, endnotes, tables of
1.1  christos contents, multiple columns, nested lists, recto/verso printing and
1.1  christos user designable headers and footers are also part of the fun.
1.1  christos <p>
1.1  christos <a name="INTRO_PHILOSOPHY">
1.1  christos 	<h2><u>Mom's philosophy</u></h2>
1.1  christos </a>
1.1  christos
1.1  christos Formatting documents should be easy, from soup to nuts.  Writers need
1.1  christos to focus on what they're writing, not on how it looks.  From the
1.1  christos moment you fire up an editor to the moment you add "FINIS"
1.1  christos to your opus, nothing should interfere with the flow of your words.
1.1  christos The commands needed to format your work should be easy to remember,
1.1  christos comprehensible, and stand out well from the text.  There shouldn't
1.1  christos be too much clutter.  Your documents should be as readable inside a
1.1  christos text editor as they are on the printed page.
1.1  christos <p>
1.1  christos Unfortunately, in computerland, &quot;easy,&quot;
1.1  christos &quot;comprehensible,&quot; and &quot;readable&quot; often mean
1.1  christos &quot;you're stuck with what you get.&quot; No document formatting
1.1  christos system can give you exactly what you want all the time, every time.
1.1  christos Documents, it seems, always need to be tweaked, either to satisfy a
1.1  christos typographic whim or to clarify some aspect of their content.
1.1  christos <p>
1.1  christos Groff has traditionally solved the problem of formatting vs. tweaking
1.1  christos by requiring users of the common macro packages (mm, ms, me and their
1.1  christos offspring) to resort to groff
1.1  christos <a href="definitions.html#TERMS_PRIMITIVES">primitives</a>
1.1  christos and
1.1  christos <a href="definitions.html#TERMS_INLINES">inline escapes</a>
1.1  christos for their special typesetting needs.  Not to put too fine a point on
1.1  christos it, groff primitives tend toward the abstruse, and most inline escapes
1.1  christos are about as readable in-line as an encrypted password.  This does
1.1  christos not make for happy-camper writers, who either find themselves stuck
1.1  christos with a document formatting style they don't really like, or are
1.1  christos forced to learn groff from the ground up--a daunting task, to say
1.1  christos the least.
1.1  christos <p>
1.1  christos <strong>Mom</strong> aims to make creating documents a simple matter,
1.1  christos but with no corresponding loss of user control.  The document
1.1  christos processing macros provide an excellent set of defaults, but if
1.1  christos something is not to your liking, you can change it.  And in combination
1.1  christos with the typesetting macros, you have all the tools you need to
1.1  christos massage passages and tweak pages until they look utterly professional.
1.1  christos <p>
1.1  christos One rarely hears the word &quot;user interface&quot; in conjunction
1.1  christos with document processing.  Since the user formatting takes place
1.1  christos inside a text editor, little thought is given to the look and feel
1.1  christos of the formatting commands.  <strong>Mom</strong> attempts to rectify
1.1  christos this by providing users with a consistent, readable &quot;coding&quot;
1.1  christos style.  Most of the macros (especially in the document processing set)
1.1  christos have humanly-readable names.  Not only does this speed up learning
1.1  christos the macros, it makes the sense of what's going on in a document,
1.1  christos typographically and structurally, easier to decipher.
1.1  christos <p>
1.1  christos <strong>Mom</strong> does not try to be all things to all people.
1.1  christos In contrast to the normal groff philosophy, she does not try to
1.1  christos produce output that looks good no matter where it's displayed.
1.1  christos She's designed for printed output, although with
1.1  christos <a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>
1.1  christos she produces acceptable terminal copy.  She makes no attempt to be
1.1  christos compatible with older versions of troff.
1.1  christos <p>
1.1  christos One special feature in <strong>mom</strong>'s design is the attention
1.1  christos she pays to aligning the bottom margins of every page.  Nothing screams
1.1  christos &quot;shoddy&quot; in typeset documents louder than bottom margins
1.1  christos that wander, or, in typesetter jargon, &quot;hang.&quot; There are,
1.1  christos of course, situations where whitespace at the bottom of a page may
1.1  christos be desirable (for example, you wouldn't want a head to appear at the
1.1  christos bottom of the page without some text underneath it), but in all cases
1.1  christos where hanging bottom margins can be avoided, <strong>mom</strong> does
1.1  christos avoid them, by clever adjustments to leading (&quot;line spacing&quot;)
1.1  christos and the spacing between different elements on the page.
1.1  christos <p>
1.1  christos <a name="INTRO_DOCUMENTATION">
1.1  christos 	<h2><u>A note on mom's documentation</u></h2>
1.1  christos </a>
1.1  christos
1.1  christos Writing documentation is tough, no doubt about it.  One is never
1.1  christos quite sure of the user's level of expertise.  Is s/he new to the
1.1  christos application, new to its underlying protocols and programs, new to
1.1  christos the operating system, new to computers?  At some point, one has to
1.1  christos decide who the documentation is for.  Making the wrong decision can
1.1  christos mean the difference between a program that gets used and a program
1.1  christos that gets tossed.
1.1  christos <p>
1.1  christos <strong>Mom</strong>'s documentation assumes users know their way
1.1  christos around GNU/Linux.  It further assumes they at least know what groff
1.1  christos is, even if they don't know much about it.  Lastly, it assumes that
1.1  christos everyone--groff newbies and experts alike--learns faster from
1.1  christos a few well-placed examples than from manpage-style reference docs.
1.1  christos What <strong>mom</strong>'s documentation doesn't assume is that
1.1  christos you know everything--not about groff, not about typesetting,
1.1  christos not about document processing.  Even experts have odd lacunae in
1.1  christos their knowledge base.  Therefore, whenever I suspect that a term
1.1  christos or procedure will cause head scratching, I offer an explanation.
1.1  christos And when explanations aren't enough, I offer examples.
1.1  christos <br>
1.1  christos
1.1  christos <a name="CANONICAL"><h3><u>Canonical reference materials</u></h3></a>
1.1  christos <p>
1.1  christos The canonical reference materials for groff are
1.1  christos <strong>cstr54</strong> (a downloadable PostScript copy of which is
1.1  christos available
1.1  christos <a href="http://www.kohala.com/start/troff/">here</a>)
1.1  christos and the <strong>troff</strong> and <strong>groff_diff</strong>
1.1  christos manpages.  Another excellent source of information (maybe the best)
1.1  christos is the groff <strong>info</strong> pages, available by typing
1.1  christos <p>
1.1  christos <pre>
1.1  christos 	info groff
1.1  christos </pre>
1.1  christos
1.1  christos at the command line (assuming you have <strong>info</strong>
1.1  christos installed on your system).  And for inputting special characters,
1.1  christos see <strong>man groff_char.</strong>
1.1  christos <p>
1.1  christos I've tried to avoid reiterating the information contained in these
1.1  christos documents; however, in a few places, this has proved impossible.
1.1  christos But be forewarned: I have no qualms about sidestepping excruciating
1.1  christos completeness concerning groff usage; I'm more interested in getting
1.1  christos <strong>mom</strong> users up and running. <em>Mea culpa.</em>
1.1  christos <p>
1.1  christos <strong>Note:</strong> <strong>Mom</strong>'s macro file
1.1  christos (om.tmac) is heavily commented.  Each macro is preceded by a
1.1  christos description of its arguments, function and usage, which may
1.1  christos give you information in addition to what's contained in this
1.1  christos documentation.
1.1  christos <p>
1.1  christos <a name="MACRO_ARGS">
1.1  christos 	<h3><u>How to read macro arguments</u></h3>
1.1  christos </a>
1.1  christos
1.1  christos The concise descriptions of macros in this documentation typically
1.1  christos look like this:
1.1  christos <blockquote>
1.1  christos Macro: <strong>NAME</strong> <nobr>arguments</nobr>
1.1  christos </blockquote>
1.1  christos <var>arguments</var> lists the macro's arguments using conventions that
1.1  christos should be familiar to anyone who has ever read a manpage.  Briefly:
1.1  christos <p>
1.1  christos <ol>
1.1  christos 	<li>Macro arguments are separated from each other by spaces.
1.1  christos 	<li>If an argument is surrounded by chevrons
1.1  christos 		(&nbsp;&lt;&nbsp;&gt;&nbsp;), it's a description of the argument,
1.1  christos 		not the argument itself.
1.1  christos 	<li>If an argument begins with or is surrounded by double-quotes, the
1.1  christos 		double quotes MUST be included in the argument.
1.1  christos 	<li>If the user has a choice between several arguments, each of the
1.1  christos 		choices is separated by the pipe character (&nbsp;|&nbsp;),
1.1  christos 		which means &quot;or.&quot;
1.1  christos 	<li>Arguments that are optional are surrounded by square brackets.
1.1  christos 	<li>&lt;off&gt; in an argument list means that any argument
1.1  christos 	    other than those in the argument list turns the macro off.
1.1  christos </ol>
1.1  christos
1.1  christos <a name="TOGGLE_MACRO"><h3><u>Toggle macros</u></h3></a>
1.1  christos <p>
1.1  christos Some macros don't require an argument.  They simply start something.
1.1  christos When you need to turn them off, the same macro with <em>any</em>
1.1  christos argument will do the trick.  That's right: ANY argument.  This permits
1.1  christos choosing whatever works for you: OFF, END, QUIT, DONE, Q, X...  Hell,
1.1  christos it could even be I_LOVE_MOM.
1.1  christos <p>
1.1  christos Since these macros toggle things on and off, the argument list
1.1  christos simply reads
1.1  christos <blockquote>
1.1  christos <nobr>toggle</nobr>
1.1  christos </blockquote>
1.1  christos <br>
1.1  christos <hr>
1.1  christos
1.1  christos <h3>Example 1: an argument requiring double-quotes</h3>
1.1  christos <blockquote>
1.1  christos Macro: <strong>TITLE</strong> <nobr>&quot;&lt;title of document&gt;&quot;</nobr>
1.1  christos </blockquote>
1.1  christos <p>
1.1  christos The required argument to <strong>TITLE</strong> is the title of your
1.1  christos document.  Since it's surrounded by double-quotes, you must
1.1  christos include them in the argument, like this:
1.1  christos <p>
1.1  christos <pre>
1.1  christos 	.TITLE "My Pulitzer Novel"
1.1  christos </pre>
1.1  christos
1.1  christos <h3>Example 2: a macro with required and optional arguments</h3>
1.1  christos <blockquote>
1.1  christos Macro: <strong>TAB_SET</strong> <nobr>&lt;tab #&gt;  &lt;indent&gt;  &lt;length&gt;  [ L | R | C | J [ QUAD ] ]</nobr>
1.1  christos </blockquote>
1.1  christos <p>
1.1  christos The first required argument is a number that identifies the tab (say,
1.1  christos "3").  The second required argument is an indent from the left margin
1.1  christos (say, 6 picas).  The third required argument is the length of the tab
1.1  christos (say, 3 picas).  Therefore, at a minimum, when using this macro,
1.1  christos you would enter:
1.1  christos <p>
1.1  christos <pre>
1.1  christos 	.TAB_SET 3 6P 3P
1.1  christos </pre>
1.1  christos
1.1  christos The remaining two arguments are optional.  The first is a single
1.1  christos letter, either L, R, C or J.  The second, which is itself optional
1.1  christos after L, R, C or J, is the word QUAD.  Therefore, depending on
1.1  christos what additional information you wish to pass to the macro,
1.1  christos you could enter:
1.1  christos <p>
1.1  christos <pre>
1.1  christos 	.TAB_SET 3 6P 3P L
1.1  christos 		or
1.1  christos 	.TAB_SET 3 6P 3P L QUAD
1.1  christos </pre>
1.1  christos
1.1  christos <a name="TOGGLE_EXAMPLE"></a>
1.1  christos <h3>Example 3: a sample toggle macro:</h3>
1.1  christos <blockquote>
1.1  christos Macro: <strong>QUOTE</strong> <nobr>toggle</nobr>
1.1  christos </blockquote>
1.1  christos <p>
1.1  christos <strong>QUOTE</strong> begins a section of quoted text in a document
1.1  christos and doesn't require an argument.  When the quote's finished,
1.1  christos you have to tell <strong>mom</strong> it's done.
1.1  christos <p>
1.1  christos <pre>
1.1  christos 	.QUOTE
1.1  christos 	So runs my dream, but what am I?
1.1  christos 	An infant crying in the night
1.1  christos 	An infant crying for the light
1.1  christos 	And with no language but a cry.
1.1  christos 	.QUOTE OFF
1.1  christos </pre>
1.1  christos
1.1  christos Alternatively, you could have turned the quote off with END, or
1.1  christos X, or something else.
1.1  christos
1.1  christos <p>
1.1  christos <hr>
1.1  christos <a href="definitions.html#TOP">Next</a>&nbsp;&nbsp;
1.1  christos <a href="#TOP">Top</a>&nbsp;&nbsp;
1.1  christos <a href="toc.html">Table of Contents</a>
1.1  christos </body>
1.1  christos </html>