1 <?xml version="1.0" encoding="utf-8"?>
3 This file is part of groff, the GNU roff type-setting system.
5 Copyright (C) 2004-2014 Free Software Foundation, Inc.
6 Written by Peter Schaffter (peter@schaffter.ca).
8 Permission is granted to copy, distribute and/or modify this document
9 under the terms of the GNU Free Documentation License, Version 1.3 or
10 any later version published by the Free Software Foundation; with the
11 Invariant Sections being this comment section, with no Front-Cover
12 Texts, and with no Back-Cover Texts.
14 A copy of the Free Documentation License is included as a file called
15 FDL in the main directory of the groff source package.
18 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
19 <html xmlns="http://www.w3.org/1999/xhtml">
22 <meta http-equiv="content-type" content="text/html;charset=utf-8"/>
23 <title>Mom -- Goodies</title>
24 <link rel="stylesheet" type="text/css" href="stylesheet.css" />
27 <body style="background-color: #f5faff;">
29 <!-- ==================================================================== -->
31 <div id="top" class="page">
33 <!-- Navigation links -->
34 <table style="width: 100%;">
36 <td><a href="toc.html">Back to Table of Contents</a></td>
37 <td style="text-align: right;"><a href="inlines.html#top">Next: Inline escapes</a></td>
41 <h1 id="goodies" class="docs">Goodies</h1>
44 The macros in this section are a collection of useful (and sometimes
45 nearly indispensable) routines to simplify typesetting.
48 <div id="goodies-macros-mini-toc" style="margin-top: -1em; font-size: 95%;">
49 <div class="mini-toc-col-1">
50 <ul class="no-enumerator">
51 <li class="list-head-goodies"><a href="#alias">ALIAS</a> <span class="normal-smaller">– rename macros</span></li>
52 <li class="list-head-goodies"><a href="#caps">CAPS</a> <span class="normal-smaller">– convert to upper case</span></li>
53 <li class="list-head-goodies"><a href="#esc-char">ESC_CHAR</a> <span class="normal-smaller">– change the escape character to something other than a backslash</span></li>
54 <li class="list-head-goodies"><a href="#silent">SILENT</a> <span class="normal-smaller">– hide input lines from output</span></li>
55 <li class="list-head-goodies"><a href="#sizespecs">SIZESPECS</a> <span class="normal-smaller">– get cap-height, x-height and descender depth of a font</span></li>
56 <li class="list-head-goodies"><a href="#smartquotes">SMARTQUOTES</a> <span class="normal-smaller">– convert typewriter doublequotes to proper doublequotes</span></li>
57 <li class="list-head-goodies"><a href="#string">STRING</a> <span class="normal-smaller">– user-definable strings</span></li>
58 <li class="list-head-goodies"><a href="#trap">TRAP</a> <span class="normal-smaller">– suspend/re-invoke traps</span></li>
59 <li class="list-head-goodies no-anchor"><span style="font-size: 90%;">Underscoring/underlining</span>
61 <li class="list-head-goodies text-color"><a href="#underscore">UNDERSCORE</a> <span class="normal-smaller">– single underscore</span>
62 <ul class="sublist sub">
63 <li class="list-head-goodies text-color"><a href="#underscore-weight">Controlling the weight of underscores</a></li>
64 <li class="list-head-goodies text-color"><a href="#underscore-color">Colorizing underscores</a></li>
66 <li class="list-head-goodies text-color"><a href="#underscore2">UNDERSCORE2</a> <span class="normal-smaller">– double underscore</span></li>
67 <li class="list-head-goodies text-color"><a href="#underline">UNDERLINE</a>
68 <ul class="sublist sub">
69 <li class="list-head-goodies text-color"><a href="#ul">\*[UL]</a> <span class="normal-sub-sub">– inline escape to underline</span></li>
72 <li class="list-head-goodies no-anchor"><span style="font-size: 90%;">Padding</span>
74 <li class="list-head-goodies text-color"><a href="#pad">PAD</a> <span class="normal-smaller">– insert equalized whitespace into lines</span>
75 <ul class="sublist sub">
76 <li class="list-head-goodies text-color"><a href="#pad-marker">PAD_MARKER</a> <span class="normal-sub-sub">– change/set the marker used with PAD</span></li>
81 <div class="mini-toc-col-2">
82 <ul class="no-enumerator">
83 <li class="list-head-goodies no-anchor"><span style="font-size: 90%;">Leaders</span>
85 <li class="list-head-goodies text-color"><a href="#leader">\*[LEADER]</a> <span class="normal-smaller">– inline escape to add leaders to a line</span></li>
86 <li class="list-head-goodies text-color"><a href="#leader-character">LEADER_CHARACTER</a> <span class="normal-smaller">– change/set the leader character</span></li>
88 <li class="list-head-goodies no-anchor"><span style="font-size: 90%;">Drop caps</span>
90 <li class="list-head-goodies text-color"><a href="#dropcap">DROPCAP</a> <span class="normal-smaller">– set a drop cap</span></li>
91 <li class="list-head-goodies text-color" style="list-style-type: none;"><a href="#dropcap-support"><span class="normal-smaller" style="font-weight: bold;">Support macros for DROPCAP</span></a>
92 <ul class="sublist sub">
93 <li class="list-head-goodies text-color"><a href="#dropcap-family">DROPCAP_FAMILY</a> <span class="normal-sub-sub">– change drop cap family</span></li>
94 <li class="list-head-goodies text-color"><a href="#dropcap-font">DROPCAP_FONT</a> <span class="normal-sub-sub">– change drop cap font</span></li>
95 <li class="list-head-goodies text-color"><a href="#dropcap-adjust">DROPCAP_ADJUST</a> <span class="normal-sub-sub">– alter size of drop cap</span></li>
96 <li class="list-head-goodies text-color"><a href="#dropcap-color">DROPCAP_COLOR</a> <span class="normal-sub-sub">– change colour of drop cap</span></li>
97 <li class="list-head-goodies text-color"><a href="#dropcap-gutter">DROPCAP_GUTTER</a> <span class="normal-sub-sub">– change space between drop cap and running text</span></li>
100 <li class="list-head-goodies text-color no-anchor"><span style="font-size: 90%;">Superscripts</span>
102 <li class="list-head-goodies text-color"><a href="#sup">\*[SUP]</a> <span class="normal-smaller">– inline escape to set superscripts</span>
103 <ul class="sublist sub">
104 <li class="list-head-goodies text-color"><a href="#sup-raise">SUPERSCRIPT_RAISE_AMOUNT</a> <span class="normal-sub-sub">(control superscript raise amount</span></li>
105 <li class="list-head-goodies text-color"><a href="#cond-or-ext-sup">\*[CONDSUP]</a> <span class="normal-sub-sub">– condensed superscripts</span></li>
106 <li class="list-head-goodies text-color"><a href="#cond-or-ext-sup">\*[EXTSUP]</a> <span class="normal-sub-sub">– extended superscripts</span></li>
113 <div class="rule-medium" style="padding-bottom: 1em;"><hr/></div>
117 <div class="macro-id-overline">
118 <h3 id="alias" class="macro-id">Rename macros</h3>
121 <div class="box-macro-args">
122 Macro: <b>ALIAS</b> <kbd class="macro-args"><new name> <old name></kbd>
126 The ALIAS macro may well be your best friend. With it, you can
127 change the name of a macro to anything you like (provided the new
128 name is not already being used by mom; see the
129 <a href="reserved.html#reserved">list of reserved words</a>).
133 Groff has always been a bit intimidating for new users because
134 its standard macro packages use very terse macro names. Mom
135 doesn’t like people to feel intimidated; she wants them
136 to feel welcome. Consequently, she tries for easy-to-grasp,
137 self-explanatory macro names. However, mom knows that people have
138 their own ways of thinking, their own preferences, their own habits.
139 Some of her macro names may not suit you; they might be too long,
140 or aren’t what you automatically think of when you want to
141 do a particular thing, or might conflict with habits you’ve
142 developed over the years.
146 If you don’t like one of mom’s macro names, say,
147 PAGEWIDTH, change it, like this:
149 <span class="pre-in-pp">
155 The first argument to ALIAS is the new name you want for a macro.
156 The second is the “official” name by which the macro is
157 normally invoked. After ALIAS, either can be used.
161 Note that in ALIAS, you do NOT include the period (dot) that
162 precedes the macro when it’s a
163 <a href="definitions.html#controllines">control line</a>.
166 <div class="box-tip">
168 <span class="tip">Tip:</span>
169 A particularly good candidate for ALIAS is the macro,
170 <a href="typesetting.html#ps">PT_SIZE</a>.
171 A more natural name for it would simply be PS, but PS conflicts
172 with the <b>eqn</b> equation preprocessor and thus mom uses the
173 longer form. However, if you’re not using <b>eqn</b>, you can
174 happily rename PT_SIZE to
177 <span class="pre-in-pp">
183 <div class="box-tip">
185 <span class="note">Note:</span>
186 If you use ALIAS a lot, and always for the same things, consider
187 creating an aliases file of the form
189 <span class="pre-in-pp">
190 .ALIAS <new name> <old name>
191 .ALIAS <new name> <old name>
192 .ALIAS <new name> <old name>
195 Put the file someplace convenient and source it (include it) at the
196 beginning of your documents with the
197 <a href="docprocessing.html#include">INCLUDE</a>
198 macro. Assuming that you’ve created an aliases file called
199 <b>mom-aliases</b> in your home directory under a directory called
200 <b>Mom</b>, you’d source it by placing
202 <span class="pre-in-pp">
203 .INCLUDE /home/<username>/Mom/mom-aliases
205 at the top of your documents.
208 <p class="tip-bottom">
209 If you share documents that make use of an alias file, remember that
210 other people don’t have the file. Paste the whole thing at
211 the top of your documents, please.
215 <div class="box-tip">
217 <span class="experts">Experts:</span>
218 ALIAS is an alias of <kbd>.als</kbd>. You can use either, or mix
219 'n' match with impunity.
224 <div class="macro-id-overline">
225 <h3 id="silent" class="macro-id">Hide input lines from output</h3>
228 <div class="box-macro-args">
229 Macro: <b>SILENT</b> <kbd class="macro-args">toggle</kbd>
232 <p class="alias" style="margin-bottom: 0;">
233 <i>Alias:</i> <b>COMMENT</b>
237 Sometimes, you want to “hide”
238 <a href="definitions.html#inputline">input lines</a>
239 from final output. This is most likely to be the case when setting
240 up string tabs (see the
241 <a href="typesetting.html#string-tabs-tut">quickie tutorial on string tabs</a>
242 for an example), but there are other places where you might want
243 input lines to be invisible as well. Any place you don’t want
244 input lines to appear in the output, use the SILENT macro.
248 SILENT is a toggle. Invoking it without an argument turns it on;
249 any argument turns it off. E.g.,
251 <span class="pre-in-pp">
256 The line “A line of text” will not appear in the
261 SILENT is aliased as COMMENT. If you want to insert non-printing
262 comments into your documents, you may prefer this.
265 <div class="box-tip">
267 <span class="tip">Tip:</span>
268 SILENT does not automatically break an
269 <a href="definitions.html#inputline">input line</a>
271 <a href="typesetting.html#br">BR</a>)
272 when you’re in one of the
273 <a href="definitions.html#filled">fill modes</a>
274 (<a href="typesetting.html#justify">JUSTIFY</a>
276 <a href="typesetting.html#quad">QUAD L | R | C | J</a>).
277 The same applies to tabs
278 (<a href="typesetting.html#tab-set">typesetting</a>
280 <a href="typesetting.html#st">string</a>)
281 to which you’ve passed the J or QUAD argument. You must
282 insert <kbd>.BR</kbd> yourself, or risk a portion of your text
283 disappearing into a black hole.
289 <div class="macro-id-overline">
290 <h3 id="trap" class="macro-id">Suspend/re-invoke traps</h3>
293 <div class="box-macro-args">
294 Macro: <b>TRAP</b> <kbd class="macro-args">toggle</kbd>
298 Traps are vertical positions on the output page at which
299 you or mom have instructed groff to start doing something
300 automatically. Commonly, this is near the bottom of the page, where
301 behind-the-scenes processing is needed in order for one page to
302 finish and another to start.
306 Sometimes, traps get sprung when you don’t want them. If this
307 happens, surround just the offending macros and input lines with
309 <span class="pre-in-pp">
314 TRAP is a toggle, therefore any argument turns it off (ie suspends
315 the trap), and no argument turns it (back) on.
318 <!-- -SMARTQUOTES- -->
320 <div class="macro-id-overline">
321 <h3 id="smartquotes" class="macro-id">Convert typewriter doublequotes to proper doublequotes</h3>
324 <div class="box-macro-args">
325 Macro: <b>SMARTQUOTES</b> <kbd class="macro-args">[<off>] [ ,, | >> | << ]</kbd>
328 <span style="margin-left: .5em">or</span>
330 <div class="box-macro-args">
331 Macro: <b>SMARTQUOTES</b> <kbd class="macro-args">DA | DE | ES | FR | IT | NL | NO | PT | SV</kbd>
335 If you invoke SMARTQUOTES without an argument, mom converts all
336 instances of the inch-mark, (<kbd>"</kbd>), also called
337 a doublequote, into the appropriate instances of true Anglo-American
338 open-and close-doublequotes. (See
339 <a href="#sq-international">Internationalization</a>
340 for how to get SMARTQUOTES to behave correctly for non-English
345 Typographically, there is a difference between the inch-mark and
346 quotation marks—a BIG difference. Sadly, typewriters and computer
347 keyboards supply only one: the inch-mark. While using inches for
348 doublequotes is, and always has been, acceptable in typewriter-style
349 copy, it has never been, and, God willing, never will be acceptable in
350 typeset copy. Failure to turn inches into quotes is the first thing
351 a professional typesetter notices in documents prepared by amateurs.
352 And you don’t want to look like an amateur, do you?
355 <h3 id="sq-international" class="docs">Internationalization</h3>
357 If you invoke SMARTQUOTES with one of the optional arguments
358 (<kbd>,,</kbd> or <kbd>>></kbd>
359 or <kbd><<</kbd>) you can use
360 <kbd>"</kbd> (ie the inch-mark/doublequotes key)
361 as “cheap” open-and close-quotes when inputting text in
362 a language other than English, and have mom convert them, on output,
363 into the chosen open-and close-quote style.
367 <kbd>,,</kbd> opens quotes with “lowered
368 doublequotes” and closes them with “raised
369 doublequotes”, as in this ascii approximation:
371 <span class="pre-in-pp">
375 <kbd>>></kbd> opens quotes with guillemets
376 pointing to the right, and closes them with guillemets pointing to
377 the left, as in this ascii approximation:
379 <span class="pre-in-pp">
380 >>Zurück !<<
382 <kbd><<</kbd> opens quotes with guillemets
383 pointing to the left, and closes them with guillemets pointing to
384 the right, as in this ascii approximation:
386 <span class="pre-in-pp">
387 <<Mais monsieur! Je ne suis pas ce genre de fille!>>
389 Please note: the above arguments to SMARTQUOTES are literal
390 ASCII characters. <kbd>,,</kbd> is two commas;
391 <kbd><<</kbd> is two less-than signs;
392 <kbd>>></kbd> is two greater-than signs.
396 Alternatively, you can pass SMARTQUOTES the two-letter, ISO 639
397 abbreviation for the language you’re writing in, and mom will
398 output the correct quotes.
400 <span class="pre-in-pp">
401 .SMARTQUOTES DA = Danish >>text<<
402 .SMARTQUOTES DE = German ,,text``
403 .SMARTQUOTES ES = Spanish ``text´´
404 .SMARTQUOTES FR = French << text >>
405 .SMARTQUOTES IT = Italian << text >>
406 .SMARTQUOTES NL = Dutch ´´text´´
407 .SMARTQUOTES NO = Norwegian <<text>>
408 .SMARTQUOTES PT = Portuguese <<text>>
409 .SMARTQUOTES SV = Swedish >>text>>
414 Turn SMARTQUOTES off by passing it any argument not in the argument
415 list (e.g. OFF, QUIT, X, etc.)
419 If you’re using the
420 <a href="docprocessing.html#docprocessing">document processing macros</a>
422 <a href="docprocessing.html#printstyle">PRINTSTYLE TYPESET</a>,
423 SMARTQUOTES is on by default (in the Anglo-American style); with
424 <a href="docprocessing.html#printstyle">PRINTSTYLE TYPEWRITE</a>,
425 it’s off by default (and should probably stay that way).
429 Finally, if you’re fussy about the kerning of quote marks in
430 relation to the text they surround, or have special quoting needs,
431 you have to enter quote marks by hand using groff’s native
432 <a href="definitions.html#inlines">inline escapes</a>
433 for special characters (see <kbd>man groff-char</kbd>
434 for a complete list of special characters). Entering quote marks
435 this way allows you to use mom’s
436 <a href="inlines.html#inline-kerning-mom">inline kerning escapes</a>
437 to fine-tune the look of quotes.
440 <div class="box-tip">
442 <span class="note">Note:</span>
443 SMARTQUOTES does not work on single quotes, which most people
444 input with the apostrophe (found at the right-hand end of the
445 “home row” on a QWERTY keyboard). Groff will interpret
446 all instances of the apostrophe as an apostrophe, making the symbol
447 useless as an open-single-quote. For open single quotes, input
448 the backtick character typically found under the tilde on most
449 keyboards. Here’s an example of correct input copy with
452 <span class="pre-in-pp">
453 "But she said, `I don’t want to!'"
457 <p class="tip-bottom" style="margin-top: -1em;">
458 <span class="additional-note">Additional note:</span>
459 Whether or not you have SMARTQUOTES turned on, get into the habit of
460 entering the foot-and inch-marks, when you need them, with the
461 <a href="definitions.html#inlines">inline escapes</a>
462 <kbd>\*[FOOT]</kbd> and
463 <kbd>\*[INCH]</kbd>, instead of
464 <kbd>'</kbd> and <kbd>"</kbd>.
470 <div class="macro-id-overline">
471 <h3 id="caps" class="macro-id">Convert to upper case</h3>
474 <div class="box-macro-args">
475 Macro: <b>CAPS</b> <kbd class="macro-args">toggle</kbd>
479 CAPS converts all lower case letters to upper case.
480 Primarily, it’s a support macro used by the
481 <a href="docprocessing.html#docprocessing">document processing macros</a>,
482 but you may find it helpful on occasion. CAPS is a toggle, therefore
483 no argument turns it on, any argument (OFF, QUIT, X, etc.) turns
486 <span class="pre-in-pp">
488 All work and no play makes Jack a dull boy.
494 <span class="pre-in-pp">
495 ALL WORK AND NO PLAY MAKES JACK A DULL BOY.
497 If you wish to capitalise a section of type inline, use the
498 <a href="definitions.html#inlines">inline escapes</a>,
499 <a href="inlines.html#uc-lc"><kbd>\*[UC]...\*[LC]</kbd></a>
502 <span class="pre-in-pp">
503 All work \*[UC]and\*[LC] no play makes Jack a dull boy.
506 The above produces, on output
508 <span class="pre-in-pp">
509 All work AND no play makes Jack a dull boy.
515 <div class="macro-id-overline">
516 <h3 id="string" class="macro-id">User-defined strings</h3>
519 <div class="box-macro-args">
520 Macro: <b>STRING</b> <kbd class="macro-args"><name> <what you want in the string></kbd>
524 You may find sometimes that you have to type out portions of text
525 repeatedly. If you’d like not to wear out your fingers, you can
526 define a string that, whenever you call it by name, outputs whatever
531 For example, say you’re creating a document that repeatedly uses
532 the phrase “the Montreal/Windsor corridor”. Instead
533 of typing all that out every time, you could define a string, like
536 <span class="pre-in-pp">
537 .STRING mw the Montreal/Windsor corridor
539 Once a string is defined, you can call it any time with the
540 <a href="definitions.html#inlines">inline escape</a>
541 <kbd>\*[<stringname>]</kbd>. Using the example
544 <span class="pre-in-pp">
545 The schedule for trains along \*[mw]:
549 <span class="pre-in-pp">
550 The schedule for trains along the Montreal/Windsor corridor:
554 <div class="box-tip">
556 <span class="note">Note:</span>
557 Be very careful not to put any spaces at the ends of strings
558 you’re defining, unless you want them. Everything after
559 the name argument you pass to STRING goes into the string,
560 including trailing spaces. It’s a good idea to get into the
561 habit of using groff’s native commenting mechanism, <kbd
562 class="bold">\"</kbd>, immediately following any string definition
563 in order to avoid spaces you can’t see, like this
565 <span class="pre-in-pp">
566 .STRING mw the Montreal/Windsor corridor\"
571 <div class="box-tip">
573 <span class="experts">Experts:</span>
574 STRING is an alias for
575 <b>ds</b>. You can use either, or mix 'n' match with impunity.
581 <div class="macro-id-overline">
582 <h3 id="esc-char" class="macro-id">Change the escape character</h3>
585 <div class="box-macro-args">
586 Macro: <b>ESC_CHAR</b> <kbd class="macro-args"><new character> | <anything></kbd>
590 Groff’s and mom’s default escape character is
591 the backslash. Sometimes, you may want to include a literal
592 backslash in your document. There are two ways to accomplish
593 this. One is simply to double the backslash character (<kbd
594 class="bold">\\</kbd>), which is convenient if you don’t have
595 a lot of backslashes to input. If you need to input a whole batch
596 of backslashes (say, when including code snippets in your document),
597 you can use ESC_CHAR to make the change permanent (until you decide
598 to restore the escape character to its default, the backslash).
602 ESC_CHAR with a single character argument changes the escape
603 character to whatever the argument is. ESC_CHAR with no argument
604 restores the escape character to the backslash.
608 <div class="box-tip">
610 <span class="experts">Experts:</span>
611 ESC_CHAR is an alias of <kbd>.ec</kbd>. Mix 'n' match
612 the two with impunity.
618 <div class="macro-id-overline">
619 <h3 id="sizespecs" class="macro-id">Get cap-height, x-height and descender depth of a font</h3>
622 <div class="box-macro-args">
623 Macro: <b>SIZESPECS</b>
627 Whenever you need to get the
628 <a href="definitions.html#capheight">cap-height</a>,
629 <a href="definitions.html#xheight">x-height</a>
631 <a href="definitions.html#descender">descender</a>
632 depth of type at the current point size, invoke <kbd
633 class="bold">.SIZESPECS</kbd>, which takes no argument.
634 The dimensions are stored in the string registers
635 <b>\*[$CAP_HEIGHT]</b>, <b>\*[$X_HEIGHT]</b> and
636 <b>\*[$DESCENDER]</b>, respectively, in
637 <a href="definitions.html#units">machine units</a>
639 <a href="definitions.html#unitofmeasure">unit of measure</a>,
640 <b>u</b>, is already appended.
644 Thus, if you wanted to advance 2 inches from your current position
645 on the page plus the cap-height of the current point size of type
647 <span class="pre-in-pp">
650 .ALD 2i+\*[$CAP_HEIGHT]
655 <!-- -UNDERSCORE- -->
657 <div class="macro-id-overline">
658 <h3 id="underscore" class="macro-id">Single underscore</h3>
661 <div class="box-macro-args">
662 Macro: <b>UNDERSCORE</b> <kbd class="macro-args">[ <distance below baseline> ] "<string>"</kbd>
666 • Optional argument requires a <a href="definitions.html#unitofmeasure">unit of measure</a>
670 By default, UNDERSCORE places an underscore 2 points beneath the
672 <a href="definitions.html#stringargument">string argument</a>.
673 The string must be enclosed in double-quotes, like this:
675 <span class="pre-in-pp">
676 .UNDERSCORE "Unmonitored monopolies breed high prices and poor products."
678 If you wish to change the distance of the rule from the baseline,
679 use the optional argument
680 <kbd><distance below baseline></kbd>
681 (with a unit of measure).
683 <span class="pre-in-pp">
684 .UNDERSCORE 3p "Unmonitored monopolies breed high prices and poor products."
686 The above places upper edge of the underscore 3 points below the
687 <a href="definitions.html#baseline">baseline</a>.
690 <div class="box-tip">
692 <span class="note">Note:</span>
693 UNDERSCORE does not work across line breaks in output copy, which is
694 to say that you can’t underscore a multi-line passage simply
695 by putting the text of the whole thing in the string you pass to
696 UNDERSCORE. If you need to underscore several lines of type, use
697 <a href="#underline">UNDERLINE</a>.
701 <h3 id="underscore-weight" class="docs">Controlling the weight of underscores</h3>
703 The weight (thickness) of underscores may be controlled with the
704 macro, UNDERSCORE_WEIGHT. Thus, if you want underscores with a
705 weight of 1-1/2 points, you’d invoke:
707 <span class="pre-in-pp">
708 .UNDERSCORE_WEIGHT 1.5
710 prior to invoking <kbd>.UNDERSCORE</kbd>. Every
711 subsequent instance of <kbd>.UNDERSCORE</kbd> will use
716 Mom’s default underscore weight is 1/2 point.
719 <div class="box-tip">
721 <span class="note">Note:</span>
722 UNDERSCORE_WEIGHT also sets the weight of
723 <a href="#UNDERSCORE2">double underscores.</a>
727 <h3 id="underscore-color" class="docs">Colorizing underscored text</h3>
729 If you want underscored text to be in a different colour from the
730 text around it, use the
731 <a href="color.html#color">COLOR</a>
732 macro, rather than the
733 <a href="color.html#color-inline">inline escape for changing color</a>.
734 In other words, assuming your prevailing text color is black and
735 you want underscored text in red
737 <span class="pre-in-pp">
739 .UNDERSCORE "text to underscore"
744 <span class="pre-in-pp">
745 .UNDERSCORE "\*[red]text to underscore\*[black]"
747 The latter will render the text in red, and the underscore in black.
748 You can use this to create truly rainbow effects if you want, e.g.
749 text in red, underscore in blue, and prevailing type in black:
751 <span class="pre-in-pp">
752 .UNDERSCORE "\*[red]text to underscore\*[blue]"
757 <!-- -UNDERSCORE2- -->
759 <div class="macro-id-overline">
760 <h3 id="underscore2" class="macro-id">Double underscore</h3>
763 <div class="box-macro-args">
764 Macro: <b>UNDERSCORE2</b> <kbd class="macro-args">[ <distance below baseline> [ <distance between rules> ] ] "<string>"</kbd>
768 • Optional arguments require a <a href="definitions.html#unitofmeasure">unit of measure</a>
772 By default, UNDERSCORE2 places a double underscore 2 points beneath
774 <a href="definitions.html#stringargument">string argument</a>.
775 The string must be enclosed in double-quotes, like this:
777 <span class="pre-in-pp">
778 .UNDERSCORE2 "Unmonitored monopolies breed high prices and poor products."
780 The default distance between the two rules is 2 points, measured
781 from the bottom edge of the upper rule to the top edge of the lower
786 If you wish to change the distance of the double underscore from the
787 <a href="definitions.html#baseline">baseline</a>,
788 use the optional argument
789 <kbd><distance below baseline></kbd>
790 (with a unit of measure), e.g.,
792 <span class="pre-in-pp">
793 .UNDERSCORE2 3p "Unmonitored monopolies breed high prices and poor products."
795 which places the upper edge of the first rule of the double
796 underscore 3 points below the baseline.
800 If you wish to change the distance between the two rules as well,
801 use the second optional argument
802 <kbd><distance between rules></kbd>
803 (with a unit of measure). Be aware that you must give a value for
804 the first optional argument if you want to use the second. The
805 distance between the two rules is measured from the bottom edge of
806 the upper rule to the top edge of the lower one.
810 The weight (thickness) of double underscores may be controlled with
812 <a href="#underscore-weight">UNDERSCORE_WEIGHT</a>
817 <div class="macro-id-overline">
818 <h3 id="underline" class="macro-id">Underline</h3>
821 <div class="box-macro-args">
822 Macro: <b>UNDERLINE</b> <kbd class="macro-args">toggle</kbd>
826 The distinction between underscoring and underlining is that
827 underscoring is suitable for occasional effects (a word here, a word
828 there), whereas underlining underlines whole passages of type.
829 Furthermore, you cannot colorize underlining, and there’s a
831 <a href="#underline-specs">UNDERLINE_SPECS</a>,
832 to control the weight and distance from the baseline of the
833 underline. Lastly, files that use UNDERLINE must be processed with
835 <span class="pre-in-pp">
836 pdfmom -Tps filename.mom | ps2pdf - filename.pdf
838 since groff's native pdf driver does not recognize UNDERLINE.
842 UNDERLINE is a toggle macro, therefore you invoke it by itself (ie
843 with no argument) to initiate underlining, and with any argument
844 (<kbd>OFF, QUIT, X,</kbd> etc) to turn it off.
847 <div class="box-tip">
849 <span class="note">Note:</span>
850 Underlining may also be turned on and off
851 <a href="definitions.html#inlines">inline</a>
853 <kbd><a href="#ul">\*[UL]...\*[ULX]</a></kbd>.
856 <p class="tip-bottom">
857 <span class="additional-note">Additional note:</span>
858 In document processing, neither <kbd>.UNDERLINE</kbd> nor
859 <kbd>\*[UL]</kbd> persist past the current document element tag.
860 For example, if you turn underlining on in a paragraph
861 (<kbd><a href="docelement.html#pp">.PP</a></kbd>),
862 your next paragraph will not be underlined.
866 <h4 id="underline-specs" class="docs">UNDERLINE_SPECS</h4>
869 The weight of underlining and the distance from the baseline is
872 <span class="pre-in-pp">
873 .UNDERLINE_SPECS <weight> <distance>
875 The <kbd><weight></kbd> argument can be expressed in any
876 <a href="definitions.html#unitofmeasure">unit of measure</a>
877 you like, but points is the most usual. Mom’s default is 1/2 point
878 (.5p). The same holds for the <kbd><distance></kbd> argument;
879 mom’s default is 1-1/4 points (1.25p).
884 <h4 id="ul" class="docs">INLINE ESCAPE FOR UNDERLINING</h4>
888 <kbd><a href="#underline">.UNDERLINE</a></kbd> /
889 <kbd>.UNDERLINE OFF</kbd>, and the inline escapes,
890 <kbd>\*[UL]</kbd> / <kbd>\*[ULX]</kbd>, are functionally identical,
892 <a href="definitions.html#filled">fill</a>
895 <span class="pre-in-pp">
905 produces the same result as
907 <span class="pre-in-pp">
908 Which should I heed? \*[UL]Just do it\*[ULX] or \*[UL]just say no?\*[ULX]
910 In either case, this is a misuse of UNDERLINE.
911 <a href="#underscore">UNDERSCORE</a>
917 <div class="macro-id-overline">
918 <h3 id="pad" class="macro-id">Insert equalized whitespace into lines</h3>
921 <div class="box-macro-args">
922 Macro: <b>PAD</b> <kbd class="macro-args">"<string with pad markers inserted>" [ NOBREAK ]</kbd>
926 With PAD, you can insert proportional amounts of whitespace into a
927 line. The optional <kbd id="nobreak" class="bold">NOBREAK</kbd>
928 argument tells mom not to advance on the page after the PAD macro
933 PAD calculates the difference between the length of text on the line
934 and the distance remaining to its end, then inserts the difference
935 (as whitespace) at the place(s) you specify.
939 Take, for example, the following relatively common typesetting
940 situation, found at the bottom of legal agreements:
948 The person signing the agreement is supposed to fill in the date
949 as well as a signature. Space needs to be left for both, but the
950 exact amount is neither known, nor important. All that matters is
951 that there be a little space after Date, and rather more space after
952 Signature. (In the above, <kbd>|</kbd> represents the
953 end of the line at the prevailing line length.)
958 <a href="goodies.html#pad-marker">pad marker</a>
959 (see below) is <kbd>#</kbd> (the pound or number sign
960 on your keyboard) and can be used multiple times in a line. With
961 that in mind, here’s how you’d input the Date/Signature line
962 (assuming a length of 30 picas):
966 .PAD "Date#Signature###"
971 When the line is output, the space remaining on the line, after
972 "Date" and "Signature" have been taken into
973 account, is split into four (because there are four # signs). One
974 quarter of the space is inserted between Date and Signature, the
975 remainder is inserted after Signature.
978 <div class="examples-container">
979 <h3 id="pad-example" class="docs notes">Example of PAD usage</h3>
980 <p style="margin-top: .5em;">
981 One rarely wants merely to insert space in a line; one usually wants
982 to fill it with something, hence PAD is particularly useful in
984 <a href="typesetting.html#string-tabs">string tabs</a>.
985 The following uses the Date/Signature example, above, but adds
986 rules into the whitespace through the use of string tabs and
988 <a href="definitions.html#inlines">inline escape</a>
989 <kbd><a href="inlines.html#inline-rule-mom">\*[RULE]</a></kbd>.
991 <span class="pre-in-pp">
993 .PAD "Date \*[ST1]#\*[ST1X] Signature \*[ST2]###\*[ST2X]" NOBREAK
1005 Here’s what the example does:
1007 <ol style="margin-top: -.5em; margin-bottom: -.5em;">
1008 <li>Pads the Date/Signature line with a shorter space for Date
1009 (<kbd>#</kbd>) and a longer space for Signature
1010 (<kbd>###</kbd>), encloses the padded space with string tabs
1011 markers, and outputs the line without advancing on the page.
1013 <li>Sets the quad for the two string tabs (in this instance, justified).
1015 <li>Calls the first string tab and draws a rule to its full
1018 <li>Calls the second tab with
1019 <a href="typesetting.html#tn">TN</a>
1020 (which moves to tab 2 and stays on the same baseline)
1021 then draws a rule to the full length of string tab 2.
1026 Often, when setting up string tabs this way, you don’t want the
1027 padded line to print immediately. To accomplish this, use
1028 <kbd><a href="#silent">SILENT</a></kbd>.
1030 <a href="typesetting.html#string-tabs-tut">quickie tutorial on string tabs</a>
1035 <div class="box-tip">
1037 <span class="note">Note:</span>
1038 Because the pound sign
1039 (<kbd>#</kbd>) is used as the pad marker, you
1040 can’t use it as a literal part of the pad string. If you need
1041 the sign to appear in the text of a padded line, change the pad
1043 <kbd><a href="#pad-marker">PAD_MARKER</a></kbd>.
1044 Also, be aware that <kbd>#</kbd> as a pad marker
1045 only applies within the PAD macro; at all other times it prints
1046 literally, just as you’d expect.
1049 <p class="tip-bottom">
1050 Another important consideration when using PAD is that because the
1051 string must be enclosed in double-quotes, you can’t use the
1052 double-quote (<kbd>"</kbd>) as part of the string. The
1053 way to circumvent this is to use the groff
1054 <a href="definitions.html#inlines">inline escapes</a>
1055 <kbd>\(lq</kbd> and <kbd>\(rq</kbd>
1056 (leftquote and rightquote respectively) whenever double-quotes are
1057 required in the string passed to PAD.
1061 <!-- -PAD_MARKER- -->
1063 <div class="macro-id-overline">
1064 <h3 id="pad-marker" class="macro-id">Change/set the marker used with PAD</h3>
1067 <div class="box-macro-args">
1068 Macro: <b>PAD_MARKER</b> <kbd class="macro-args">"<character to use as the pad marker></kbd>
1072 If you need to change mom’s default pad marker (<kbd
1073 class="bold">#</kbd>), either because you want a literal # in
1074 the padded line, or simply because you want to use another character
1075 instead, use PAD_MARKER, whose argument is the new pad marker
1078 <span class="pre-in-pp">
1081 changes the pad marker to <kbd>@</kbd>.
1085 Once you’ve changed the pad marker, the new marker remains in effect
1086 for every instance of
1087 <a href="#pad">PAD</a>
1088 until you change it again (say, back to the pound sign).
1091 <!-- -\*[LEADER]- -->
1093 <div class="macro-id-overline">
1094 <h3 id="leader" class="macro-id">Inline escape to add leaders to a line</h3>
1097 <div class="box-macro-args">
1098 Inline: <b>\*[LEADER]</b>
1102 Whenever you want to fill a line or tab with
1103 <a href="definitions.html#leader">leaders</a>,
1105 <a href="definitions.html#inlines">inline escape</a>
1106 <kbd>\*[LEADER]</kbd>. The remainder of the line or
1107 tab will be filled with the leader character. Mom’s default
1108 leader character is a period (dot), but you can change it to any
1109 character you like with
1110 <kbd><a href="#leader-character">LEADER_CHARACTER</a></kbd>.
1113 <div class="box-tip">
1115 <span class="note">Note:</span>
1116 <kbd>\*[LEADER]</kbd> fills lines or tabs right to
1117 their end. You cannot insert leaders into a line or tab and have
1118 text following the leader on the same line or in the same tab.
1119 Should you wish to achieve such an effect typographically, create
1120 tabs for each element of the line and fill them appropriately with
1121 the text and leaders you need.
1122 <a href="typesetting.html#string-tabs">String tabs</a>
1123 are perfect for this. An example follows.
1127 .PAD "Date\*[ST1]#\*[ST1X] Signature\*[ST2]###\*[ST2X]" NOBREAK
1139 <p class="tip-bottom">
1140 The PAD line sets the words Date and Signature, and marks string
1141 tabs around the pad space inserted in the line. The string tabs are
1142 then "set", called, and filled with leaders. The result
1145 <span class="pre" style="margin-bottom: -1em;">
1146 Date.............Signature.....................................
1151 <!-- -LEADER_CHARACTER- -->
1153 <div class="macro-id-overline">
1154 <h3 id="leader-character" class="macro-id">Change/set the leader character</h3>
1157 <div class="box-macro-args">
1158 Macro: <b>LEADER_CHARACTER</b> <kbd class="macro-args"><character></kbd>
1162 LEADER_CHARACTER takes one argument: a single character you would
1164 <a href="definitions.html#leader">leaders</a>.
1166 <kbd><a href="#leader">\*[LEADER]</a></kbd>
1167 for an explanation of how to fill lines with leaders.)
1171 For example, to change the leader character from mom’s
1172 default (a period) to the underscore character, enter
1174 <span class="pre-in-pp">
1179 <div class="box-tip">
1181 <span class="tip">Tip:</span>
1182 A particularly useful function of LEADER_CHARACTER is that it can be
1183 used to increase the spacing of mom’s default leaders. This is
1184 done by assigning to LEADER_CHARACTER both the period (dot) and a
1185 space. The technique requires a little low-level groffing:
1187 <span class="pre-in-pp">
1188 .char \[leader] . \"
1189 .LEADER_CHARACTER \[leader]
1191 The <kbd>.char</kbd>
1192 <a href="definitions.html#primitives">primitive</a>
1193 allows you to define a character called <kbd>leader</kbd>, to which
1194 you assign a period and a space. The <kbd>\"</kbd>, which, in
1195 groff, is used to add non-printing comments to a line, is not
1196 strictly necessary. Its presence here lets you see that
1197 there’s a space after the period.
1203 <div class="macro-id-overline">
1204 <h3 id="dropcap" class="macro-id">Drop caps</h3>
1207 <div class="box-macro-args">
1208 Macro: <b>DROPCAP</b> <kbd class="macro-args"><dropcap letter> <number of lines to drop> [ COND <percentage> | EXT <percentage> ]</kbd>
1212 The first two arguments to DROPCAP are the letter you want to be the
1213 <a href="definitions.html#dropcap">drop cap</a>
1214 and the number of lines you want it to drop. By default, mom uses
1215 the current family and font for the drop cap.
1219 The optional argument (<kbd>COND</kbd> or <kbd>EXT</kbd>) indicates
1220 that you want the drop cap condensed (narrower) or extended (wider).
1221 If you use <kbd class="bold">COND</kbd> or <kbd>EXT</kbd>, you must
1222 follow the argument with the percentage of the letter’s normal
1223 width you want it condensed or extended. No percent sign
1224 (<kbd>%</kbd>) is required.
1228 Mom will do her very best to get the drop cap to line up with the
1229 first line of text indented beside it, then set the correct number
1230 of indented lines, and restore your left margin when the number of
1231 drop cap lines has been reached.
1235 Beginning a paragraph with a drop cap “T” looks like this:
1238 .DROPCAP T 3 COND 90
1239 he thousand injuries of Fortunato I had borne as best I
1240 could, but when he ventured upon insult, I vowed revenge.
1241 You who so well know the nature of my soul will not suppose,
1242 however, that I gave utterance to a threat...
1247 The drop cap, slightly condensed but in the current family and font,
1248 will be three lines tall, with whatever text fills those three
1249 lines indented to the right of the letter. The remainder of the
1250 paragraph’s text will revert to the left margin.
1253 <div class="box-tip">
1255 <span class="note">Note:</span>
1257 <a href="docprocessing.html#docprocessing">document processing macro</a>
1258 <a href="docelement.html#pp">PP</a>,
1261 <ul style="margin-top: -1em; margin-bottom: 0;">
1262 <li>with initial paragraphs (ie at the start of the document,
1264 <a href="docelement.html#head">HEAD</a>),</li>
1265 <li>when <kbd>.DROPCAP</kbd> comes immediately after <kbd>.PP</kbd>,</li>
1267 <a href="docprocessing.html#printstyle">PRINTSTYLE</a>
1270 <p class="tip-bottom">
1271 If these conditions aren’t met, DROPCAP is silently ignored.
1275 <div class="box-important">
1277 <span class="important">Warning:</span>
1278 DROPCAP puts a bit of a strain on resource-challenged systems. If
1279 you have such a system and use drop caps extensively in a document,
1280 be prepared for a wait while mom does her thing.
1284 <h3 id="dropcap-support" class="docs control-macros-header">Support macros for DROPCAP</h3>
1286 Drop caps are the bane of most typesetters’ existence.
1287 It’s very difficult to get the size of the drop cap right
1288 for the number of drop lines, especially if the drop cap is in a
1289 different family from the prevailing family of running text. Not
1290 only that, but there’s the gutter around the drop cap to take
1291 into account, plus the fact that the letter may be too wide or too
1292 narrow to look anything but odd or misplaced.
1296 Mom solves the last of these problems with the <kbd>COND</kbd> and
1297 <kbd>EXT</kbd> arguments. The rest she solves with macros that
1298 change the default behaviour of DROPCAP, namely
1300 <ul class="no-enumerator" style="margin-top: -.5em; margin-left: -.5em;">
1301 <li><a href="#dropcap-family">DROPCAP_FAMILY</a></li>
1302 <li><a href="#dropcap-font">DROPCAP_FONT</a></li>
1303 <li><a href="#dropcap-color">DROPCAP_COLOR</a></li>
1304 <li><a href="#dropcap-adjust">DROPCAP_ADJUST</a></li>
1305 <li><a href="#dropcap-gutter">DROPCAP_GUTTER</a></li>
1308 <p style="margin-top: -.5em;">
1309 These macros must, of course, come before you invoke DROPCAP.
1312 <h3 id="dropcap-family" class="control-macro">• DROPCAP_FAMILY</h3>
1313 <p style="margin-left: .66em;">
1314 Set the drop cap family by giving DROPCAP_FAMILY the name of the
1315 family you want, e.g.
1317 <span class="pre-in-pp">
1320 which will set the family to Helvetica for the drop cap only.
1323 <h3 id="dropcap-font" class="control-macro">• DROPCAP_FONT</h3>
1324 <p style="margin-left: .66em;">
1325 Set the drop cap font by giving DROPCAP_FONT the name of the font
1328 <span class="pre-in-pp">
1331 which will set the font to italic for the drop cap only.
1334 <h3 id="dropcap-adjust" class="control-macro">• DROPCAP_ADJUST</h3>
1335 <p style="margin-left: .66em;">
1336 If the size mom calculates for the drop cap isn’t precisely
1337 what you want, you can increase or decrease it with DROPCAP_ADJUST,
1340 <span class="pre-in-pp">
1346 .DROPCAP_ADJUST -.75
1350 <p style="margin-left: .66em;">
1351 DROPCAP_ADJUST only understands
1352 <a href="definitions.html#picaspoints">points</a>,
1353 therefore do not append any
1354 <a href="definitions.html#unitofmeasure">unit of measure</a>
1355 to the argument. And always be sure to prepend the plus or
1356 minus sign, depending on whether you want the drop cap larger or
1360 <h3 id="dropcap-color" class="control-macro">• DROPCAP_COLOR</h3>
1361 <p style="margin-left: .66em;">
1362 If you’d like your drop cap colourized, simply invoke
1363 <kbd>.DROPCAP_COLOR <color></kbd> with the name of a
1364 colour you’ve already created (“initialized”) with
1365 <a href="color.html#newcolor">NEWCOLOR</a>
1367 <a href="color.html#xcolor">XCOLOR</a>.
1368 Only the drop cap will be colourized; all other text will remain at
1369 the current colour default (usually black).
1372 <h3 id="dropcap-gutter" class="control-macro">• DROPCAP_GUTTER</h3>
1373 <p style="margin-left: .66em;">
1374 By default, mom puts three points of space between the drop cap
1375 and the text indented beside it. If you want another value, use
1376 DROPCAP_GUTTER (with a unit of measure), like this:
1378 <span class="pre-in-pp">
1385 <div class="macro-id-overline">
1386 <h3 id="sup" class="macro-id">Superscript</h3>
1389 <div class="box-macro-args">
1390 Inlines: <kbd>\*[SUP]...\*[SUPX]</kbd>
1394 Superscripts are accomplished
1395 <a href="definitions.html#inlines">inline</a>.
1396 Whenever you need one, typically for numerals, all you need to do is
1397 surround the superscript with the inlines above. <kbd>\*[SUP]</kbd>
1398 begins superscripting; <kbd>\*[SUPX]</kbd> turns it off.
1401 <p id="cond-or-ext-sup">
1402 If your running type is
1403 <a href="typesetting.html#cond-inline">pseudo-condensed</a>
1405 <a href="typesetting.html#ext-inline">pseudo-extended</a>
1406 and you want your superscripts to be equivalently pseudo-condensed
1407 or -extended, use <kbd>\*[CONDSUP]...\*[CONDSUPX]</kbd> or
1408 <kbd>\*[EXTSUP]...\*[EXTSUPX]</kbd>.
1412 The superscript inlines are primarily used by the
1413 <a href="docprocessing.html#docprocessing">document processing macros</a>
1414 for automatic generation of numbered footnotes. However, you may
1415 find them useful for other purposes.
1418 <div class="box-tip">
1420 <span class="note">Note:</span>
1421 Mom does a pretty fine job of making superscripts look good in any
1422 font and at any size. If you’re fussy, though (and I am),
1423 about precise vertical placement, kerning, weight, size, and so on,
1424 you may want to roll your own solution.
1428 <h3 id="sup-raise" class="docs">SUPERSCRIPT RAISE AMOUNT</h3>
1430 By default, mom raises superscripts 1/3 of an
1431 <a href="definitions.html#em">em</a>
1432 above the baseline. If you’re not happy with this default,
1433 you can change it by invoking SUPERSCRIPT_RAISE_AMOUNT with the
1434 amount you want them raised. A
1435 <a href="definitions.html#unitofmeasure">unit of measure</a>
1436 must be appended directly to the amount. Thus, you want
1437 superscripts raised by 3
1438 <a href="definitions.html#picaspoints">points</a>
1439 instead of 1/3 em, you’d do
1441 <span class="pre-in-pp">
1442 .SUPERSCRIPT_RAISE_AMOUNT 3p
1444 and all subsequent superscripts would be raised by 3 points.
1447 <div class="rule-long"><hr/></div>
1449 <!-- Navigation links -->
1450 <table style="width: 100%; margin-top: 12px;">
1452 <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
1453 <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td>
1454 <td style="width: 33%; text-align: right;"><a href="inlines.html#top">Next: Inline escapes</a></td>
1460 <div class="bottom-spacer"><br/></div>
1464 <!-- vim: fileencoding=utf-8: nomodified: -->
projects / platform / upstream / groff.git / blob