| blob | 83a7ff3b3ebfc43a0b1ce436e4380f8240b2a2e9 |
2 <html>
3 <head>
6 </head>
9 <!====================================================================>
14 <p>
18 </a>
19 <p>
21 The macros in this section are a collection of useful (and sometimes
22 nearly indispensable) routines to simplify typesetting.
23 <p>
26 </a>
28 <ul>
32 <li><a href="#SMARTQUOTES">SMARTQUOTES</a> (convert typewriter doublequotes to proper doublequotes)
35 <br>
37 <ul>
42 </ul>
44 <ul>
47 </ul>
49 <ul>
52 </ul>
54 <ul>
57 <ul>
62 <li><a href="#DROPCAP_GUTTER">DROPCAP_GUTTER</a> (change space between drop cap and running text)
63 </ul>
64 </ul>
66 <ul>
70 </ul>
72 <ul>
79 </ul>
80 </ul>
82 <!---ALIAS--->
86 <br>
89 <p>
91 you can change the name of a macro to anything you like
92 (provided the new name is not already being used by
95 <p>
96 Groff has always been a bit intimidating for new users because
97 its standard macro packages use very terse macro names.
99 them to feel welcome. Consequently, she tries for easy-to-grasp,
101 that people have their own ways of thinking, their own preferences,
102 their own habits. Some of her macro names may not suit you; they
103 might be too long, or aren't what you automatically think of
104 when you want to do a particular thing, or might conflict with habits
105 you've developed over the years.
106 <p>
108 say, PAGEWIDTH, change it, like this:
109 <p>
110 <pre>
111 .ALIAS PW PAGEWIDTH
112 | |
113 new__| |__official
114 name name
115 </pre>
120 either can be used.
121 <p>
123 (dot) that precedes the macro when it's a
125 <p>
127 and always for the same things, consider creating an aliases
128 file of the form
129 <p>
130 <pre>
134 ...etc
135 </pre>
137 Put the file someplace convenient and source it at the
138 beginning of your documents using the groff
141 called mom_aliases in your home directory under a directory
143 <p>
144 <pre>
146 </pre>
148 at the top of your documents.
149 <p>
150 If you share documents that make use of an alias file, remember that
151 other people don't have the file! Paste the whole thing at the top
152 of your documents, please.
153 <p>
156 impunity.
157 <p>
159 <!---SILENT--->
163 <br>
165 <br>
168 <p>
171 from final output. This is most likely to be the case when setting
172 up string tabs (see the
174 for an example), but there are other places where you might want input
175 lines to be invisible as well. Any place you don't want input lines
177 <p>
179 turns it on; any argument turns it off. E.g.,
180 <p>
181 <pre>
182 .SILENT
183 A line of text
184 .SILENT OFF
185 </pre>
188 output copy.
189 <p>
191 If you want to insert non-printing comments into your documents,
192 you may prefer this.
193 <p>
196 (see
198 when you're in one of the
201 or
203 The same applies to tabs
205 or
209 portion of your text disappearing into a black hole.
210 <p>
212 <!---TRAP--->
216 <br>
219 <p>
220 Traps are vertical positions on the output page at which you or
222 something automatically. Commonly, this is near the bottom of
223 the page, where automatic behind-the-scenes processing is needed
224 in order for one page to finish and another to start.
225 <p>
226 Sometimes, traps get sprung when you don't want them. If this
227 happens, surround just the offending macros and input lines with
228 <p>
229 <pre>
230 .TRAP OFF
231 ...
232 .TRAP
233 </pre>
236 turns it off (i.e. suspends the trap), and no argument turns it
237 (back) on.
238 <p>
240 <!---SMARTQUOTES--->
243 <a name="SMARTQUOTES"><h3><u>Convert typewriter doublequotes to proper doublequotes</u></h3></a>
244 <br>
246 <br>
247 or
248 <br>
251 <p>
255 the appropriate instances of true Anglo-American open- and
256 close-doublequotes. (See
258 for how to get SMARTQUOTES to behave correctly for non-English
259 quoting styles.)
260 <p>
261 Typographically, there is a difference between the inch-mark and
262 doublequotes -- a BIG difference. Sadly, typewriters and computer
263 keyboards supply only one: the inch-mark. While using inches for
264 doublequotes is, and always has been, acceptable in typewriter-style
265 copy, it has never been, and, God willing, never will be acceptable in
266 typeset copy. Failure to turn inches into quotes is the first thing
267 a professional typesetter notices in documents prepared by amateurs.
268 And you don't want to look like an amateur, do you?
269 <p>
271 <p>
272 If you invoke <strong>SMARTQUOTES</strong> with one of the optional
273 arguments (<kbd>,,</kbd> or <kbd>>></kbd> or
274 <kbd><<</kbd>) you can use <kbd>"</kbd> as "cheap"
275 open- and close-quotes when inputting text in a language other than
276 English, and have <strong>mom</strong> convert them, on output,
277 into the chosen open- and close-quote style.
278 <p>
279 <kbd>,,</kbd> opens quotes with "lowered doublequotes" and
280 closes them with "raised doublequotes", as in this ascii
281 approximation:
282 <p>
283 <pre>
284 ,,Hilfe !``
285 </pre>
287 <kbd>>></kbd> opens quotes with guillemets pointing to the
288 right, and closes them with guillemets pointing to the left, as in
289 this ascii approximation:
290 <p>
291 <pre>
292 >>Zurück !<<
293 </pre>
295 <kbd><<</kbd> opens quotes with guillemets pointing to the
296 left, and closes them with guillemets pointing to the right, as in
297 this ascii approximation:
298 <p>
299 <pre>
300 <<Mais monsieur! Je ne suis pas ce genre de fille!>>
301 </pre>
303 Please note: the above arguments to <strong>SMARTQUOTES</strong>
304 are literal ASCII characters. <kbd>,,</kbd> is two commas,
305 <kbd><<</kbd> is two less-than signs and <kbd>>></kbd>
306 is two greater-than signs.
307 <p>
308 Alternatively, you can pass <strong>SMARTQUOTES</strong> the
309 two-letter, ISO 639 abbreviation for the language you're writing in,
310 and <strong>mom</strong> will output the correct quotes.
311 <p>
312 <pre>
313 .SMARTQUOTES DA = Danish >>text<<
314 .SMARTQUOTES DE = German ,,text``
315 .SMARTQUOTES ES = Spanish ``text´´
316 .SMARTQUOTES FR = French << text >>
317 .SMARTQUOTES IT = Italian << text >>
318 .SMARTQUOTES NL = Dutch ´´text´´
319 .SMARTQUOTES NO = Norwegian <<text>>
320 .SMARTQUOTES PT = Portuguese <<text>>
321 .SMARTQUOTES SV = Swedish >>text>>
322 </pre>
323 <p>
324 Turn <strong>SMARTQUOTES</strong> off by passing it any argument
325 <em>not</em> in the argument list (e.g. <strong>OFF</strong>,
326 <strong>QUIT</strong>, <strong>X</strong>, etc.)
327 <p>
328 If you're using the
330 with
332 <strong>SMARTQUOTES</strong> is on by default (in the Anglo-American
333 style); with
335 it's off by default (and should probably stay that way).
336 <p>
337 Finally, if you're fussy about the kerning of quote marks in
338 relation to the text they surround, or have special quoting needs,
339 you have to enter quote marks by hand using groff's native
341 for special characters (see man groff_char for a complete list of
342 special characters). Entering quote marks this way allows you to
343 use <strong>mom</strong>'s
345 to fine-tune the look of quotes.
346 <p>
347 <strong>NOTE:</strong> <strong>SMARTQUOTES</strong> does not work on
348 single quotes, which most people input with the apostrophe (found at
349 the right-hand end of the "home row" on a QWERTY keyboard).
350 Groff will interpret all instances of the apostrophe as an apostrophe,
351 making the symbol useless as an open-single-quote. For open single
352 quotes, input the backtick character typically found under the tilde
353 on most keyboards. (Pour nous autres, "backtick" veut dire
354 l'accent grave.)
355 Here's an example of correct input copy with single quotes:
356 <p>
357 <pre>
359 </pre>
361 <strong>ADDITIONAL NOTE:</strong> Whether or not you have
362 <strong>SMARTQUOTES</strong> turned on, get into the habit of entering
363 the foot- and inch-marks, when you need them, with the
365 <strong>\*[FOOT]</strong> and <strong>\*[INCH]</strong>, instead
367 <p>
369 <!---CAPS--->
373 <br>
376 <p>
378 case. Primarily, it's a support macro used by the
381 is a toggle, therefore no argument turns it on, any argument
382 turns it off.
383 <p>
384 <pre>
385 .CAPS
386 All work and no play makes Jack a dull boy.
387 .CAPS OFF
388 </pre>
390 produces, on output
391 <p>
392 <pre>
393 ALL WORK AND NO PLAY MAKES JACK A DULL BOY.
394 </pre>
396 <!---STRING--->
400 <br>
403 <p>
404 You may find sometimes that you have to type out portions of text
405 repeatedly. If you'd like not to wear out your fingers, you can
407 outputs whatever you put into it.
408 <p>
409 For example, say you're creating a document that repeatedly uses
411 typing all that out every time, you could define a string, like
412 this:
413 <p>
414 <pre>
415 .STRING mw the Montreal/Windsor corridor
416 </pre>
418 Once a string is defined, you can call it any time with the
421 <p>
422 <pre>
423 The schedule for trains along \*[mw]:
424 </pre>
426 produces, on output
427 <p>
428 <pre>
429 The schedule for trains along the Montreal/Windsor corridor:
430 </pre>
433 ends of strings you're defining, unless you want them. Everything
435 into the string, including trailing spaces.
436 <p>
438 You can use either, or mix 'n' match with impunity.
439 <p>
441 <!---UNDERSCORE--->
445 <br>
446 <nobr>Macro: <strong>UNDERSCORE</strong> [ <distance below baseline> ] "<string>"<wbr>
447 <br>
448 <em>*Optional argument requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em>
450 <p>
452 beneath the required
454 The string must be enclosed in double-quotes, like this:
455 <p>
456 <pre>
457 .UNDERSCORE "Unmonitored monopolies breed high prices and poor products."
458 </pre>
460 If you wish to change the distance of the rule from the
463 <p>
464 <pre>
466 </pre>
468 The above places the underscore 3 points below the baseline.
469 <p>
472 <br>
474 copy, which is to say that you can't underscore a multi-line passage
475 simply by putting the text of the whole thing in the string you pass
478 or portion of an output line you want underscored must be plugged
480 that underscoring should at best be an occasional effect in typeset
481 copy. If you want to emphasize an entire passage, it's much, much
482 better to change fonts (e.g. to italic or bold).
483 <p>
484 You can easily and successfully underline entire passages in simulated
485 typewriter-style copy (i.e. if your font is Courier, or you're using
486 the document processing macro
488 with the
491 purpose, but works only with the Courier font.
492 <p>
494 of the underscore precisely right in
496 copy, although she's fine with all the other
498 as well as with the no-fill modes. As of this writing, I have
499 no solution to the occasional problems with justified copy.
500 <p>
504 to preview files anyway. See the section on
506 <p>
508 <!---UNDERSCORE2--->
512 <br>
513 <nobr>Macro: <strong>UNDERSCORE2</strong> [ <distance below baseline> [ <distance between rules> ] ] "<string>"<wbr>
514 <br>
515 <em>*Optional arguments require a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em>
517 <p>
519 2 points beneath the required
521 The string must be enclosed in double-quotes, like this:
522 <p>
523 <pre>
524 .UNDERSCORE2 "Unmonitored monopolies breed high prices and poor products."
525 </pre>
527 The default distance between the two rules is 2 points.
528 <p>
529 If you wish to change the distance of the double underscore from
532 <p>
533 <pre>
535 </pre>
537 which places the double underscore 3 points below the baseline.
538 <p>
539 If you wish to change the distance between the two rules as
542 give a value for the first optional argument if you want to use
543 the second.
544 <p>
550 <p>
552 <!---UNDERLINE--->
556 <br>
559 <p>
560 If your font is Courier, or you're using the document processing macro
563 passages that, in typeset copy, would be italicized. You invoke
565 by itself (i.e. with no argument) to initiate underlining, and
566 with any argument to turn underlining off.
567 <p>
569 and numbers, but not punctuation or spaces. This makes for more
570 readable copy than a solid underline.
571 <p>
574 with the escapes
576 <p>
578 <!---UL--->
582 <br>
585 <p>
586 If your font is Courier, or you're using the document processing macro
589 passages that, in typeset copy, would be italicized.
590 <p>
592 following it, but not punctuation or spaces. This makes for more
593 readable copy than a solid underline. When you no longer want
595 <p>
596 The macro
599 identical, hence
600 <p>
601 <pre>
602 .FAM C
603 .FT R
604 .PT_SIZE 12
605 .LS 24
606 .SS 0
607 .QUAD LEFT
608 Which should I heed?
609 .UNDERLINE
610 Just do it
611 .UNDERLINE OFF
612 or
613 .UNDERLINE
614 just say no?
615 .UNDERLINE OFF
616 </pre>
618 produces the same result as
619 <p>
620 <pre>
621 .FAM C
622 .FT R
623 .PT_SIZE 12
624 .LS 24
625 .SS 0
626 .QUAD LEFT
627 Which should I heed? \*[UL]Just do it\*[ULX] or \*[UL]just say no?\*[ULX]
628 </pre>
630 <!---PAD--->
634 <br>
635 <nobr>Macro: <strong>PAD</strong> "<string with pad markers inserted>" [NOBREAK]<wbr>
637 <p>
642 <p>
644 text on the line and the distance remaining to its end, then inserts
645 the difference (as whitespace) at the place(s) you specify.
646 <p>
647 Take, for example, the following relatively common typesetting
648 situation, found at the bottom of legal agreements:
649 <p>
650 <pre>
651 Date Signature |
652 </pre>
654 The person signing the agreement is supposed to fill in the date
655 as well as a signature. Space needs to be left for both, but
656 the exact amount is neither known, nor important. All that
657 matters is that there be a little space after Date, and rather
658 more space after Signature. (In the above, | represents
659 the end of the line at the prevailing line length.)
660 <p>
661 The
663 (see below) is # (the pound or number sign on your keyboard) and
664 can be used multiple times in a line. With that in mind, here's how
665 you'd input the Date/Signature line (assuming a length of 30 picas):
666 <p>
667 <pre>
668 .LL 30P
669 .PAD "Date#Signature###"
670 </pre>
672 When the line is output, the space remaining on the line, after
674 account, is split into four (because there are four # signs).
675 One quarter of the space is inserted between Date and Signature,
676 the remainder is inserted after Signature.
678 <p>
679 One rarely wants merely to insert space in a line; one usually
681 particularly useful in conjunction with
683 The following uses the Date/Signature example above, but adds
684 rules into the whitespace through the use of string tabs and
689 groff's line drawing function,
691 could be used.)
692 <p>
693 <pre>
694 .LL 30P
695 .PAD "Date \*[ST1]#\*[ST1X] Signature \*[ST2]###\*[ST2X]" NOBREAK
696 .ST 1 J
697 .ST 2 J
698 .TAB 1
699 \*[RULE]
700 .TN
701 \*[RULE]
702 .TQ
703 </pre>
705 If you're not a typesetter, and if you're new to groff, the
706 example probably looks like gibberish. My apologies. However,
707 remember that typesetting is a craft, and without having studied
708 the craft, it takes a while to grasp its concepts.
709 <p>
710 Basically, what the example does is:
711 <br>
712 <ol>
713 <li>Pads the Date/Signature line (using the pad marker #),
714 encloses the padded space with two string tabs markers,
715 and outputs the line.
716 <br>
717 <li>Sets the two string tabs (notice the use of
720 to advance a line at this point).
721 <br>
722 <li>Calls the first string tab and draws a rule to its full
723 length.
724 <br>
725 <li>Calls the second tab with
727 (which moves to tab 2 and stays on the same baseline)
728 then draws a rule to the full length of string tab 2.
729 </ol>
730 <br>
731 Often, when setting up string tabs this way, you don't want the
732 padded line to print immediately. To accomplish this, use
735 for an example.
736 <p>
738 marker, you can't use it as a literal part of the pad string. If you
739 need the sign to appear in the text of a padded line, change the pad
742 macro; at all other times it prints literally, just as you'd expect.
743 <p>
745 because the string must be enclosed in double-quotes, you can't use the
746 double-quote (") as part of the string. The way to circumvent
747 this is to use the groff
750 rightquote respectively) whenever double-quotes are required in the
752 <p>
754 <!---PAD_MARKER--->
758 <br>
761 <p>
763 (#), either because you want a literal # in the padded line,
764 or simply because you want to use another character instead, use
766 character you want.
767 <p>
768 <pre>
769 .PAD_MARKER @
770 </pre>
772 changes the pad marker to @.
773 <p>
774 Once you've changed the pad marker, the new marker remains in
775 effect for every instance of
777 until you change it again (say, back to the pound sign).
778 <p>
780 <!---\*[LEADER]--->
784 <br>
787 <p>
788 Whenever you want to fill a line or tab with
790 use the
794 default leader character is a period (dot), but you can change
795 it to any character you like with
797 <p>
799 or tabs right to their end. You cannot insert leaders into a
800 line or tab and have text following the leader on the same line
801 or in the same tab. Should you wish to achieve such an effect
802 typographically, create tabs for each element of the line and
803 fill them appropriately with the text and leaders you need.
805 example follows.
806 <p>
807 <pre>
808 .LL 30P
809 .PAD "Date\*[ST1]#\*[ST1X]Signature\*[ST2]###\*[ST2X]"
810 .EL
811 .ST 1 J
812 .ST 2 J
813 .TAB 1
814 \*[LEADER]
815 .TN
816 \*[LEADER]
817 .TQ
818 </pre>
821 and marks string tabs around the pad space inserted in the line.
823 with leaders. The result looks like this:
824 <p>
825 <pre>
826 Date.............Signature.....................................
827 </pre>
829 <!---LEADER_CHARACTER--->
833 <br>
836 <p>
838 character you would like to be used for
840 (See
842 fill lines with leaders.)
843 <p>
845 default (a period) to the underscore character, enter
846 <p>
847 <pre>
848 .LEADER_CHARACTER _
849 </pre>
851 <!---DROPCAP--->
855 <br>
856 <nobr>Macro: <strong>DROPCAP</strong> <dropcap letter> <number of lines to drop> [ COND <percentage> | EXT <percentage> ]<wbr>
858 <p>
860 want to be the
862 and the number of lines you want it to drop. By default,
864 <p>
865 The optional argument (COND or EXT) indicates that you want the
866 drop cap condensed (narrower) or extended (wider). If you use
868 argument with the percentage of the letter's normal width you want
869 it condensed or extended. No percent sign (%) is required.
870 <p>
872 line up with the first line of text indented beside it, then set
873 the correct number of indented lines, and restore your left margin
874 when the number of drop cap lines has been reached.
875 <p>
877 like this:
878 <p>
879 <pre>
881 he thousand injuries of Fortunato I had borne as best I
882 could, but when he ventured upon insult, I vowed revenge.
883 You who so well know the nature of my soul will not suppose,
884 however, that I gave utterance to a threat...
885 </pre>
887 The drop cap, slightly condensed but in the current family and font,
888 will be three lines tall, with whatever text fills those three
889 lines indented to the right of the letter. The remainder of the
890 paragraph's text will revert to the left margin.
891 <p>
896 <br>
897 <ul>
898 <li>with initial paragraphs (i.e. at the start of the document,
899 or after
902 <li>and when the
904 is TYPESET.
905 </ul>
906 <br>
908 <p>
910 a strain on resource-challenged systems. If you have such a
911 system and use drop caps extensively in a document, be prepared
915 Drop caps are the bane of most typesetters' existence. It's
916 very difficult to get the size of the drop cap right for the
917 number of drop lines, especially if the drop cap is in a
918 different family from the prevailing family of running text.
919 Not only that, but there's the gutter around the drop cap to
920 take into account, plus the fact that the letter may be too wide
921 or too narrow to look anything but odd or misplaced.
922 <p>
925 rest she solves with macros that change the default behaviour of
927 <p>
929 <br>
931 <br>
933 <br>
935 <br>
936 and
937 <br>
939 <p>
940 These macros must, of course, come before you invoke
945 Set the drop cap family by giving
947 e.g.
948 <p>
949 <pre>
950 .DROPCAP_FAMILY H
951 </pre>
953 which will set the family to Helvetica for the drop cap only.
957 Set the drop cap font by giving
959 e.g.
960 <p>
961 <pre>
962 .DROPCAP_FONT I
963 </pre>
965 which will set the font to italic for the drop cap only.
970 isn't precisely what you want, you can increase or decrease it
972 e.g.
973 <p>
974 <pre>
975 .DROPCAP_ADJUST +1
976 or
977 .DROPCAP_ADJUST -.75
978 </pre>
982 therefore do not append any
984 to the argument. And always be sure to prepend the plus or
985 minus sign, depending on whether you want the drop cap larger or
986 smaller.
991 If you'd like your drop cap colourized, simply invoke
995 or
997 colourized; all other text will remain at the current colour
998 default (usually black).
1003 between the drop cap and the text indented beside it. If you
1005 unit of measure), like this:
1006 <p>
1007 <pre>
1008 .DROPCAP_GUTTER 6p
1009 </pre>
1011 <!---\*[SUP]--->
1015 <br>
1018 <p>
1019 Superscripts are accomplished
1021 Whenever you need one, typically for numerals, all you need to
1022 do is surround the superscript with the inlines above.
1027 <p>
1028 If your running type is
1030 or
1032 and you want your superscripts to be equivalently pseudo-condensed or
1035 <p>
1036 The superscript inlines are primarily used by the
1038 for automatic generation of numbered footnotes. However, you may
1039 find them useful for other purposes.
1040 <p>
1042 making superscripts look good in any font and at any size. If you're
1043 fussy, though (and I am), about precise vertical placement, kerning,
1044 weight, size, and so on, you may want to roll your own solution.
1046 I'm neither a mathematician nor a chemist, so I don't need them.
1047 Of course, anyone who wishes to contribute a subscript routine to
1049 lifetime, but in all lifetimes to come.
1050 <p>
1051 <hr>
1056 </body>
1057 </html>