1151497Sru<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> 2104862Sru<html> 3104862Sru<head> 4104862Sru<meta http-equiv="content-type" content="text/html;charset=iso-8859-1"> 5104862Sru<title>What is mom?</title> 6104862Sru</head> 7104862Sru<body bgcolor="#dfdfdf"> 8104862Sru 9104862Sru<!====================================================================> 10104862Sru 11104862Sru<a href="definitions.html#TOP">Next</a> 12104862Sru<a href="toc.html">Back to Table of Contents</a> 13104862Sru 14104862Sru<a name="TOP"></a> 15104862Sru<a name="INTRO"> 16104862Sru <h1 align="center"><u>WHAT IS MOM?</u></h1> 17104862Sru</a> 18104862Sru 19104862Sru<a href="#INTRO_INTRO">Who is mom meant for?</a> 20104862Sru<br> 21104862Sru<a href="#INTRO_TYPESETTING">Typesetting with mom</a> 22104862Sru<br> 23104862Sru<a href="#INTRO_DOCPROCESSING">Document processing with mom</a> 24104862Sru<br> 25104862Sru<a href="#INTRO_PHILOSOPHY">Mom's philosophy</a> 26104862Sru<br> 27104862Sru<a href="#INTRO_DOCUMENTATION">A note on mom's documentation</a> 28104862Sru<br> 29151497Sru<a href="#CANONICAL">Canonical reference materials</a> 30151497Sru<br> 31104862Sru<a href="#MACRO_ARGS">How to read macro arguments</a> 32104862Sru 33104862Sru<h2><a name="INTRO_INTRO"><u>Who is mom meant for?</u></a></h2> 34104862Sru 35104862Sru<strong>Mom</strong> ("my own macros", "my other 36104862Srumacros", "maximum overdrive macros"...) is a macro set for 37104862Srugroff, designed to format documents for PostScript output. 38104862SruShe's aimed at three kinds of users: 39104862Sru<br> 40104862Sru<ol> 41104862Sru <li>typesetters who suspect groff might be "the right 42104862Sru tool for the job" but who are 43104862Sru frustrated/intimidated by groff's terse, geeky, 44104862Sru not-always-typographically-intuitive 45104862Sru <a href="definitions.html#TERMS_PRIMITIVES">primitives</a>; 46104862Sru <br> 47104862Sru <li>non-scientific writers (novelists, short story writers, 48104862Sru journalists, students) who just want their work to 49104862Sru look good; 50104862Sru <br> 51104862Sru <li>newbies to computer typesetting, document processing, or 52104862Sru groff who need a well-documented macro set to help them get 53104862Sru started. 54104862Sru</ol> 55104862Sru<p> 56151497SruAs might be inferred from the above, <strong>mom</strong> is two macro 57104862Srupackages in one: a set of typesetting macros, and a set of document 58104862Sruprocessing macros. The typesetting macros govern the physical 59104862Sruaspects of page layout and provide sane, comprehensible control over 60104862Srutypographic refinements. The document processing macros let you focus 61104862Sruon a document's content and logical structure without worrying about 62104862Srutypesetting or page layout at all. 63104862Sru<p> 64104862SruBecause <strong>mom</strong> provides both typesetting and document 65104862Sruprocessing macros, it's safe to say she blurs the distinction between 66104862Srudocument processing and document design. While her basic document style 67151497Srucomes with pretty spiffy defaults (okay--change "spiffy" 68104862Sruto "typographically professional"), you can easily control 69104862Sruhow all the various document elements look: titles, page headers and 70104862Srufooters, page numbering, heads, subheads, footnotes and so on can be 71104862Srumade to come out exactly the way you want. And should you need precise 72104862Srutypographic control over elements in a document that fall outside the 73104862Srurange of <strong>mom</strong>'s document element tags, you don't have to 74104862Sruread up on groff 75104862Sru<a href="definitions.html#TERMS_PRIMITIVES">primitives</a> 76104862Sruin order to accomplish what you want; the typesetting macros take 77104862Srucare of that. 78151497Sru<p> 79104862Sru 80104862Sru<a name="INTRO_TYPESETTING"> 81104862Sru <h2><u>Typesetting with mom</u></h2> 82104862Sru</a> 83104862Sru 84104862Sru<strong>Mom</strong>'s typesetting macros control the basic parameters 85104862Sruof type: margins, line length, type family, font, point size, 86104862Srulinespacing, and so on. In addition, they allow you to move around 87104862Sruon the page horizontally and vertically, and to set up tabs, indents, 88104862Sruand columns. Finally, they let you adjust such typographic details as 89104862Srujustification style, letter spacing, word spacing, hyphenation, and 90104862Srukerning. 91104862Sru 92104862Sru<p> 93104862SruIn terms of typographic control, these macros resemble the 94104862Srucommands used on dedicated typesetting computers like Compugraphics and 95104862SruLinotronics. Most of them simply give access to groff's typesetting 96104862Sruprimitives in a way that's consistent and easy to use. A few of 97104862Sruthem (tabs and indents, for example) handle fundamental typesetting 98104862Srurequirements in ways radically different from groff primitives. 99104862Sru 100104862Sru<p> 101104862SruWith <strong>mom</strong>'s typesetting macros, you can, if you wish, 102104862Srucreate individual output pages that you design from the ground up. 103104862SruProvided you have not signalled to <strong>mom</strong> that you 104104862Sruwant document processing (via the 105104862Sru<a href="docprocessing.html#START">START</a> 106104862Srumacro; see below), every macro is a literal command that remains in 107104862Srueffect until you modify it or turn it off. This means that if you 108151497Sruwant to create flyers, surveys, tabulated forms, curricula vitae and 109151497Sruso on, you may do so in the good old-fashioned way: one step at a 110151497Srutime with complete control over every element on the page. 111104862Sru<p> 112104862SruYears of reading various mailing lists dealing with computer 113151497Srutypesetting (groff, TeX, and friends) have convinced me that no program 114104862Srucan ever replace the human eye and human input when it comes to high 115104862Sruquality typesetting. As of this writing, a thread on the subject of 116104862Sru"micro typography" in groff has been going on for nearly a 117104862Srumonth. The reason for the lengthy thread is obvious; words and 118104862Srupunctuation on the printed page are too variable, too fluid, to be 119104862Srurendered flawlessly by any algorithm, no matter how clever. (For 120104862Sruwhatever it's worth, a similar problem exists with engraving musical 121104862Sruscores by computer.) 122104862Sru<p> 123151497Sru<strong>Mom</strong> does not try to solve the problems posed 124151497Sruby things like hanging punctuation, left-margin adjustments for 125151497Sruupper case letters like T and W, and so on. She merely tries to 126151497Sruprovide tools that allow knowledgeable typesetters to come up with 127151497Srusolutions to these problems in ways that are easier and more 128151497Sruintuitive than manipulating groff at the 129151497Sru<a href="definitions.html#TERMS_PRIMITIVES">primitive</a> 130104862Srulevel. As a professional typesetter of more than two decades, and a 131104862Sruwriter, I have encountered few situations that cannot be handled by 132104862Sru<strong>mom</strong>'s typesetting macros. 133104862Sru<p> 134104862Sru<strong>Author's note:</strong> One area where groff itself needs 135104862Sruserious rethinking is in the matter of an algorithm that takes into 136151497Sruaccount both word and letter spacing when 137104862Sru<a href="definitions.html#TERMS_JUST">justifying</a> 138104862Srulines. At present, only word spacing is adjusted, requiring what I 139104862Sruconsider an unnecessary amount of user intervention whenever 140104862Sruletter spacing is required. 141151497Sru<p> 142104862Sru<a name="INTRO_DOCPROCESSING"> 143104862Sru <h2><u>Document processing with mom</u></h2> 144104862Sru</a> 145104862Sru 146104862Sru<strong>Mom</strong>'s document processing macros let you format 147104862Srudocuments without having to worry about the typographic details. 148104862SruIn this respect, <strong>mom</strong> is similar to other groff macro 149104862Srupackages, as well as to html and LaTeX. Where <strong>mom</strong> 150104862Srudiffers is in the degree of control you have over the look and 151104862Sruplacement of the various elements of a document. For example, if you 152104862Srudon't want your heads underlined, or you want them bigger/smaller, 153104862Sruor you'd prefer them to be in a different font, or you'd rather they 154151497Sruwere flush left instead of centred, you can make the changes easily 155104862Sruand have them apply to the whole document. Temporary and one-off 156104862Sruchanges are easy, too. 157104862Sru<p> 158104862Sru<strong>Mom</strong> has some nifty features other macro sets 159104862Srudon't provide. For example, you can switch between draft-style and 160104862Srufinal-copy output. If you regularly make submissions to publishers 161104862Sruand editors who insist on "typewritten, double-spaced," there's a 162151497Sruspecial macro-- 163104862Sru<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a> 164151497Sru--that changes typeset documents into ones that would make your 165151497Sruhigh-school typing teacher proud. Footnotes, endnotes, tables of 166151497Srucontents, multiple columns, nested lists, recto/verso printing and 167151497Sruuser designable headers and footers are also part of the fun. 168151497Sru<p> 169104862Sru<a name="INTRO_PHILOSOPHY"> 170104862Sru <h2><u>Mom's philosophy</u></h2> 171104862Sru</a> 172104862Sru 173104862SruFormatting documents should be easy, from soup to nuts. Writers need 174104862Sruto focus on what they're writing, not on how it looks. From the 175104862Srumoment you fire up an editor to the moment you add "FINIS" 176104862Sruto your opus, nothing should interfere with the flow of your words. 177104862SruThe commands needed to format your work should be easy to remember, 178104862Srucomprehensible, and stand out well from the text. There shouldn't 179104862Srube too much clutter. Your documents should be as readable inside a 180104862Srutext editor as they are on the printed page. 181104862Sru<p> 182104862SruUnfortunately, in computerland, "easy," 183104862Sru"comprehensible," and "readable" often mean 184114402Sru"you're stuck with what you get." No document formatting 185104862Srusystem can give you exactly what you want all the time, every time. 186104862SruDocuments, it seems, always need to be tweaked, either to satisfy a 187104862Srutypographic whim or to clarify some aspect of their content. 188104862Sru<p> 189104862SruGroff has traditionally solved the problem of formatting vs. tweaking 190104862Sruby requiring users of the common macro packages (mm, ms, me and their 191104862Sruoffspring) to resort to groff 192104862Sru<a href="definitions.html#TERMS_PRIMITIVES">primitives</a> 193104862Sruand 194104862Sru<a href="definitions.html#TERMS_INLINES">inline escapes</a> 195104862Srufor their special typesetting needs. Not to put too fine a point on 196104862Sruit, groff primitives tend toward the abstruse, and most inline escapes 197104862Sruare about as readable in-line as an encrypted password. This does 198104862Srunot make for happy-camper writers, who either find themselves stuck 199151497Sruwith a document formatting style they don't really like, or are 200151497Sruforced to learn groff from the ground up--a daunting task, to say 201151497Sruthe least. 202104862Sru<p> 203104862Sru<strong>Mom</strong> aims to make creating documents a simple matter, 204104862Srubut with no corresponding loss of user control. The document 205104862Sruprocessing macros provide an excellent set of defaults, but if 206104862Srusomething is not to your liking, you can change it. And in combination 207104862Sruwith the typesetting macros, you have all the tools you need to 208104862Srumassage passages and tweak pages until they look utterly professional. 209104862Sru<p> 210104862SruOne rarely hears the word "user interface" in conjunction 211104862Sruwith document processing. Since the user formatting takes place 212104862Sruinside a text editor, little thought is given to the look and feel 213104862Sruof the formatting commands. <strong>Mom</strong> attempts to rectify 214104862Sruthis by providing users with a consistent, readable "coding" 215104862Srustyle. Most of the macros (especially in the document processing set) 216104862Sruhave humanly-readable names. Not only does this speed up learning 217104862Sruthe macros, it makes the sense of what's going on in a document, 218104862Srutypographically and structurally, easier to decipher. 219104862Sru<p> 220104862Sru<strong>Mom</strong> does not try to be all things to all people. 221104862SruIn contrast to the normal groff philosophy, she does not try to 222104862Sruproduce output that looks good no matter where it's displayed. 223104862SruShe's designed for printed output, although with 224104862Sru<a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a> 225104862Srushe produces acceptable terminal copy. She makes no attempt to be 226151497Srucompatible with older versions of troff. 227104862Sru<p> 228104862SruOne special feature in <strong>mom</strong>'s design is the attention 229104862Srushe pays to aligning the bottom margins of every page. Nothing screams 230104862Sru"shoddy" in typeset documents louder than bottom margins 231104862Sruthat wander, or, in typesetter jargon, "hang." There are, 232104862Sruof course, situations where whitespace at the bottom of a page may 233104862Srube desirable (for example, you wouldn't want a head to appear at the 234104862Srubottom of the page without some text underneath it), but in all cases 235104862Sruwhere hanging bottom margins can be avoided, <strong>mom</strong> does 236104862Sruavoid them, by clever adjustments to leading ("line spacing") 237104862Sruand the spacing between different elements on the page. 238151497Sru<p> 239104862Sru<a name="INTRO_DOCUMENTATION"> 240104862Sru <h2><u>A note on mom's documentation</u></h2> 241104862Sru</a> 242104862Sru 243104862SruWriting documentation is tough, no doubt about it. One is never 244104862Sruquite sure of the user's level of expertise. Is s/he new to the 245104862Sruapplication, new to its underlying protocols and programs, new to 246104862Sruthe operating system, new to computers? At some point, one has to 247104862Srudecide who the documentation is for. Making the wrong decision can 248104862Srumean the difference between a program that gets used and a program 249104862Sruthat gets tossed. 250104862Sru<p> 251104862Sru<strong>Mom</strong>'s documentation assumes users know their way 252104862Sruaround GNU/Linux. It further assumes they at least know what groff 253104862Sruis, even if they don't know much about it. Lastly, it assumes that 254151497Srueveryone--groff newbies and experts alike--learns faster from 255104862Srua few well-placed examples than from manpage-style reference docs. 256104862SruWhat <strong>mom</strong>'s documentation doesn't assume is that 257151497Sruyou know everything--not about groff, not about typesetting, 258104862Srunot about document processing. Even experts have odd lacunae in 259104862Srutheir knowledge base. Therefore, whenever I suspect that a term 260104862Sruor procedure will cause head scratching, I offer an explanation. 261104862SruAnd when explanations aren't enough, I offer examples. 262151497Sru<br> 263151497Sru 264151497Sru<a name="CANONICAL"><h3><u>Canonical reference materials</u></h3></a> 265104862Sru<p> 266151497SruThe canonical reference materials for groff are 267151497Sru<strong>cstr54</strong> (a downloadable PostScript copy of which is 268151497Sruavailable 269104862Sru<a href="http://www.kohala.com/start/troff/">here</a>) 270151497Sruand the <strong>troff</strong> and <strong>groff_diff</strong> 271151497Srumanpages. Another excellent source of information (maybe the best) 272151497Sruis the groff <strong>info</strong> pages, available by typing 273104862Sru<p> 274151497Sru<pre> 275151497Sru info groff 276151497Sru</pre> 277151497Sru 278151497Sruat the command line (assuming you have <strong>info</strong> 279151497Sruinstalled on your system). And for inputting special characters, 280151497Srusee <strong>man groff_char.</strong> 281151497Sru<p> 282151497SruI've tried to avoid reiterating the information contained in these 283151497Srudocuments; however, in a few places, this has proved impossible. 284151497SruBut be forewarned: I have no qualms about sidestepping excruciating 285151497Srucompleteness concerning groff usage; I'm more interested in getting 286151497Sru<strong>mom</strong> users up and running. <em>Mea culpa.</em> 287151497Sru<p> 288104862Sru<strong>Note:</strong> <strong>Mom</strong>'s macro file 289104862Sru(om.tmac) is heavily commented. Each macro is preceded by a 290151497Srudescription of its arguments, function and usage, which may 291104862Srugive you information in addition to what's contained in this 292104862Srudocumentation. 293151497Sru<p> 294104862Sru<a name="MACRO_ARGS"> 295104862Sru <h3><u>How to read macro arguments</u></h3> 296104862Sru</a> 297104862Sru 298104862SruThe concise descriptions of macros in this documentation typically 299104862Srulook like this: 300104862Sru<blockquote> 301151497SruMacro: <strong>NAME</strong> <nobr>arguments</nobr> 302104862Sru</blockquote> 303104862Sru<var>arguments</var> lists the macro's arguments using conventions that 304104862Srushould be familiar to anyone who has ever read a manpage. Briefly: 305104862Sru<p> 306104862Sru<ol> 307104862Sru <li>Macro arguments are separated from each other by spaces. 308104862Sru <li>If an argument is surrounded by chevrons 309104862Sru ( < > ), it's a description of the argument, 310104862Sru not the argument itself. 311104862Sru <li>If an argument begins with or is surrounded by double-quotes, the 312104862Sru double quotes MUST be included in the argument. 313104862Sru <li>If the user has a choice between several arguments, each of the 314104862Sru choices is separated by the pipe character ( | ), 315104862Sru which means "or." 316104862Sru <li>Arguments that are optional are surrounded by square brackets. 317104862Sru <li><off> in an argument list means that any argument 318151497Sru other than those in the argument list turns the macro off. 319104862Sru</ol> 320104862Sru 321104862Sru<a name="TOGGLE_MACRO"><h3><u>Toggle macros</u></h3></a> 322104862Sru<p> 323104862SruSome macros don't require an argument. They simply start something. 324104862SruWhen you need to turn them off, the same macro with <em>any</em> 325104862Sruargument will do the trick. That's right: ANY argument. This permits 326104862Sruchoosing whatever works for you: OFF, END, QUIT, DONE, Q, X... Hell, 327104862Sruit could even be I_LOVE_MOM. 328104862Sru<p> 329104862SruSince these macros toggle things on and off, the argument list 330104862Srusimply reads 331104862Sru<blockquote> 332151497Sru<nobr>toggle</nobr> 333104862Sru</blockquote> 334151497Sru<br> 335104862Sru<hr> 336104862Sru 337104862Sru<h3>Example 1: an argument requiring double-quotes</h3> 338104862Sru<blockquote> 339151497SruMacro: <strong>TITLE</strong> <nobr>"<title of document>"</nobr> 340104862Sru</blockquote> 341151497Sru<p> 342104862SruThe required argument to <strong>TITLE</strong> is the title of your 343104862Srudocument. Since it's surrounded by double-quotes, you must 344104862Sruinclude them in the argument, like this: 345104862Sru<p> 346104862Sru<pre> 347104862Sru .TITLE "My Pulitzer Novel" 348104862Sru</pre> 349104862Sru 350104862Sru<h3>Example 2: a macro with required and optional arguments</h3> 351104862Sru<blockquote> 352151497SruMacro: <strong>TAB_SET</strong> <nobr><tab #> <indent> <length> [ L | R | C | J [ QUAD ] ]</nobr> 353104862Sru</blockquote> 354151497Sru<p> 355104862SruThe first required argument is a number that identifies the tab (say, 356104862Sru"3"). The second required argument is an indent from the left margin 357104862Sru(say, 6 picas). The third required argument is the length of the tab 358104862Sru(say, 3 picas). Therefore, at a minimum, when using this macro, 359104862Sruyou would enter: 360104862Sru<p> 361104862Sru<pre> 362104862Sru .TAB_SET 3 6P 3P 363104862Sru</pre> 364104862Sru 365104862SruThe remaining two arguments are optional. The first is a single 366104862Sruletter, either L, R, C or J. The second, which is itself optional 367104862Sruafter L, R, C or J, is the word QUAD. Therefore, depending on 368104862Sruwhat additional information you wish to pass to the macro, 369104862Sruyou could enter: 370104862Sru<p> 371104862Sru<pre> 372104862Sru .TAB_SET 3 6P 3P L 373104862Sru or 374104862Sru .TAB_SET 3 6P 3P L QUAD 375104862Sru</pre> 376104862Sru 377151497Sru<a name="TOGGLE_EXAMPLE"></a> 378151497Sru<h3>Example 3: a sample toggle macro:</h3> 379104862Sru<blockquote> 380151497SruMacro: <strong>QUOTE</strong> <nobr>toggle</nobr> 381104862Sru</blockquote> 382151497Sru<p> 383104862Sru<strong>QUOTE</strong> begins a section of quoted text in a document 384104862Sruand doesn't require an argument. When the quote's finished, 385104862Sruyou have to tell <strong>mom</strong> it's done. 386104862Sru<p> 387104862Sru<pre> 388104862Sru .QUOTE 389104862Sru So runs my dream, but what am I? 390104862Sru An infant crying in the night 391104862Sru An infant crying for the light 392104862Sru And with no language but a cry. 393104862Sru .QUOTE OFF 394104862Sru</pre> 395104862Sru 396104862SruAlternatively, you could have turned the quote off with END, or 397104862SruX, or something else. 398104862Sru 399104862Sru<p> 400104862Sru<hr> 401104862Sru<a href="definitions.html#TOP">Next</a> 402104862Sru<a href="#TOP">Top</a> 403104862Sru<a href="toc.html">Table of Contents</a> 404104862Sru</body> 405104862Sru</html> 406