diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:44:05 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:44:05 +0000 |
| commit | d318611dd6f23fcfedd50e9b9e24620b102ba96a (patch) | |
| tree | 8b9eef82ca40fdd5a8deeabf07572074c236095d /contrib/mom/momdoc/goodies.html | |
| parent | Initial commit. (diff) | |
| download | groff-d318611dd6f23fcfedd50e9b9e24620b102ba96a.tar.xz groff-d318611dd6f23fcfedd50e9b9e24620b102ba96a.zip | |
Adding upstream version 1.23.0.upstream/1.23.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'contrib/mom/momdoc/goodies.html')
| -rw-r--r-- | contrib/mom/momdoc/goodies.html | 1785 |
1 files changed, 1785 insertions, 0 deletions
diff --git a/contrib/mom/momdoc/goodies.html b/contrib/mom/momdoc/goodies.html new file mode 100644 index 0000000..7c39e14 --- /dev/null +++ b/contrib/mom/momdoc/goodies.html @@ -0,0 +1,1785 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004-2020 Free Software Foundation, Inc. +Written by Peter Schaffter (peter@schaffter.ca). + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> + +<!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=utf-8"/> + <title>Mom -- Goodies</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="inlines.html#top">Next: Inline escapes</a></td> +</tr> +</table> + +<h1 id="goodies" class="docs">Goodies</h1> + +<p> +The macros in this section are a collection of useful (and sometimes +nearly indispensable) routines to simplify typesetting. +</p> + +<div id="goodies-macros-mini-toc" style="margin-top: -1em; font-size: 95%;"> +<div class="mini-toc-col-1"> +<ul class="no-enumerator"> +<li class="list-head-goodies"><a href="#alias">ALIAS</a> <span class="normal-smaller">– rename macros</span></li> +<li class="list-head-goodies"><a href="#caps">CAPS</a> <span class="normal-smaller">– convert to upper case</span></li> +<li class="list-head-goodies"><a href="#center-block">CENTER_BLOCK</a> <span class="normal-smaller">– centre blocks of type with quad intact</span></li> +<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> +<li class="list-head-goodies"><a href="#hang">HANG</a> <span class="normal-smaller">– hang character(s) outside right margin (inline escape)</span></li> +<li class="list-head-goodies"><a href="#left-hang">LEFT_HANG</a> <span class="normal-smaller">– hang character(s) outside left margin</span></li> +<li class="list-head-goodies"><a href="#silent">SILENT</a> <span class="normal-smaller">– hide input lines from output</span></li> +<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> +<li class="list-head-goodies"><a href="#smartquotes">SMARTQUOTES</a> <span class="normal-smaller">– convert typewriter doublequotes to proper doublequotes</span></li> +<li class="list-head-goodies"><a href="#string">STRING</a> <span class="normal-smaller">– user-definable strings</span></li> +<li class="list-head-goodies"><a href="#trap">TRAP</a> <span class="normal-smaller">– suspend/re-invoke traps</span></li> +<li class="list-head-goodies no-anchor"><span style="font-size: 90%;">Underscoring/underlining</span> +<ul class="sublist"> + <li class="list-head-goodies text-color"><a href="#underscore">UNDERSCORE</a> <span class="normal-smaller">– single underscore</span> + <ul class="sublist sub"> + <li class="list-head-goodies text-color"><a href="#underscore-weight">Controlling the weight of underscores</a></li> + <li class="list-head-goodies text-color"><a href="#underscore-color">Colourising underscores</a></li> + </ul></li> + <li class="list-head-goodies text-color"><a href="#underscore2">UNDERSCORE2</a> <span class="normal-smaller">– double underscore</span></li> + <li class="list-head-goodies text-color"><a href="#underline">UNDERLINE</a> + <ul class="sublist sub"> + <li class="list-head-goodies text-color"><a href="#ul">\*[UL]</a> <span class="normal-sub-sub">– inline escape to underline</span></li> + </ul></li> +</ul></li> +<li class="list-head-goodies no-anchor"><span style="font-size: 90%;">Padding</span> +<ul class="sublist"> + <li class="list-head-goodies text-color"><a href="#pad">PAD</a> <span class="normal-smaller">– insert equalized whitespace into lines</span> + <ul class="sublist sub"> + <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> + </ul></li> +</ul></li> +</ul> +</div> +<div class="mini-toc-col-2"> +<ul class="no-enumerator"> +<li class="list-head-goodies no-anchor"><span style="font-size: 90%;">Leaders</span> +<ul class="sublist"> + <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> + <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> +</ul></li> +<li class="list-head-goodies no-anchor"><span style="font-size: 90%;">Drop caps</span> +<ul class="sublist"> + <li class="list-head-goodies text-color"><a href="#dropcap">DROPCAP</a> <span class="normal-smaller">– set a drop cap</span></li> + <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> + <ul class="sublist sub"> + <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> + <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> + <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> + <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> + <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> + </ul></li> +</ul></li> +<li class="list-head-goodies text-color no-anchor"><span style="font-size: 90%;">Superscripts</span> +<ul class="sublist"> + <li class="list-head-goodies text-color"><a href="#sup">\*[SUP]</a> <span class="normal-smaller">– inline escape to set superscripts</span> + <ul class="sublist sub"> + <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> + <li class="list-head-goodies text-color"><a href="#cond-or-ext-sup">\*[CONDSUP]</a> <span class="normal-sub-sub">– condensed superscripts</span></li> + <li class="list-head-goodies text-color"><a href="#cond-or-ext-sup">\*[EXTSUP]</a> <span class="normal-sub-sub">– extended superscripts</span></li> + </ul></li> +</ul></li> +</ul> +</div> +</div> + +<div class="rule-medium" style="padding-bottom: 1em;"><hr/></div> + +<!-- -ALIAS- --> + +<div class="macro-id-overline"> +<h3 id="alias" class="macro-id">Rename macros</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>ALIAS</b> <kbd class="macro-args"><new name> <old name></kbd> +</div> + +<p> +The ALIAS 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 mom). +</p> + +<p> +Groff has always been a bit intimidating for new users because +its standard macro packages use very terse macro names. Mom +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, mom 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 mom’s macro names, say, +PAGEWIDTH, change it, like this: +<br/> +<span class="pre-in-pp"> + .ALIAS PW PAGEWIDTH + | | + new--+ +--official + name name +</span> +The first argument to ALIAS is the new name you want for a macro. +The second is the “official” name by which the macro is +normally invoked. After ALIAS, either can be used. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="tip">Tip:</span> +A particularly good candidate for ALIAS is the macro +<a href="typesetting.html#ps">PT_SIZE</a>. +A more natural name for it would simply be PS, but PS conflicts +with the <b>eqn</b> equation preprocessor and thus mom uses the +longer form. However, if you’re not using <b>eqn</b>, you can +happily rename PT_SIZE to +PS: +<br/> +<span class="pre-in-pp"> + .ALIAS PS PT_SIZE +</span> +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If you use ALIAS a lot, and always for the same things, consider +creating an aliases file of the form +<br/> +<span class="pre-in-pp"> + .ALIAS <new name> <old name> + .ALIAS <new name> <old name> + .ALIAS <new name> <old name> + ...etc +</span> +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 +<b>mom-aliases</b> in your home directory under a directory called +<b>Mom</b>, you’d source it by placing +<br/> +<span class="pre-in-pp"> + .INCLUDE /home/<username>/Mom/mom-aliases +</span> +at the top of your documents. +</p> + +<p class="tip-bottom"> +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> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="experts">Experts:</span> +ALIAS is an alias of <kbd>.als</kbd>. You can use either, or mix +’n’ match with impunity. +</p> +</div> + +<!-- -SILENT- --> +<div class="macro-id-overline"> +<h3 id="silent" class="macro-id">Hide input lines from output</h3> +</div> + +<div class="box-macro-args"> + Macro: <b>SILENT</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>COMMENT</b> +</p> + +<p> +Sometimes, you want to “hide” +<a href="definitions.html#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 SILENT macro. +</p> + +<p> +SILENT is a toggle. Invoking it without an argument turns it on; +any argument turns it off. E.g., +<br/> +<span class="pre-in-pp"> + .SILENT + A line of text + .SILENT OFF +</span> +The line “A line of text” will not appear in the +output copy. +</p> + +<p> +SILENT is aliased as COMMENT. If you want to insert non-printing +comments into your documents, you may prefer this. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="tip">Tip:</span> +SILENT does not automatically break an +<a href="definitions.html#inputline">input line</a> +(see +<a href="typesetting.html#br">BR</a>) +when you’re in one of the +<a href="definitions.html#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 J or QUAD argument. You must +insert <kbd>.BR</kbd> yourself, or risk a portion of your text +disappearing into a black hole. +</p> +</div> + +<!-- -TRAP- --> + +<div class="macro-id-overline"> +<h3 id="trap" class="macro-id">Suspend / re-invoke traps</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>TRAP</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +Traps are vertical positions on the output page at which +you or mom have instructed groff to start doing something +automatically. Commonly, this is near the bottom of the page, where +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 +<br/> +<span class="pre-in-pp"> + .TRAP OFF + ... + .TRAP +</span> +TRAP is a toggle, therefore any argument turns it off (i.e., suspends +the trap), and no argument turns it (back) on. +</p> + +<!-- -SMARTQUOTES- --> + +<div class="macro-id-overline"> +<h3 id="smartquotes" class="macro-id">Convert typewriter doublequotes to proper doublequotes</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>SMARTQUOTES</b> <kbd class="macro-args">[<off>] [ ,, | >> | << ]</kbd> +</div> + +<span style="margin-left: .5em">or</span> + +<div class="box-macro-args"> +Macro: <b>SMARTQUOTES</b> <kbd class="macro-args">DA | DE | ES | FR | IT | NL | NO | PT | SV</kbd> +</div> + +<p> +If you invoke SMARTQUOTES without an argument, mom 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 +quotation marks—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> + +<h3 id="sq-international" class="docs">Internationalization</h3> +<p> +If you invoke SMARTQUOTES with one of the optional arguments +(<kbd>,,</kbd> or <kbd>>></kbd> +or <kbd><<</kbd>) you can use +<kbd>"</kbd> (i.e. the inch-mark/doublequotes key) +as “cheap” open-and close-quotes when inputting text in +a language other than English, and have mom 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: +<br/> +<span class="pre-in-pp"> + ,,Hilfe !`` +</span> + +<kbd>>></kbd> opens quotes with guillemets +pointing to the right, and closes them with guillemets pointing to +the left, as in this ascii approximation: +<br/> +<span class="pre-in-pp"> + >>Zurück !<< +</span> +<kbd><<</kbd> opens quotes with guillemets +pointing to the left, and closes them with guillemets pointing to +the right, as in this ascii approximation: +<br/> +<span class="pre-in-pp"> + <<Mais monsieur! Je ne suis pas ce genre de fille!>> +</span> +Please note: the above arguments to SMARTQUOTES are literal +ASCII characters. <kbd>,,</kbd> is two commas; +<kbd><<</kbd> is two less-than signs; +<kbd>>></kbd> is two greater-than signs. +</p> + +<p> +Alternatively, you can pass SMARTQUOTES the two-letter, ISO 639 +abbreviation for the language you’re writing in, and mom will +output the correct quotes. +<br/> +<span class="pre-in-pp"> + .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>> +</span> +</p> + +<p> +Turn SMARTQUOTES off by passing it any argument not in the argument +list (e.g. <kbd>OFF</kbd>, <kbd>QUIT</kbd>, <kbd>X</kbd>, 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>, +smartquotes are 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#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 mom’s +<a href="inlines.html#inline-kerning-mom">inline kerning escapes</a> +to fine-tune the look of quotes. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +SMARTQUOTES 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. Here’s an example of correct input copy with +single quotes: +<br/> +<span class="pre-in-pp"> + "But she said, `I don’t want to!'" +</span> +</p> + +<p class="tip-bottom" style="margin-top: -1em;"> +<span class="additional-note">Additional note:</span> +Whether or not you have SMARTQUOTES turned on, get into the habit of +entering the foot-and inch-marks, when you need them, with the +<a href="definitions.html#inlines">inline escapes</a> +<kbd><span class="nobr">\*[FOOT]</span></kbd> and +<kbd><span class="nobr">\*[INCH]</span></kbd>, instead of +<kbd>'</kbd> and <kbd>"</kbd>. +</p> +</div> + +<!-- -CAPS- --> + +<div class="macro-id-overline"> +<h3 id="caps" class="macro-id">Convert to upper case</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>CAPS</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +CAPS 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. CAPS is a toggle, therefore +no argument turns it on, any argument (<kbd>OFF</kbd>, +<kbd>QUIT</kbd>, <kbd>X</kbd>, etc) turns it off. +<br/> +<span class="pre-in-pp"> + .CAPS + All work and no play makes Jack a dull boy. + .CAPS OFF +</span> + +produces, on output +<br/> +<span class="pre-in-pp"> + ALL WORK AND NO PLAY MAKES JACK A DULL BOY. +</span> +If you wish to capitalise a section of type inline, use the +<a href="definitions.html#inlines">inline escapes</a>, +<a href="inlines.html#uc-lc"><kbd><span class="nobr">\*[UC]...\*[LC]</span></kbd></a> +like this: +<br/> +<span class="pre-in-pp"> + All work \*[UC]and\*[LC] no play makes Jack a dull boy. +</span> + +The above produces, on output +<br/> +<span class="pre-in-pp"> + All work AND no play makes Jack a dull boy. +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +<kbd>\*[LC]</kbd> must come after a terminating period. +<br/> +<span class="pre-in-pp"> + \*[UC]All work and no play makes Jack a dull boy.\*[LC] +</span> +not +<span class="pre-in-pp"> + \*[UC]All work and no play makes Jack a dull boy\*[LC]. +</span> +Conversely, an initial period must come <em>before</em> +<kbd>\*[UC]</kbd>, or be preceded by <kbd>\&</kbd>, like this: +<br/> +<span class="pre-in-pp"> + .\*[UC]start\*[LC] is used to begin document processing. +</span> +or +<span class="pre-in-pp"> + \*[UC]\&.start\*[LC] is used to begin document processing. +</span> +Upon output, either will produce +<br/> +<span class="pre-in-pp"> + START is used to begin document processing. +</span> +</p> +</div> + +<!-- -STRING- --> + +<div class="macro-id-overline"> +<h3 id="string" class="macro-id">User-defined strings</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>STRING</b> <kbd class="macro-args"><name> <what you want in the string></kbd> +</div> + +<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: +<br/> +<span class="pre-in-pp"> + .STRING mw the Montreal/Windsor corridor +</span> +Once a string is defined, you can call it any time with the +<a href="definitions.html#inlines">inline escape</a> +<kbd><span class="nobr">\*[<name>]</span></kbd>. Using the example +string above +<br/> +<span class="pre-in-pp"> + The schedule for trains along \*[mw]: +</span> +produces, on output +<br/> +<span class="pre-in-pp"> + The schedule for trains along the Montreal/Windsor corridor: +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +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 STRING goes into the string, +including trailing spaces. It’s a good idea to get into the +habit of using groff’s native commenting mechanism, <kbd +class="bold">\"</kbd>, immediately following any string definition +in order to avoid spaces you can’t see, like this +<br/> +<span class="pre-in-pp"> + .STRING mw the Montreal/Windsor corridor\" +</span> +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="experts">Experts:</span> +STRING is an alias for <b>ds</b>. You can use either, or mix +’n’ match with impunity. +</p> +</div> + +<!-- -ESC_CHAR- --> + +<div class="macro-id-overline"> +<h3 id="esc-char" class="macro-id">Change the escape character</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>ESC_CHAR</b> <kbd class="macro-args"><new character> | <anything></kbd> +</div> + +<p> +Groff’s and mom’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 (<kbd +class="bold">\\</kbd>), 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 ESC_CHAR to make the change permanent (until you decide +to restore the escape character to its default, the backslash). +</p> + +<p> +ESC_CHAR with a single character argument changes the escape +character to whatever the argument is. ESC_CHAR with no argument +restores the escape character to the backslash. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="important">Important:</span> +Changing the escape character prevents macros, which require that +the backslash be the escape character, from functioning correctly. +Do not introduce any subsequent macros without first restoring the +escape character to its default. +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="experts">Experts:</span> +ESC_CHAR is an alias of <kbd>.ec</kbd>. Mix ’n’ match +the two with impunity. +</p> +</div> + +<!-- -SIZESPECS- --> + +<div class="macro-id-overline"> +<h3 id="sizespecs" class="macro-id">Get cap-height, x-height and descender depth of a font</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>SIZESPECS</b> +</div> + +<p> +Whenever you need to get the +<a href="definitions.html#capheight">cap-height</a>, +<a href="definitions.html#xheight">x-height</a> +or +<a href="definitions.html#descender">descender</a> +depth of type at the current point size, invoke <kbd +class="bold">.SIZESPECS</kbd>, which takes no argument. +The dimensions are stored in the string registers +<b><span class="nobr">\*[$CAP_HEIGHT]</span></b>, +<b><span class="nobr">\*[$X_HEIGHT]</span></b>, +and +<b><span class="nobr">\*[$DESCENDER]</span></b>, respectively, in +<a href="definitions.html#units">machine units</a> +to which the +<a href="definitions.html#unitofmeasure">unit of measure</a>, +<b>u</b>, is already appended. +</p> + +<p> +Thus, if you wanted to advance 2 inches from your current position +on the page plus the cap-height of the current point size of type +<br/> +<span class="pre-in-pp"> + .PT_SIZE <n> + .SIZESPECS + .ALD 2i+\*[$CAP_HEIGHT] +</span> +would do the trick. +</p> + +<!-- -UNDERSCORE- --> + +<div class="macro-id-overline"> +<h3 id="underscore" class="macro-id">Single underscore</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>UNDERSCORE</b> <kbd class="macro-args">[ <distance below baseline> ] [ PREFIX <prefix> ] [ SUFFIX <suffix> ] "<string>"</kbd> +</div> + +<p class="requires"> +• <distance below baseline> requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +By default, UNDERSCORE places an underscore 2 points beneath the +required +<a href="definitions.html#stringargument">string argument</a>. +The string must be enclosed in double-quotes, like this: +<br/> +<span class="pre-in-pp"> + .UNDERSCORE "Unmonitored monopolies breed high prices and poor products" +</span> +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). +<br/> +<span class="pre-in-pp"> + .UNDERSCORE 3p "Unmonitored monopolies breed high prices and poor products" +</span> +The above places the upper edge of the underscore 3 points below the +<a href="definitions.html#baseline">baseline</a>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Tip:</span> +UNDERSCORE can also be used for strikethrough effects by supplying a +negative value to the distance argument. +</p> +</div> + +<p> +<kbd>PREFIX</kbd> and <kbd>SUFFIX</kbd> allow you to add +non-underscored punctuation (or other glyphs) to the beginning +and/or end of the underscored string. If the argument to either +<kbd>PREFIX</kbd> or <kbd>SUFFIX</kbd> contains spaces, surround the +argument with double-quotes. For example, the following underscores +the text string but not the surrounding punctuation. +<br/> +<span class="pre-in-pp"> + .UNDERSCORE PREFIX ( SUFFIX .) "Unmonitored monopolies breed high prices and poor products" +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +UNDERSCORE 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 +UNDERSCORE. If you need to underscore several lines of type, use +<a href="#underline">UNDERLINE</a>. +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Additional note:</span> +In +<a href="definitions.html#filled">nofill modes</a>, +UNDERSCORE causes a break before and after, meaning the underscored +word or phrase will appear as a separate line in your output. If +you wish to embed an underscored word or phrase into non-filled +text, temporarily change to the corresponding fill mode with +<a href="typesetting.html#quad">QUAD</a> +and insert breaks manually with +<a href="typesetting.html#br">BR</a> +as appropriate, reverting to the original nofill mode afterwards. +</p> +</div> + +<h3 id="underscore-weight" class="docs">Controlling the weight of underscores</h3> +<p> +The weight (thickness) of underscores may be controlled with the +macro UNDERSCORE_WEIGHT. Thus, if you want underscores with a +weight of 1-1/2 points, you’d invoke: +<br/> +<span class="pre-in-pp"> + .UNDERSCORE_WEIGHT 1.5 +</span> +prior to invoking <kbd>.UNDERSCORE</kbd>. Every +subsequent instance of <kbd>.UNDERSCORE</kbd> will use +this weight. +</p> + +<p> +Mom’s default underscore weight is 1/2 point. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +UNDERSCORE_WEIGHT also sets the weight of +<a href="#UNDERSCORE2">double underscores.</a> +</p> +</div> + +<h3 id="underscore-color" class="docs">Colourising underscored text</h3> +<p> +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 colour</a>. +In other words, assuming your prevailing text colour is black and +you want underscored text in red +<br/> +<span class="pre-in-pp"> + .COLOR red + .UNDERSCORE "text to underscore" + .COLOR black +</span> +rather than +<br/> +<span class="pre-in-pp"> + .UNDERSCORE "\*[red]text to underscore\*[black]" +</span> +The latter will render the text in red but the underscore in black. +You can, of course, use this to create rainbow effects if that's +what you want, e.g. text in red, underscore in blue, and prevailing +type in black: +<br/> +<span class="pre-in-pp"> + .UNDERSCORE "\*[red]text to underscore\*[blue]" + .COLOR black +</span> +</p> + +<!-- -UNDERSCORE2- --> + +<div class="macro-id-overline"> +<h3 id="underscore2" class="macro-id">Double underscore</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>UNDERSCORE2</b> <kbd class="macro-args">[ <distance below baseline> [ <distance between rules> ] [ PREFIX <prefix> ] [ SUFFIX <suffix> ] "<string>"</kbd> +</div> + +<p class="requires"> +• <distance below baseline> +and +<distance between rules> +require a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +By default, UNDERSCORE2 places a double underscore 2 points beneath +the required +<a href="definitions.html#stringargument">string argument</a>. +The string must be enclosed in double-quotes, like this: +<br/> +<span class="pre-in-pp"> + .UNDERSCORE2 "Unmonitored monopolies breed high prices and poor products" +</span> +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 +<a href="definitions.html#baseline">baseline</a>, +use the optional argument +<kbd><distance below baseline></kbd> +(with a unit of measure), e.g. +<br/> +<span class="pre-in-pp"> + .UNDERSCORE2 3p "Unmonitored monopolies breed high prices and poor products" +</span> +which places the upper edge of the first rule of the double +underscore 3 points below the baseline. +</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). The distance between the two rules +is measured from the bottom edge of the upper rule to the top +edge of the lower one. Be aware that you must give a value for +<kbd><distance below baseline></kbd> if you want to +use <kbd><distance between rules></kbd>. +</p> + +<p> +<kbd>PREFIX</kbd> and <kbd>SUFFIX</kbd> allow you to add +non-underscored punctuation (or other glyphs) to the beginning +and/or end of the double-underscored string. If the argument to +either <kbd>PREFIX</kbd> or <kbd>SUFFIX</kbd> contains spaces, +surround the argument with double-quotes. For example, the +following double-underscores the text string but not the surrounding +punctuation. +<br/> +<span class="pre-in-pp"> + .UNDERSCORE2 PREFIX ( SUFFIX .) "Unmonitored monopolies breed high prices and poor products" +</span> +The weight (thickness) of double underscores may be controlled with +the macro +<a href="#underscore-weight">UNDERSCORE_WEIGHT</a> +(q.v). +</p> + +<p> +See +<a href="#underscore-color">here</a> +for advice on colourising double-underscored text. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +In +<a href="definitions.html#filled">nofill modes</a>, +UNDERSCORE2 causes a break before and after, meaning the double-underscored +word or phrase will appear as a separate line in your output. If +you wish to embed a double-underscored word or phrase into non-filled +text, temporarily change to the corresponding fill mode with +<a href="typesetting.html#quad">QUAD</a> +and insert breaks manually with +<a href="typesetting.html#br">BR</a> +as appropriate, reverting to the original nofill mode afterwards. +</p> +</div> + +<!-- -UNDERLINE- --> +<div class="macro-id-overline"> +<h3 id="underline" class="macro-id">Underline</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>UNDERLINE</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +The distinction between underscoring and underlining is that +underscoring is suitable for occasional effects (a word here, +a phrase there), whereas underlining underlines whole passages +of type. Furthermore, you cannot colourise underlining. +There’s a special macro, +<a href="#underline-specs">UNDERLINE_SPECS</a>, +to control the weight and distance from the baseline of the +underline. +</p> + +<p> +Lastly, files that use UNDERLINE must be processed with +<br/> +<span class="pre-in-pp"> + pdfmom -Tps filename.mom | ps2pdf - filename.pdf +</span> +since groff’s pdf driver does not recognize UNDERLINE. +</p> + +<p> +Note that +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPEWRITE</a> +uses UNDERLINE to underline italics +and pseudo-italics (<a href="typesetting.html#slant-inline">SLANT</a>) +by default. The default may be changed (see +<a href="docprocessing.html#printstyle-italics">Underlining of italics</a>) +but if it's what you want, you must process your document as shown +above. +</p> + +<p> +UNDERLINE is a toggle macro, therefore you invoke it by itself (i.e. +with no argument) to initiate underlining, and with any argument +(<kbd>OFF</kbd>, <kbd>QUIT</kbd>, <kbd>END</kbd>, <kbd>X</kbd>, etc) +to turn it off. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +Underlining may also be turned on and off +<a href="definitions.html#inlines">inline</a> +with the escapes +<a href="#ul"><kbd><span class="nobr">\*[UL]...\*[ULX]</span></kbd></a>. +</p> + +<p class="tip-bottom"> +<span class="additional-note">Additional note:</span> +In document processing, neither <kbd>.UNDERLINE</kbd> nor +<kbd><span class="nobr">\*[UL]</span></kbd> persist past the current document element tag. +For example, if you turn underlining on in a paragraph +(<kbd><a href="docelement.html#pp">.PP</a></kbd>), +your next paragraph will not be underlined. +</p> +</div> + +<h4 id="underline-specs" class="docs">UNDERLINE_SPECS</h4> + +<p> +The weight of underlining and the distance from the baseline is +set with +<br/> +<span class="pre-in-pp"> + .UNDERLINE_SPECS <weight> <distance> +</span> +The <kbd><weight></kbd> argument can be expressed in any +<a href="definitions.html#unitofmeasure">unit of measure</a> +you like, but points is the most usual. Mom’s default is 1/2 point +(.5p). The same holds for the <kbd><distance></kbd> argument; +mom’s default is 1-1/4 points (1.25p). +</p> + +<!-- -UL- --> + +<h4 id="ul" class="docs">INLINE ESCAPE FOR UNDERLINING</h4> + +<p> +The macro pair, +<kbd><a href="#underline">.UNDERLINE</a></kbd> / +<kbd>.UNDERLINE OFF</kbd>, and the inline escapes, +<span class="nobr"><kbd>\*[UL]</kbd> / <kbd>\*[ULX]</kbd></span>, are +functionally identical, hence, in +<a href="definitions.html#filled">fill</a> +modes +<br/> +<span class="pre-in-pp"> + Which should I heed? + .UNDERLINE + Just do it + .UNDERLINE OFF + or + .UNDERLINE + just say no? + .UNDERLINE OFF +</span> +produces the same result as +<br/> +<span class="pre-in-pp"> + Which should I heed? \*[UL]Just do it\*[ULX] or \*[UL]just say no?\*[ULX] +</span> +In either case, this is a misuse of UNDERLINE. +<a href="#underscore">UNDERSCORE</a> +is preferable. +</p> + +<!-- -PAD- --> + +<div class="macro-id-overline"> +<h3 id="pad" class="macro-id">Insert equalized whitespace into lines</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PAD</b> <kbd class="macro-args">"<string with pad markers inserted>" [ NOBREAK ]</kbd> +</div> + +<p> +With PAD, you can insert proportional amounts of whitespace into a +line. The optional <kbd id="nobreak" class="bold">NOBREAK</kbd> +argument tells mom not to advance on the page after the PAD macro +has been invoked. +</p> + +<p> +PAD 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: +<br/> +<span class="pre"> + Date Signature | +</span> +</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, <kbd>|</kbd> 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 <kbd>#</kbd> (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): +<br/> +<span class="pre"> + .LL 30P + .PAD "Date#Signature###" +</span> +</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> + +<div class="examples-container"> +<h3 id="pad-example" class="docs notes">Example of PAD usage</h3> +<p style="margin-top: .5em;"> +One rarely wants merely to insert space in a line; one usually wants +to fill it with something, hence PAD 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 +mom’s +<a href="definitions.html#inlines">inline escape</a> +<a href="inlines.html#inline-rule-mom"><kbd><span class="nobr">\*[RULE]</span></kbd></a>. +<br/> +<span class="pre-in-pp"> + .LL 30P + .PAD "Date \*[ST1]#\*[ST1X] Signature \*[ST2]###\*[ST2X]" NOBREAK + .ST 1 J + .ST 2 J + .TAB 1 + \*[RULE] + .TN + \*[RULE] + .TQ +</span> +</p> + +<p> +Here’s what the example does: +</p> +<ol style="margin-top: -.5em; margin-bottom: -.5em;"> + <li>Pads the Date/Signature line with a shorter space for Date + (<kbd>#</kbd>) and a longer space for Signature + (<kbd>###</kbd>), encloses the padded space with string tabs + markers, and outputs the line without advancing on the page. + </li> + <li>Sets the quad for the two string tabs (in this instance, justified). + </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> +Often, when setting up string tabs this way, you don’t want the +padded line to print immediately. To accomplish this, use +<kbd><a href="#silent">SILENT</a></kbd>. +See the +<a href="typesetting.html#string-tabs-tut">quickie tutorial on string tabs</a> +for an example. +</p> +</div> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +Because the pound sign +(<kbd>#</kbd>) 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 +<kbd><a href="#pad-marker">PAD_MARKER</a></kbd>. +Also, be aware that <kbd>#</kbd> as a pad marker +only applies within the PAD macro; at all other times it prints +literally, just as you’d expect. +</p> + +<p class="tip-bottom"> +Another important consideration when using PAD is that because the +string must be enclosed in double-quotes, you can’t use the +double-quote (<kbd>"</kbd>) as part of the string. The +way to circumvent this is to use the groff +<a href="definitions.html#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 PAD. +</p> +</div> + +<!-- -PAD_MARKER- --> + +<div class="macro-id-overline"> +<h3 id="pad-marker" class="macro-id">Change/set the marker used with PAD</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PAD_MARKER</b> <kbd class="macro-args">"<character to use as the pad marker></kbd> +</div> + +<p> +If you need to change mom’s default pad marker (<kbd +class="bold">#</kbd>), either because you want a literal # in +the padded line, or simply because you want to use another character +instead, use PAD_MARKER, whose argument is the new pad marker +character you want. +<br/> +<span class="pre-in-pp"> + .PAD_MARKER @ +</span> +changes the pad marker to <kbd>@</kbd>. +</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]- --> + +<div class="macro-id-overline"> +<h3 id="leader" class="macro-id">Inline escape to add leaders to a line</h3> +</div> + +<div class="box-macro-args"> +Inline: <b>\*[LEADER]</b> +</div> + +<p> +Whenever you want to fill a line or tab with +<a href="definitions.html#leader">leaders</a>, +use the +<a href="definitions.html#inlines">inline escape</a> +<kbd><span class="nobr">\*[LEADER]</span></kbd>. The remainder of the line or +tab will be filled with the leader character. Mom’s default +leader character is a period (dot), but you can change it to any +character you like with +<kbd><a href="#leader-character">LEADER_CHARACTER</a></kbd>. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +<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. +<br/> +<span class="pre"> + .LL 30P + .PAD "Date\*[ST1]#\*[ST1X] Signature\*[ST2]###\*[ST2X]" NOBREAK + .EL + .ST 1 J + .ST 2 J + .TAB 1 + \*[LEADER] + .TN + \*[LEADER] + .TQ +</span> +</p> + +<p class="tip-bottom"> +The PAD 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: +<br/> +<span class="pre" style="margin-bottom: -1em;"> + Date.............Signature..................................... +</span> +</p> +</div> + +<!-- -LEADER_CHARACTER- --> + +<div class="macro-id-overline"> +<h3 id="leader-character" class="macro-id">Change/set the leader character</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>LEADER_CHARACTER</b> <kbd class="macro-args"><character></kbd> +</div> + +<p> +LEADER_CHARACTER takes one argument: a single character you would +like to be used for +<a href="definitions.html#leader">leaders</a>. +(See +<a href="#leader"><kbd><span class="nobr">\*[LEADER]</span></kbd></a> +for an explanation of how to fill lines with leaders.) +</p> + +<p> +For example, to change the leader character from mom’s +default (a period) to the underscore character, enter +<br/> +<span class="pre-in-pp"> + .LEADER_CHARACTER _ +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="tip">Tip:</span> +A particularly useful function of LEADER_CHARACTER is that it can be +used to increase the spacing of mom’s default leaders. This is +done by assigning to LEADER_CHARACTER both the period (dot) and a +space. The technique requires a little low-level groffing: +<br/> +<span class="pre-in-pp"> + .char \[leader] . \" + .LEADER_CHARACTER \[leader] +</span> +The <kbd>.char</kbd> +<a href="definitions.html#primitives">primitive</a> +allows you to define a character called <kbd>leader</kbd>, to which +you assign a period and a space. The <kbd>\"</kbd>, which, in +groff, is used to add non-printing comments to a line, is not +strictly necessary. Its presence here lets you see that +there’s a space after the period. +</p> +</div> + +<!-- -DROPCAP- --> + +<div class="macro-id-overline"> +<h3 id="dropcap" class="macro-id">Drop caps</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DROPCAP</b> <kbd class="macro-args"><dropcap letter> <number of lines to drop> [ COND <percentage> | EXT <percentage> ]</kbd> +</div> + +<p> +The first two arguments to DROPCAP are the letter you want to be the +<a href="definitions.html#dropcap">drop cap</a> +and the number of lines you want it to drop. By default, mom uses +the current family and font for the drop cap. +</p> + +<p> +The optional argument (<kbd>COND</kbd> or <kbd>EXT</kbd>) indicates +that you want the drop cap condensed (narrower) or extended (wider). +If you use <kbd class="bold">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 +(<kbd>%</kbd>) is required. +</p> + +<p> +Mom 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: +<br/> +<span class="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... +</span> +</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> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +When using the +<a href="docprocessing.html#docprocessing">document processing macro</a> +<a href="docelement.html#pp">PP</a>, +DROPCAP only works +</p> +<ul style="margin-top: -1em; margin-bottom: -.5em;"> + <li>with initial paragraphs (i.e. at the start of the document, + or after + <a href="docelement.html#heading">HEADING</a>),</li> + <li>when <kbd>.DROPCAP</kbd> comes immediately after <kbd>.PP</kbd>,</li> + <li>the + <a href="docprocessing.html#printstyle">PRINTSTYLE</a> + is TYPESET.</li> +</ul> +<p> +If these conditions aren’t met, DROPCAP is silently ignored. +</p> + +<p class="tip-bottom" style="margin-top: -1em;"> +<span class="additional-note">Additional note:</span> +If you have dropcaps after +<a href="docelement.html#heading">HEADING</a>s, +you must increase the <kbd>NEEDS</kbd> argument to +<a href="docelement.html#heading-style">HEADING_STYLE</a> +to match the number of dropcap lines. For example, assuming +dropcaps that are three lines tall: +<br/> +<span class="pre-in-pp"> + .HEADING_STYLE 1 NEEDS 3 +</span> +</p> +</div> + +<div class="box-important"> +<p class="tip"> +<span class="important">Warning:</span> +DROPCAP 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 mom does her thing. +</p> +</div> + +<h3 id="dropcap-support" class="docs control-macros-header">Support macros for DROPCAP</h3> +<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> +Mom 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 DROPCAP, namely +</p> +<ul class="no-enumerator" style="margin-top: -.5em; margin-left: -.5em;"> + <li><a href="#dropcap-family">DROPCAP_FAMILY</a></li> + <li><a href="#dropcap-font">DROPCAP_FONT</a></li> + <li><a href="#dropcap-color">DROPCAP_COLOR</a></li> + <li><a href="#dropcap-adjust">DROPCAP_ADJUST</a></li> + <li><a href="#dropcap-gutter">DROPCAP_GUTTER</a></li> +</ul> + +<p style="margin-top: -.5em;"> +These macros must, of course, come before you invoke DROPCAP. +</p> + +<h3 id="dropcap-family" class="control-macro">• DROPCAP_FAMILY</h3> +<p style="margin-left: .66em;"> +Set the drop cap family by giving DROPCAP_FAMILY the name of the +family you want, e.g. +<br/> +<span class="pre-in-pp"> + .DROPCAP_FAMILY H +</span> +which will set the family to Helvetica for the drop cap only. +</p> + +<h3 id="dropcap-font" class="control-macro">• DROPCAP_FONT</h3> +<p style="margin-left: .66em;"> +Set the drop cap font by giving DROPCAP_FONT the name of the font +you want, e.g. +<br/> +<span class="pre-in-pp"> + .DROPCAP_FONT I +</span> +which will set the font to italic for the drop cap only. +</p> + +<h3 id="dropcap-adjust" class="control-macro">• DROPCAP_ADJUST</h3> +<p style="margin-left: .66em;"> +If the size mom calculates for the drop cap isn’t precisely +what you want, you can increase or decrease it with DROPCAP_ADJUST, +like this: e.g. +<br/> +<span class="pre-in-pp"> + .DROPCAP_ADJUST +1 +</span> +or +<br/> +<span class="pre"> + .DROPCAP_ADJUST -.75 +</span> +</p> + +<p style="margin-left: .66em;"> +DROPCAP_ADJUST only understands +<a href="definitions.html#picaspoints">points</a>, +therefore do not append any +<a href="definitions.html#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> + +<h3 id="dropcap-color" class="control-macro">• DROPCAP_COLOR</h3> +<p style="margin-left: .66em;"> +If you’d like your drop cap colourized, simply invoke +<kbd>.DROPCAP_COLOR <color></kbd> 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> + +<h3 id="dropcap-gutter" class="control-macro">• DROPCAP_GUTTER</h3> +<p style="margin-left: .66em;"> +By default, mom puts three points of space between the drop cap +and the text indented beside it. If you want another value, use +DROPCAP_GUTTER (with a unit of measure), like this: +<br/> +<span class="pre-in-pp"> + .DROPCAP_GUTTER 6p +</span> +</p> + +<!-- -\*[SUP]- --> + +<div class="macro-id-overline"> +<h3 id="sup" class="macro-id">Superscript</h3> +</div> + +<div class="box-macro-args"> +Inlines: <kbd>\*[SUP]...\*[SUPX]</kbd> +</div> + +<p> +Superscripts are accomplished +<a href="definitions.html#inlines">inline</a>. +Whenever you need one, typically for numerals, all you need +to do is surround the superscript with the inlines above. +<kbd><span class="nobr">\*[SUP]</span></kbd> begins superscripting; +<kbd><span class="nobr">\*[SUPX]</span></kbd> turns it off. +</p> + +<p id="cond-or-ext-sup"> +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 +<br/> +<kbd><span class="nobr">\*[CONDSUP]...\*[CONDSUPX]</span></kbd> or +<kbd><span class="nobr">\*[EXTSUP]...\*[EXTSUPX]</span></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> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Mom 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. +</p> +</div> + +<h3 id="sup-raise" class="docs">SUPERSCRIPT RAISE AMOUNT</h3> +<p> +By default, mom raises superscripts 1/3 of an +<a href="definitions.html#em">em</a> +above the baseline. If you’re not happy with this default, +you can change it by invoking SUPERSCRIPT_RAISE_AMOUNT with the +amount you want them raised. A +<a href="definitions.html#unitofmeasure">unit of measure</a> +must be appended directly to the amount. Thus, if you want +superscripts raised by 3 +<a href="definitions.html#picaspoints">points</a> +instead of 1/3 em, you’d do +<br/> +<span class="pre-in-pp"> + .SUPERSCRIPT_RAISE_AMOUNT 3p +</span> +and all subsequent superscripts would be raised by 3 points. +</p> + +<!-- -CENTER BLOCK- --> + +<div class="macro-id-overline"> +<h3 id="center-block" class="macro-id">Centre blocks of type</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>CENTER_BLOCK</b> <kbd class="macro-args"><toggle></kbd> +</div> + +<p> +Blocks of type sometimes need to be centred on the page with their quad +direction (left, centre, right) left intact. The +document processing macros +<a href="docelement.html#quote">QUOTE</a> +and +<a href="docelement.html#blockquote">BLOCKQUOTE</a> +take care of this automatically, but there are other situations +where you may want to centre blocks of type. An example might be +left-quadded +<a href="docelement.html#list-intro">nested lists</a>. +</p> + +<p> +Whenever you want to centre a block of type on the page, surround it +with <kbd>.CENTER_BLOCK/.CENTER_BLOCK OFF</kbd> (or <kbd>QUIT</kbd>, +<kbd>X</kbd>, etc). +</p> + +<div class="macro-id-overline"> +<h3 id="left-hang" class="macro-id">Hanging characters</h3> +</div> +<br/> +<div class="box-macro-args"> +Macro: <b>LEFT_HANG</b> <kbd class="macro-args"><character> [ <gutter></kbd> ] +</div> +<p class="requires"> +• left-hung characters +</p> + +<div class="box-macro-args" style="margin-top: 1em"> +Inline: <b>\*[HANG <kbd class="macro-args"><character></kbd>]</b> +</div> +<p class="requires"> +• right-hung characters +</p> + +<p> +Hung characters, frequently punctuation, fall outside the left or +right margin. Their purpose is usually to fine-tune justification. +Consider the following: +</p> + +<table style="margin-left: 3%; margin-right: 6%; text-align: justify"> +<tr> +<td style="padding-right: 1em"> +“Play the man, Master Ridley; we +shall this day light such a candle, +by God's grace, in England, as I +trust shall never be put out.” +</td> +<td> + +</td> +<td style="margin-right: 0; padding-right: 0"> +“ +<br/> +<br/> +<br/> +<br/> +</td> +<td style="margin-left: 0; padding-left: 0"> +Play the man, Master Ridley; we +shall this day light such a candle, +by God's grace, in England, as I +trust shall never be put out.”</td> +</tr> +</table> + +<p> +In the right hand example, the opening double-quote hangs outside +the left margin, creating a uniform left margin for the text. +</p> + +<h4 class="docs">Left hung characters</h4> + +<p> +LEFT_HANG hangs its first argument, the character to be hung, to +the left of the left margin. The optional second argument lets you +specify an amount of space to insert between the hung character and +the text. +</p> + +<p> +Input text after LEFT_HANG must begin with the character to be hung +PLUS a +<a href="inlines.html#inline-horizontal-mom">horizontal motion</a> +corresponding to <kbd><gutter></kbd> if one was given. +If the hung character is a left double-quote, <kbd>\[lq]</kbd> +must be used as the argument to LEFT_HANG and the usual keyboard +double-quote (<kbd>"</kbd>) entered as the input text so as not to +confuse +<a href="goodies.html#smartquotes">SMARTQUOTES</a> +The following example demonstrates: +<br/> +<span class="pre-in-pp"> + .LEFT_HANG \[lq] 1p + "\*[FWD 1p]This line will have its opening double-quote + plus one point of space hung outside the left margin." +</span> +</p> + +<p style="margin-top: -1em"> +Note that what follows LEFT_HANG must be an input line and therefore +it cannot be used to left-hang a +<a href="docelement.html#heading">HEADING</a> +character. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="important">Important:</span> +Versions of mom lower than 2.5_a that included LEFT_HANG required +that the character and its gutter be entered as a single, +concatenated argument, using horizontal motions to establish the +gutter +(e.g. +<a href="inlines.html#inline-horizontal-mom">FWD</a>, +<a href="inlines.html#inline-horizontal-mom">BCK</a>). +Documents created with versions prior to 2.5_a may have to be +updated. +</p> +</div> + +<h4 class="docs">Right hung characters</h4> + +<p> +The <kbd>\*[HANG c]</kbd> inline escape hangs its argument outside +the right margin of justified or quad right copy. The argument may +be a single character, or a single character preceded by a +horizontal motion, effectively establishing a gutter between the +right margin and the hung character: +<br/> +<span class="pre-in-pp" style="margin-bottom: .25em"> + This line will have its closing period hung outside + the right margin with a one point gutter\*[HANG \*[FWD 1p].] +</span> +If the hung character is a right double-quote, <kbd>"\[rq]"</kbd> +must be used as the argument (that is, the <kbd>\[rq]</kbd> +character surrounded by double-quotes). The double-quotes are +required for all special characters of the form +<kbd style="whitespace: nowrap">\[name]</kbd>. +Horizontal motion, if any, must fall inside the double-quotes: +<br/> +<span class="pre-in-pp"> + ...and they all lived happily ever after.\*[HANG "\*[FWD 1p]\[rq]"] +</span> +</p> + +<p> +If the hung character is a hyphen, +<kbd style="whitespace: nowrap"><span class="nobr">\*[HANG -]</span></kbd> +must come at the end of an +<a href="definitions.html#inputline">input line</a>. +This restriction does not apply to other characters, which may come +anywhere in an input line provided that, on output, the line breaks +at the point you introduced the hung character. +</p> + +<p> +For the exceptionally fussy, <kbd>\*[HANG]</kbd> may also be used to +improve visual centring; when text is centred, <kbd +style="whitespace: nowrap">\*[HANG c]</kbd> +hangs the character to the right of the centred line instead of the +margin. +</p> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="inlines.html#top">Next: Inline escapes</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> |