diff options
Diffstat (limited to 'contrib/mom/momdoc/goodies.html')
| -rw-r--r-- | contrib/mom/momdoc/goodies.html | 1435 |
1 files changed, 1435 insertions, 0 deletions
diff --git a/contrib/mom/momdoc/goodies.html b/contrib/mom/momdoc/goodies.html new file mode 100644 index 00000000..db30bc33 --- /dev/null +++ b/contrib/mom/momdoc/goodies.html @@ -0,0 +1,1435 @@ +<?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>Mom -- Goodies</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="inlines.html#TOP">Next</a> +<a href="typesetting.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<a name="GOODIES"><h1 align="center"><u>Goodies</u></h1></a> + +<p> +The macros in this section are a collection of useful (and sometimes +nearly indispensable) routines to simplify typesetting. +</p> + +<a name="INDEX_GOODIES"><h3><u>Goodies list</u></h3></a> + +<ul> + <li><a href="#ALIAS">ALIAS</a> (rename macros)</li> + <li><a href="#SILENT">SILENT</a> ("hide" input lines from output)</li> + <li><a href="#TRAP">TRAP</a> (suspend/re-invoke traps)</li> + <li><a href="#SMARTQUOTES">SMARTQUOTES</a> (convert typewriter doublequotes to proper doublequotes)</li> + <li><a href="#CAPS">CAPS</a> (convert to upper case)</li> + <li><a href="#STRING">STRING</a> (user-definable strings)</li> + <li><a href="#ESC_CHAR">ESC_CHAR</a> (change to escape character to something other than a backslash)</li> + <li><strong>Underscore/underline</strong></li> + <ul> + <li><a href="#UNDERSCORE">UNDERSCORE</a> (single underscore)</li> + <li><a href="#UNDERSCORE2">UNDERSCORE2</a> (double underscore)</li> + <li><a href="#UNDERLINE">UNDERLINE</a> (underline — Courier only!)</li> + <li><a href="#UL">\*[UL]</a> (inline escape to underline — Courier only!)</li> + </ul> + <li><strong>Padding</strong></li> + <ul> + <li><a href="#PAD">PAD</a> (insert equalized space into lines)</li> + <li><a href="#PAD_MARKER">PAD_MARKER</a> (change/set the marker used with <strong>PAD</strong>)</li> + </ul> + <li><strong>Leaders</strong></li> + <ul> + <li><a href="#LEADER">\*[LEADER]</a> (inline escape to add leaders to a line)</li> + <li><a href="#LEADER_CHARACTER">LEADER_CHARACTER</a> (change/set the leader character)</li> + </ul> + <li><strong>Drop caps</strong></li> + <ul> + <li><a href="#DROPCAP">DROPCAP</a> (set a drop cap)</li> + <li><strong>Support macros for DROPCAP</strong></li> + <ul> + <li><a href="#DROPCAP_FAMILY">DROPCAP_FAMILY</a> (change drop cap family)</li> + <li><a href="#DROPCAP_FONT">DROPCAP_FONT</a> (change drop cap font)</li> + <li><a href="#DROPCAP_ADJUST">DROPCAP_ADJUST</a> (alter size of drop cap)</li> + <li><a href="#DROPCAP_COLOR">DROPCAP_COLOR</a> (change colour of drop cap)</li> + <li><a href="#DROPCAP_GUTTER">DROPCAP_GUTTER</a> (change space between drop cap and running text)</li> + </ul> + </ul> + <li><strong>Superscripts</strong></li> + <ul> + <li><a href="#SUP">\*[SUP]</a> (set superscript)</li> + <li><a href="#CONDSUP">\*[CONDSUP]</a> (set condensed superscript)</li> + <li><a href="#EXTSUP">\*[EXTSUP]</a> (set extended superscript)</li> + </ul> + <li><strong>Lists</strong></li> + <ul> + <li><a href="docelement.html#LIST_INTRO">Introduction to lists</a></li> + <li><a href="docelement.html#LIST">LIST</a></li> + <li><a href="docelement.html#ITEM">ITEM</a></li> + <li><a href="docelement.html#SHIFT_LIST">SHIFT_LIST</a></li> + <li><a href="docelement.html#RESET_LIST">RESET_LIST</a></li> + <li><a href="docelement.html#PAD_LIST_DIGITS">PAD_LIST_DIGITS</a></li> + </ul> +</ul> + +<!-- -ALIAS- --> + +<hr width="66%" align="left"/> + +<a name="ALIAS"><h3><u>Rename macros</u></h3></a> + +<p> +<nobr>Macro: <strong>ALIAS</strong> <kbd><new name> <old name></kbd></nobr> +</p> + +<p> +The <strong>ALIAS</strong> macro may well be your best friend. +With it, you can change the name of a macro to anything you +like (provided the new name is not already being used by +<strong>mom</strong>; see the +<a href="reserved.html#RESERVED">list of reserved words</a>). +</p> + +<p> +Groff has always been a bit intimidating for new users because +its standard macro packages use very terse macro names. +<strong>Mom</strong> doesn't like people to feel intimidated; +she wants them to feel welcome. Consequently, she tries +for easy-to-grasp, self-explanatory macro names. However, +<strong>mom</strong> knows that people have their own ways of +thinking, their own preferences, their own habits. Some of her +macro names may not suit you; they might be too long, or aren't what +you automatically think of when you want to do a particular thing, +or might conflict with habits you've developed over the years. +</p> + +<p> +If you don't like one of <strong>mom</strong>'s macro names, +say, PAGEWIDTH, change it, like this: + +<pre> + .ALIAS PW PAGEWIDTH + | | + new__| |__official + name name +</pre> +</p> + +<p> +The first argument to <strong>ALIAS</strong> is the new name you +want for a macro. The second is the "official" name by +which the macro is normally invoked. After <strong>ALIAS</strong>, +either can be used. +</p> + +<p> +Note that in <strong>ALIAS</strong>, you do NOT include the period +(dot) that precedes the macro when it's a +<a href="definitions.html#TERMS_CONTROLLINES">control line</a>. +</p> + +<p> +<strong>NOTE:</strong> If you use <strong>ALIAS</strong> a lot, and +always for the same things, consider creating an aliases file of the +form + +<pre> + .ALIAS <new name> <old name> + .ALIAS <new name> <old name> + .ALIAS <new name> <old name> + ...etc +</pre> + +Put the file someplace convenient and source it (include it) at the +beginning of your documents with the +<a href="docprocessing.html#INCLUDE">INCLUDE</a> +macro. Assuming that you've created an aliases file +called <kbd>mom_aliases</kbd> in your home directory under +a directory called <kbd>Mom</kbd>, you'd source it by placing + +<pre> + .INCLUDE /home/<username>/Mom/mom_aliases +</pre> + +at the top of your documents. +</p> + +<p> +If you share documents that make use of an alias file, remember that +other people don't have the file! Paste the whole thing at the top +of your documents, please. +</p> + +<p> +<strong>EXPERTS:</strong> <strong>ALIAS</strong> is an alias +of <kbd>.als</kbd>. You can use either, or mix 'n' match with +impunity. +</p> + +<!-- -SILENT- --> + +<hr width="33%" align="left"/> + +<a name="SILENT"><h3><u>Hide input lines from output</u></h3></a> + +<p> +<nobr>Macro: <strong>SILENT</strong> <kbd>toggle</kbd></nobr> +<br/> + +Alias: <strong>COMMENT</strong> +</p> + +<p> +Sometimes, you want to "hide" +<a href="definitions.html#TERMS_INPUTLINE">input lines</a> +from final output. This is most likely to be the case when setting +up string tabs (see the +<a href="typesetting.html#STRING_TABS_TUT">quickie tutorial on string tabs</a> +for an example), but there are other places where you might want input +lines to be invisible as well. Any place you don't want input lines +to appear in the output, use the <strong>SILENT</strong> macro. +</p> + +<p> +<strong>SILENT</strong> is a toggle. Invoking it without an argument +turns it on; any argument turns it off. E.g., + +<pre> + .SILENT + A line of text + .SILENT OFF +</pre> +</p> + +<p> +The line "A line of text" will not appear in the +output copy. +</p> + +<p> +<strong>SILENT</strong> is aliased as <strong>COMMENT</strong>. +If you want to insert non-printing comments into your documents, +you may prefer this. +</p> + +<p> +<strong>NOTE: SILENT</strong> does not automatically break an +<a href="definitions.html#TERMS_INPUTLINE">input line</a> +(see +<a href="typesetting.html#BR">BR</a>) +when you're in one of the +<a href="definitions.html#TERMS_FILLED">fill modes</a> +(<a href="typesetting.html#JUSTIFY">JUSTIFY</a> +or +<a href="typesetting.html#QUAD">QUAD L | R | C | J</a>). +The same applies to tabs +(<a href="typesetting.html#TAB_SET">typesetting</a> +or +<a href="typesetting.html#ST">string</a>) +to which you've passed the <strong>J</strong> or +<strong>QUAD</strong> argument. You must insert <kbd>.BR</kbd> +yourself, or risk a portion of your text disappearing into a black +hole. +</p> + +<!-- -TRAP- --> + +<hr width="33%" align="left"/> + +<a name="TRAP"><h3><u>Suspend/re-invoke traps</u></h3></a> + +<p> +<nobr>Macro: <strong>TRAP</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +Traps are vertical positions on the output page at which you or +<strong>mom</strong> have instructed groff to start doing something +automatically. Commonly, this is near the bottom of the page, where +automatic behind-the-scenes processing is needed in order for one +page to finish and another to start. +</p> + +<p> +Sometimes, traps get sprung when you don't want them. If this +happens, surround just the offending macros and input lines with + +<pre> + .TRAP OFF + ... + .TRAP +</pre> +</p> + +<p> +<strong>TRAP</strong> is a toggle, therefore any argument +turns it off (i.e. suspends the trap), and no argument turns it +(back) on. +</p> + +<!-- -SMARTQUOTES- --> + +<hr width="33%" align="left"/> + +<a name="SMARTQUOTES"><h3><u>Convert typewriter doublequotes to proper doublequotes</u></h3></a> + +<p> +<nobr>Macro: <strong>SMARTQUOTES</strong> <kbd>[<off>] [ ,, | >> | << ]</kbd></nobr> +<br/> + +or +<br/> + +<nobr>Macro: <strong>SMARTQUOTES</strong> <kbd>DA | DE | ES | FR | IT | NL | NO | PT | SV</kbd></nobr> +</p> + +<p> +If you invoke <strong>SMARTQUOTES</strong> without an argument, +<strong>mom</strong> converts all instances of the inch-mark, +(<kbd>"</kbd> — also called a "doublequote"), into +the appropriate instances of true Anglo-American open-and +close-doublequotes. (See +<a href="#SQ_INTERNATIONAL">Internationalization</a> +for how to get SMARTQUOTES to behave correctly for non-English +quoting styles.) +</p> + +<p> +Typographically, there is a difference between the inch-mark and +doublequotes — a BIG difference. Sadly, typewriters and computer +keyboards supply only one: the inch-mark. While using inches for +doublequotes is, and always has been, acceptable in typewriter-style +copy, it has never been, and, God willing, never will be acceptable in +typeset copy. Failure to turn inches into quotes is the first thing +a professional typesetter notices in documents prepared by amateurs. +And you don't want to look like an amateur, do you? +</p> + +<a name="SQ_INTERNATIONAL"><h3><u>Internationalization</u></h3></a> + +<p> +If you invoke <strong>SMARTQUOTES</strong> with one of the +optional arguments (<kbd>,,</kbd> or <kbd>>></kbd> +or <kbd><<</kbd>) you can use <kbd>"</kbd> as +"cheap" open-and close-quotes when inputting text in a +language other than English, and have <strong>mom</strong> convert +them, on output, into the chosen open-and close-quote style. +</p> + +<p> +<kbd>,,</kbd> opens quotes with "lowered doublequotes" and +closes them with "raised doublequotes", as in this ascii +approximation: + +<pre> + ,,Hilfe !`` +</pre> + +<kbd>>></kbd> opens quotes with guillemets pointing to the +right, and closes them with guillemets pointing to the left, as in +this ascii approximation: + +<pre> + >>Zurück !<< +</pre> +</p> + +<p> +<kbd><<</kbd> opens quotes with guillemets pointing to the +left, and closes them with guillemets pointing to the right, as in +this ascii approximation: + +<pre> + <<Mais monsieur! Je ne suis pas ce genre de fille!>> +</pre> +</p> + +<p> +Please note: the above arguments to <strong>SMARTQUOTES</strong> +are literal ASCII characters. <kbd>,,</kbd> is two commas, +<kbd><<</kbd> is two less-than signs and <kbd>>></kbd> +is two greater-than signs. +</p> + +<p> +Alternatively, you can pass <strong>SMARTQUOTES</strong> the +two-letter, ISO 639 abbreviation for the language you're writing in, +and <strong>mom</strong> will output the correct quotes. + +<pre> + .SMARTQUOTES DA = Danish >>text<< + .SMARTQUOTES DE = German ,,text`` + .SMARTQUOTES ES = Spanish ``text´´ + .SMARTQUOTES FR = French << text >> + .SMARTQUOTES IT = Italian << text >> + .SMARTQUOTES NL = Dutch ´´text´´ + .SMARTQUOTES NO = Norwegian <<text>> + .SMARTQUOTES PT = Portuguese <<text>> + .SMARTQUOTES SV = Swedish >>text>> +</pre> +</p> + +<p> +Turn <strong>SMARTQUOTES</strong> off by passing it any argument +<em>not</em> in the argument list (e.g. <strong>OFF</strong>, +<strong>QUIT</strong>, <strong>X</strong>, etc.) +</p> + +<p> +If you're using the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a> +with +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPESET</a>, +<strong>SMARTQUOTES</strong> is on by default (in the Anglo-American +style); with +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +it's off by default (and should probably stay that way). +</p> + +<p> +Finally, if you're fussy about the kerning of quote marks in +relation to the text they surround, or have special quoting needs, +you have to enter quote marks by hand using groff's native +<a href="definitions.html#TERMS_INLINES">inline escapes</a> +for special characters (see <kbd>man groff_char</kbd> for a complete +list of special characters). Entering quote marks this way allows +you to use <strong>mom</strong>'s +<a href="inlines.html#INLINE_KERNING_MOM">inline kerning escapes</a> +to fine-tune the look of quotes. +</p> + +<p> +<strong>NOTE:</strong> <strong>SMARTQUOTES</strong> does not work on +single quotes, which most people input with the apostrophe (found +at the right-hand end of the "home row" on a QWERTY +keyboard). Groff will interpret all instances of the apostrophe as +an apostrophe, making the symbol useless as an open-single-quote. +For open single quotes, input the backtick character typically +found under the tilde on most keyboards. (Pour nous autres, +"backtick" veut dire l'accent grave.) Here's an example +of correct input copy with single quotes: + +<pre> + "But she said, `I don't want to!'" +</pre> +</p> + +<p> +<strong>ADDITIONAL NOTE:</strong> Whether or not you have +<strong>SMARTQUOTES</strong> turned on, get into the habit of +entering the foot-and inch-marks, when you need them, with the +<a href="definitions.html#TERMS_INLINES">inline escapes</a> +<kbd>\*[FOOT]</kbd> and <kbd>\*[INCH]</kbd>, instead of <kbd>'</kbd> +and <kbd>"</kbd>. +</p> + +<!-- -CAPS- --> + +<hr width="33%" align="left"/> + +<a name="CAPS"><h3><u>Convert to upper case</u></h3></a> + +<p> +<nobr>Macro: <strong>CAPS</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +<strong>CAPS</strong> converts all lower case letters to upper case. +Primarily, it's a support macro used by the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a>, +but you may find it helpful on occasion. <strong>CAPS</strong> is +a toggle, therefore no argument turns it on, any argument +(<strong>OFF, QUIT, X,</strong> etc.) turns it +off. + +<pre> + .CAPS + All work and no play makes Jack a dull boy. + .CAPS OFF +</pre> + +produces, on output + +<pre> + ALL WORK AND NO PLAY MAKES JACK A DULL BOY. +</pre> +</p> + +<p> +If you wish to capitalise a section of type inlines, use the +<a href="definitions.html#TERMS_INLINES">inline escapes</a>, +<a href="inlines.html#UC_LC"><kbd>\*[UC]...\*[LC]</kbd></a> +like this: + +<pre> + All work \*[UC]and\*[LC] no play makes Jack a dull boy. +</pre> + +The above produces, on output + +<pre> + All work AND no play makes Jack a dull boy. +</pre> +</p> + +<p> +The inline escapes are especially useful for capitalizing +<strong>mom</strong>'s +<a href="headfootpage.html#RESERVED_STRINGS">reserved strings</a> +(document title, author[s], etc) when designing your own +<a href="headfootpage.html#HEADFOOTPAGE_INTRO">HEADERS and FOOTERS</a> +when using the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a>. +</p> + +<!-- -STRING- --> + +<hr width="33%" align="left"/> + +<a name="STRING"><h3><u>User-defined strings</u></h3></a> + +<p> +<nobr>Macro: <strong>STRING</strong> <kbd><name> <what you want in the string></kbd></nobr> +</p> + +<p> +You may find sometimes that you have to type out portions of text +repeatedly. If you'd like not to wear out your fingers, you can +define a "string" that, whenever you call it by name, +outputs whatever you put into it. +</p> + +<p> +For example, say you're creating a document that repeatedly uses +the phrase "the Montreal/Windsor corridor". Instead of +typing all that out every time, you could define a string, like +this: + +<pre> + .STRING mw the Montreal/Windsor corridor +</pre> +</p> + +<p> +Once a string is defined, you can call it any time with the +<a href="definitions.html#INLINES">inline escape</a> +<kbd>\*[<stringname>]</kbd>. Using the example string above + +<pre> + The schedule for trains along \*[mw]: +</pre> + +produces, on output + +<pre> + The schedule for trains along the Montreal/Windsor corridor: +</pre> +</p> + +<p> +<strong>NOTE:</strong> Be very careful not to put any spaces at the +ends of strings you're defining, unless you want them. Everything +after the name argument you pass to <strong>STRING</strong> goes +into the string, including trailing spaces. +</p> + +<p> +<strong>Experts: STRING</strong> is an alias for <strong>ds</strong>. +You can use either, or mix 'n' match with impunity. +</p> + +<!-- -ESC_CHAR- --> + +<hr width="33%" align="left"/> + +<a name="ESC_CHAR"><h3><u>Change the escape character</u></h3></a> + +<p> +<nobr>Macro: <strong>ESC_CHAR</strong> <kbd><new character> | <anything></kbd></nobr> +</p> + +<p> +<strong>Groff</strong>'s and <strong>mom</strong>'s default escape +character is the backslash. Sometimes, you may want to include +a literal backslash in your document. There are two ways to +accomplish this. One is simply to double the backslash character +<nobr>(<kbd>\\</kbd>),</nobr> which is convenient if you don't have a +lot of backslashes to input. If you need to input a whole batch of +backslashes (say, when including code snippets in your document), +you can use <strong>ESC_CHAR</strong> to make the change permanent +(until you decide to restore the escape character to its default, +the backslash). +</p> + +<p> +<strong>ESC_CHAR</strong> with a single character argument +changes the escape character to whatever the argument is. +<strong>ESC_CHAR</strong> with no argument restores the escape +character to the backslash. +</p> + +<p> +<strong>Experts</strong>: <strong>ESC_CHAR</strong> is an alias of +<kbd>.ec</kbd>. Mix 'n' match the two with impunity. +</p> + +<!-- -UNDERSCORE- --> + +<hr width="33%" align="left"/> + +<a name="UNDERSCORE"><h3><u>Single underscore</u></h3></a> + +<p> +<nobr>Macro: <strong>UNDERSCORE</strong> <kbd>[ <distance below baseline> ] "<string>"</kbd></nobr> +<br/> + +<em>*Optional argument requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +By default, <strong>UNDERSCORE</strong> places an underscore 2 +points beneath the required +<a href="definitions.html#TERMS_STRINGARGUMENT">string argument</a>. +The string must be enclosed in double-quotes, like this: + +<pre> + .UNDERSCORE "Unmonitored monopolies breed high prices and poor products." +</pre> +</p> + +<p> +If you wish to change the distance of the rule from the +baseline, use the optional argument <kbd><distance below +baseline></kbd> (with a unit of measure). + +<pre> + .UNDERSCORE 3p "Unmonitored monopolies breed high prices and poor products." +</pre> +</p> + +<p> +The above places upper edge of the underscore 3 points below the +<a href="definitions.html#TERMS_BASELINE">baseline</a>. +</p> + +<a name="UNDERSCORE_WEIGHT"></a> + +<h4><u>Controlling the weight of underscores</u></h4> + +<p> +(Please note that <strong>UNDERSCORE_WEIGHT</strong> also sets the +weight of +<a href="#UNDERSCORE2">double underscores.</a>) +</p> + +<p> +The weight (thickness) of underscores may be controlled with the +macro, <strong>UNDERSCORE_WEIGHT</strong>. Thus, if you want +underscores with a weight of 1-1/2 points, you'd invoke: + +<pre> + .UNDERSCORE_WEIGHT 1.5 +</pre> + +prior to invoking <kbd>.UNDERSCORE</kbd>. Every subsequent +instance of <kbd>.UNDERSCORE</kbd> will use this weight. +</p> + +<p> +<strong>Mom</strong>'s default underscore weight is 1/2 point. +</p> + +<a name="NOTES_UNDERSCORE"></a> + +<h4><u>NOTES:</u></h4> + +<p> +<strong>UNDERSCORE</strong> does not work across line breaks in +output copy, which is to say that you can't underscore a multi-line +passage simply by putting the text of the whole thing in the string +you pass to <strong>UNDERSCORE</strong>. Each +<a href="definitions.html#TERMS_OUTPUTLINE">output line</a> +or portion of an output line you want underscored must be plugged +separately into <strong>UNDERSCORE</strong>. Bear in mind, though, +that underscoring should at best be an occasional effect in typeset +copy. If you want to emphasize an entire passage, it's much, much +better to change fonts (e.g. to italic or bold). +</p> + +<p> +You can easily and successfully underline entire passages in +simulated typewriter-style copy (i.e. if your font is a monospaced +one, like Courier, or you're using the document processing macro +<a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>), +with the +<a href="#UNDERLINE">UNDERLINE</a> +macro. <strong>UNDERLINE</strong> is designed specifically for this +purpose, but works only with the monspaced fonts. +</p> + +<p> +<strong>Mom</strong> doesn't always get the position and length +of the underscore precisely right in +<a href="definitions.html#TERMS_JUST">justified</a> +copy, although she's fine with all the other +<a href="definitions.html#TERMS_FILLED">fill modes</a>, +as well as with the no-fill modes. The reason is that when text is +justified, the word spacing may expand to fill the line, but that +doesn't happen until <em>after</em> the line has been processed +in all other respects — including establishing how long to +make an underscore. A workaround is to prepend the backslash +character <nobr>(<kbd>\</kbd>)</nobr> to each word space in the +string passed to <strong>UNDERSCORE</strong>. The word spacing of +the underscored string <em>may</em> be slightly smaller than the +word space of the remainder of the line, but in many cases, the +difference isn't visually noticeable. +</p> + +<p> +<strong>UNDERSCORE</strong> tends to confuse +<strong>gxditview</strong>, even though the output, when +printed, looks fine. Generally, I recommend using <strong>gv</strong> +to preview files anyway. See the section on +<a href="using.html#USING_PREVIEWING">previewing</a>. +</p> + +<p> +<a name="UNDERSCORE_COLOR"><strong>Colorizing underscored text:</strong></a> +If you want underscored text to be in a different colour from the +text around it, use the +<a href="color.html#COLOR">COLOR</a> +macro, rather than the +<a href="color.html#COLOR_INLINE">inline escape for changing color</a>. +In other words, assuming your prevailing text color is black and +you want underscored text in red + +<pre> + .COLOR red + .UNDERSCORE "text to underscore" + .COLOR black +</pre> + +rather than + +<pre> + .UNDERSCORE "\*[red]text to underscore\*[black]" +</pre> + +The latter will render the text in red, and the underscore in black. +You can use this to create truly rainbow effects if you want, e.g. +text in red, underscore in blue, and prevailing type in black: + +<pre> + .UNDERSCORE "\*[red]text to underscore\*[blue]" + .COLOR black +</pre> +</p> + +<!-- -UNDERSCORE2- --> + +<hr width="33%" align="left"/> + +<a name="UNDERSCORE2"><h3><u>Double underscore</u></h3></a> + +<p> +<nobr>Macro: <strong>UNDERSCORE2</strong> [ <distance below baseline> [ <distance between rules> ] ] "<string>"</nobr> +<br/> + +<em>*Optional arguments require a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +By default, <strong>UNDERSCORE2</strong> places a double underscore +2 points beneath the required +<a href="definitions.html#TERMS_STRINGARGUMENT">string argument</a>. +The string must be enclosed in double-quotes, like this: + +<pre> + .UNDERSCORE2 "Unmonitored monopolies breed high prices and poor products." +</pre> +</p> + +<p> +The default distance between the two rules is 2 points, measured +from the bottom edge of the upper rule to the top edge of the lower +one. +</p> + +<p> +If you wish to change the distance of the double underscore from +the baseline, use the optional argument <kbd><distance below +baseline></kbd> (with a unit of measure), e.g., + +<pre> + .UNDERSCORE2 3p "Unmonitored monopolies breed high prices and poor products." +</pre> + +which places the upper edge of the first rule of the double +underscore 3 points below the +<a href="definitions.html#TERMS_BASELINE">baseline</a>. +</p> + +<p> +If you wish to change the distance between the two rules as +well, use the second optional argument <kbd><distance between +rules></kbd> (with a unit of measure). Be aware that you must +give a value for the first optional argument if you want to use the +second. The distance between the two rules is measured from the +bottom edge of the upper rule to the top edge of the lower one. +</p> + +<p> +The weight (thickness) of double underscores may be controlled with +the macro +<a href="#UNDERSCORE_WEIGHT">UNDERSCORE_WEIGHT</a> +(q.v). +</p> + +<p> +<strong>NOTE:</strong> the same restrictions and caveats apply +to <strong>UNDERSCORE2</strong> as to +<strong>UNDERSCORE</strong>. See the +<a href="#NOTES_UNDERSCORE">NOTES</a> +for <strong>UNDERSCORE</strong>. +</p> + +<!-- -UNDERLINE- --> + +<hr width="33%" align="left"/> + +<a name="UNDERLINE"><h3><u>Underline text — monospaced fonts only</u></h3></a> + +<p> +<nobr>Macro: <strong>UNDERLINE</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +If your font is monospaced one, like Courier, or you're using the +document processing macro +<a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +<strong>UNDERLINE</strong> allows you to underline words and +passages that, in typeset copy, would be italicized. You invoke +<kbd>.UNDERLINE</kbd> as you do with all toggle macros — by +itself (i.e. with no argument) to initiate underlining, and with any +argument (<strong>OFF, QUIT, X,</strong> etc) to turn underlining +off. +</p> + +<p> +When on, <strong>UNDERLINE</strong> underlines letters, words +and numbers, but not punctuation or spaces. This makes for more +readable copy than a solid underline. +</p> + +<p> +<strong>NOTE:</strong> Underlining may also be turned on and off +<a href="definitions.html#TERMS_INLINES">inline</a> +with the escapes +<a href="#UL"><kbd>\*[UL]...\*[ULX]</kbd></a>. +</p> + +<!-- -UL- --> + +<hr width="33%" align="left"/> + +<a name="UL"><h3><u>Inline escape for underlining — monospaced fonts only</u></h3></a> + +<p> +Inline: <kbd>\*[UL]...\*[ULX]</kbd> +</p> + +<p> +If your font is a monospaced one, like Courier, or you're using the +document processing macro +<a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +<kbd>\*[UL]...\*[ULX]</kbd> underlines words and +passages that, in typeset copy, would be italicized. +</p> + +<p> +<kbd>\*[UL]</kbd> underlines all letters, words and numbers +following it, but not punctuation or spaces. This makes for more +readable copy than a solid underline. When you no longer want +underlining, <kbd>\*[ULX]</kbd> turns underlining off. +</p> + +<p> +The macro +<a href="#UNDERLINE">UNDERLINE</a> +and the inline escape <kbd>\*[UL]</kbd> are functionally +identical, hence + +<pre> + .FAM C + .FT R + .PT_SIZE 12 + .LS 24 + .SS 0 + .QUAD LEFT + Which should I heed? + .UNDERLINE + Just do it + .UNDERLINE OFF + or + .UNDERLINE + just say no? + .UNDERLINE OFF +</pre> + +produces the same result as + +<pre> + .FAM C + .FT R + .PT_SIZE 12 + .LS 24 + .SS 0 + .QUAD LEFT + Which should I heed? \*[UL]Just do it\*[ULX] or \*[UL]just say no?\*[ULX] +</pre> +</p> + +<!-- -PAD- --> + +<hr width="33%" align="left"/> + +<a name="PAD"><h3><u>Insert space into lines</u></h3></a> + +<p> +<nobr>Macro: <strong>PAD</strong> <kbd>"<string with pad markers inserted>" [ NOBREAK ]</kbd></nobr> +</p> + +<p> +With <strong>PAD</strong>, you can insert unspecified amounts of +whitespace into a line. + +<a name="NOBREAK"></a> + +The optional <kbd>NOBREAK</kbd> argument tells <strong>mom</strong> +not to advance on the page after the <strong>PAD</strong> macro has +been invoked. +</p> + +<p> +<strong>PAD</strong> calculates the difference between the length of +text on the line and the distance remaining to its end, then inserts +the difference (as whitespace) at the place(s) you specify. +</p> + +<p> +Take, for example, the following relatively common typesetting +situation, found at the bottom of legal agreements: + +<pre> + Date Signature | +</pre> +</p> + +<p> +The person signing the agreement is supposed to fill in the date +as well as a signature. Space needs to be left for both, but +the exact amount is neither known, nor important. All that +matters is that there be a little space after Date, and rather +more space after Signature. (In the above, | represents +the end of the line at the prevailing line length.) +</p> + +<p> +The +<a href="goodies.html#PAD_MARKER">pad marker</a> +(see below) is # (the pound or number sign on your keyboard) and can +be used multiple times in a line. With that in mind, here's how +you'd input the Date/Signature line (assuming a length of 30 picas): + +<pre> + .LL 30P + .PAD "Date#Signature###" +</pre> +</p> + +<p> +When the line is output, the space remaining on the line, after +"Date" and "Signature" have been taken into +account, is split into four (because there are four # signs). One +quarter of the space is inserted between Date and Signature, the +remainder is inserted after Signature. +</p> + +<a name="PAD_EXAMPLE"></a> + +<p> +One rarely wants merely to insert space in a line; one usually +wants to fill it with something, hence <strong>PAD</strong> is +particularly useful in conjunction with +<a href="typesetting.html#STRING_TABS">string tabs</a>. +The following uses the Date/Signature example above, but adds +rules into the whitespace through the use of string tabs and +<strong>mom</strong>'s +<a href="definitions.html#TERMS_INLINES">inline escape</a> +<a href="inlines.html#INLINE_RULE_MOM"><kbd>\*[RULE]</kbd></a>. +(Instead of <kbd>\*[RULE]</kbd>, +groff's line drawing function, +<a href="inlines.html#INLINE_LINEDRAWING_GROFF"><kbd>\l</kbd></a> +could be used.) + +<pre> + .LL 30P + .PAD "Date \*[ST1]#\*[ST1X] Signature \*[ST2]###\*[ST2X]" NOBREAK + .ST 1 J + .ST 2 J + .TAB 1 + \*[RULE] + .TN + \*[RULE] + .TQ +</pre> +</p> + +<p> +If you're not a typesetter, and if you're new to groff, the +example probably looks like gibberish. My apologies. However, +remember that typesetting is a craft, and without having studied +the craft, it takes a while to grasp its concepts. +</p> + +<p> +Basically, what the example does is: + +<ol> + <li>Pads the Date/Signature line (using the pad marker + <kbd>#</kbd>), encloses the padded space with two string + tabs markers, and outputs the line without advancing on the + page. + </li> + <li>Sets the two string tabs. + </li> + <li>Calls the first string tab and draws a rule to its full + length. + </li> + <li>Calls the second tab with + <a href="typesetting.html#TN">TN</a> + (which moves to tab 2 and stays on the same baseline) + then draws a rule to the full length of string tab 2. + </li> +</ol> +</p> + +<p> +Often, when setting up string tabs this way, you don't want the +padded line to print immediately. To accomplish this, use +<a href="#SILENT">SILENT</a>. +See the +<a href="typesetting.html#STRING_TABS_TUT">quickie tutorial on string tabs</a> +for an example. +</p> + +<p> +<strong>NOTE:</strong> Because the pound sign +<nobr>(<kbd>#</kbd>)</nobr> is used as the pad marker, you can't use +it as a literal part of the pad string. If you need the sign to +appear in the text of a padded line, change the pad marker with +<a href="#PAD_MARKER">PAD_MARKER</a>. +Also, be aware that <kbd>#</kbd> as a pad marker only applies +within the <strong>PAD</strong> macro; at all other times it prints +literally, just as you'd expect. +</p> + +<p> +Another important consideration when using <strong>PAD</strong> is that +because the string must be enclosed in double-quotes, you can't use the +double-quote <nobr>(<kbd>"</kbd>)</nobr> as part of the string. The +way to circumvent this is to use the groff +<a href="definitions.html#TERMS_INLINES">inline escapes</a> +<kbd>\(lq</kbd> and <kbd>\(rq</kbd> (leftquote and rightquote +respectively) whenever double-quotes are required in the string +passed to <strong>PAD</strong>. +</p> + +<!-- -PAD_MARKER- --> + +<hr width="33%" align="left"/> + +<a name="PAD_MARKER"><h3><u>Change/set the marker used with PAD</u></h3></a> + +<p> +<nobr>Macro: <strong>PAD_MARKER</strong> <character to use as the pad marker></nobr> +</p> + +<p> +If you need to change <strong>mom</strong>'s default pad marker +<nobr>(<kbd>#</kbd>),</nobr> either because you want a literal # in +the padded line, or simply because you want to use another character +instead, use <strong>PAD_MARKER</strong>, whose argument is the new +pad marker character you want. + +<pre> + .PAD_MARKER @ +</pre> + +changes the pad marker to @. +</p> + +<p> +Once you've changed the pad marker, the new marker remains in +effect for every instance of +<a href="#PAD">PAD</a> +until you change it again (say, back to the pound sign). +</p> + +<!-- -\*[LEADER]- --> + +<hr width="33%" align="left"/> + +<a name="LEADER"><h3><u>Inline escape to add leaders to a line</u></h3></a> + +<p> +Inline: <kbd>\*[LEADER]</kbd> +</p> + +<p> +Whenever you want to fill a line or tab with +<a href="definitions.html#TERMS_LEADER">leaders</a>, +use the +<a href="definitions.html#TERMS_INLINES">inline escape</a> +<kbd>\*[LEADER]</kbd>. The remainder of the line or tab will be +filled with the leader character. <strong>Mom</strong>'s default +leader character is a period (dot), but you can change it to any +character you like with +<a href="#LEADER_CHARACTER">LEADER_CHARACTER</a>. +</p> + +<p> +<strong>NOTE:</strong> <kbd>\*[LEADER]</kbd> fills lines or tabs +right to their end. You cannot insert leaders into a line or tab +and have text following the leader on the same line or in the same +tab. Should you wish to achieve such an effect typographically, +create tabs for each element of the line and fill them appropriately +with the text and leaders you need. +<a href="typesetting.html#STRING_TABS">String tabs</a> +are perfect for this. An example follows. + +<pre> + .LL 30P + .PAD "Date\*[ST1]#\*[ST1X]Signature\*[ST2]###\*[ST2X]" + .EL + .ST 1 J + .ST 2 J + .TAB 1 + \*[LEADER] + .TN + \*[LEADER] + .TQ +</pre> +</p> + +<p> +The <strong>PAD</strong> line sets the words Date and Signature, +and marks string tabs around the pad space inserted in the line. +The string tabs are then "set", called, and filled +with leaders. The result looks like this: + +<pre> + Date.............Signature..................................... +</pre> +</p> + +<!-- -LEADER_CHARACTER- --> + +<hr width="33%" align="left"/> + +<a name="LEADER_CHARACTER"><h3><u>Change/set the leader character</u></h3></a> + +<p> +<nobr>Macro: <strong>LEADER_CHARACTER</strong> <kbd><character></kbd></nobr> +</p> + +<p> +<strong>LEADER_CHARACTER</strong> takes one argument: a single +character you would like to be used for +<a href="definitions.html#TERMS_LEADER">leaders</a>. +(See +<a href="#LEADER"><kbd>\*[LEADER]</kbd></a> +for an explanation of how to fill lines with leaders.) +</p> + +<p> +For example, to change the leader character from <strong>mom</strong>'s +default (a period) to the underscore character, enter + +<pre> + .LEADER_CHARACTER _ +</pre> +</p> + +<!-- -DROPCAP- --> + +<hr width="33%" align="left"/> +<a name="DROPCAP"><h3><u>Drop caps</u></h3></a> + +<p> +<nobr>Macro: <strong>DROPCAP</strong> <kbd><dropcap letter> <number of lines to drop> [ COND <percentage> | EXT <percentage> ]</kbd></nobr> +</p> + +<p> +The first two arguments to <strong>DROPCAP</strong> are the letter you +want to be the +<a href="definitions.html#TERMS_DROPCAP">drop cap</a> +and the number of lines you want it to drop. By default, +<strong>mom</strong> uses the current family and font for the drop +cap. +</p> + +<p> +The optional argument <nobr>(<kbd>COND</kbd> or +<kbd>EXT</kbd>)</nobr> indicates that you want the drop +cap condensed (narrower) or extended (wider). If you use +<kbd>COND</kbd> or <kbd>EXT</kbd>, you must follow the argument with +the percentage of the letter's normal width you want it condensed or +extended. No percent sign (%) is required. +</p> + +<p> +<strong>Mom</strong> will do her very best to get the drop cap to +line up with the first line of text indented beside it, then set the +correct number of indented lines, and restore your left margin when +the number of drop cap lines has been reached. +</p> + +<p> +Beginning a paragraph with a drop cap "T" looks +like this: + +<pre> + .DROPCAP T 3 COND 90 + he thousand injuries of Fortunato I had borne as best I + could, but when he ventured upon insult, I vowed revenge. + You who so well know the nature of my soul will not suppose, + however, that I gave utterance to a threat... +</pre> +</p> + +<p> +The drop cap, slightly condensed but in the current family and font, +will be three lines tall, with whatever text fills those three +lines indented to the right of the letter. The remainder of the +paragraph's text will revert to the left margin. +</p> + +<p> +<strong>NOTE:</strong> When using the +<a href="docprocessing.html#DOCPROCESSING">document processing macro</a> +<a href="docelement.html#PP">PP</a>, +<strong>DROPCAP</strong> only works + +<ul> + <li>with initial paragraphs (i.e. at the start of the document, + or after + <a href="docelement.html#HEAD">HEAD</a>),</li> + <li>when <kbd>.DROPCAP</kbd> comes immediately after <kbd>.PP</kbd>,</li> + <li>and when the + <a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE</a> + is TYPESET.</li> +</ul> + +If these conditions aren't met, <strong>DROPCAP</strong> is silently ignored. +</p> + +<p> +<strong>WARNING:</strong> <strong>DROPCAP</strong> puts a bit of +a strain on resource-challenged systems. If you have such a +system and use drop caps extensively in a document, be prepared +for a wait while <strong>mom</strong> does her thing. +</p> + +<h4><a name="DROPCAP_SUPPORT"><u>Support macros for DROPCAP</u></a></h4> + +<p> +Drop caps are the bane of most typesetters' existence. It's +very difficult to get the size of the drop cap right for the +number of drop lines, especially if the drop cap is in a +different family from the prevailing family of running text. +Not only that, but there's the gutter around the drop cap to +take into account, plus the fact that the letter may be too wide +or too narrow to look anything but odd or misplaced. +</p> + +<p> +<strong>Mom</strong> solves the last of these problems with the +<kbd>COND</kbd> and <kbd>EXT</kbd> arguments. The rest she +solves with macros that change the default behaviour of +<strong>DROPCAP</strong>, namely +</p> + +<p> +<a href="#DROPCAP_FAMILY">DROPCAP_FAMILY</a> +<br/> + +<a href="#DROPCAP_FONT">DROPCAP_FONT</a> +<br/> + +<a href="#DROPCAP_COLOR">DROPCAP_COLOR</a> +<br/> + +<a href="#DROPCAP_ADJUST">DROPCAP_ADJUST</a> +<br/> + +and +<br/> + +<a href="#DROPCAP_GUTTER">DROPCAP_GUTTER</a>. +</p> + +<p> +These macros must, of course, come before you invoke +<strong>DROPCAP</strong>. +</p> + +<h4><a name="DROPCAP_FAMILY"><u>DROPCAP_FAMILY</u></a></h4> + +<p> +Set the drop cap family by giving +<strong>DROPCAP_FAMILY</strong> the name of the family you want, +e.g. + +<pre> + .DROPCAP_FAMILY H +</pre> + +which will set the family to Helvetica for the drop cap only. +</p> + +<h4><a name="DROPCAP_FONT"><u>DROPCAP_FONT</u></a></h4> + +<p> +Set the drop cap font by giving +<strong>DROPCAP_FONT</strong> the name of the font you want, +e.g. + +<pre> + .DROPCAP_FONT I +</pre> + +which will set the font to italic for the drop cap only. +</p> + +<h4><a name="DROPCAP_ADJUST"><u>DROPCAP_ADJUST</u></a></h4> + +<p> +If the size <strong>mom</strong> calculates for the drop cap +isn't precisely what you want, you can increase or decrease it +with <strong>DROPCAP_ADJUST</strong>, like this: +e.g. + +<pre> + .DROPCAP_ADJUST +1 + or + .DROPCAP_ADJUST -.75 +</pre> +</p> + +<p> +<strong>DROPCAP_ADJUST</strong> only understands +<a href="definitions.html#TERMS_PICASPOINTS">points</a>, +therefore do not append any +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a> +to the argument. And always be sure to prepend the plus or +minus sign, depending on whether you want the drop cap larger or +smaller. +</p> + +<h4><a name="DROPCAP_COLOR"><u>DROPCAP_COLOR</u></a></h4> + +<p> +If you'd like your drop cap colourized, simply invoke +<strong>DROPCAP_COLOR</strong> with the name of a colour you've already +created ("initialized") with +<a href="color.html#NEWCOLOR">NEWCOLOR</a> +or +<a href="color.html#XCOLOR">XCOLOR</a>. Only the drop cap will be +colourized; all other text will remain at the current colour +default (usually black). +</p> + +<h4><a name="DROPCAP_GUTTER"><u>DROPCAP_GUTTER</u></a></h4> + +<p> +By default, <strong>mom</strong> puts three points of space +between the drop cap and the text indented beside it. If you +want another value, use <strong>DROPCAP_GUTTER</strong> (with a +unit of measure), like this: + +<pre> + .DROPCAP_GUTTER 6p +</pre> +</p> + +<!-- -\*[SUP]- --> + +<hr width="33%" align="left"/> + +<a name="SUP"><h3><u>Superscript</u></h3></a> + +<p> +Inlines: <kbd>\*[SUP]...\*[SUPX]</kbd> +</p> + +<p> +Superscripts are accomplished +<a href="definitions.html#TERMS_INLINES">inline</a>. +Whenever you need one, typically for numerals, all you need to do is +surround the superscript with the inlines above. <kbd>\*[SUP]</kbd> +begins superscripting; <kbd>\*[SUPX]</kbd> turns it off. +</p> + +<a name="CONDSUP"></a> +<a name="EXTSUP"></a> + +<p> +If your running type is +<a href="typesetting.html#COND_INLINE">pseudo-condensed</a> +or +<a href="typesetting.html#EXT_INLINE">pseudo-extended</a> +and you want your superscripts to be equivalently pseudo-condensed +or -extended, use <kbd>\*[CONDSUP]...\*[CONDSUPX]</kbd> or +<kbd>\*[EXTSUP]...\*[EXTSUPX]</kbd>. +</p> + +<p> +The superscript inlines are primarily used by the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a> +for automatic generation of numbered footnotes. However, you may +find them useful for other purposes. +</p> + +<p> +<strong>NOTE:</strong> <strong>Mom</strong> does a pretty fine job of +making superscripts look good in any font and at any size. If you're +fussy, though (and I am), about precise vertical placement, kerning, +weight, size, and so on, you may want to roll your own solution. +And sorry, there's no <strong>mom</strong> equivalent for subscripts. +I'm neither a mathematician nor a chemist, so I don't need them. +Of course, anyone who wishes to contribute a subscript routine to +<strong>mom</strong> will receive eternal blessings not only in this +lifetime, but in all lifetimes to come. +</p> + +<hr/> + +<a href="inlines.html#TOP">Next</a> +<a href="typesetting.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> + +</body> +</html> + +<!-- vim: fileencoding=latin1: nomodified: +--> |