| blob | 1e8551cbf99850c445d64c78ab7e9b25ec58f09c |
1 <html>
2 <head>
5 </head>
8 <!====================================================================>
17 </a>
20 The macros in this section are a collection of useful (and sometimes
21 nearly indispensible) routines to simplify typesetting.
25 </a>
27 <ul>
33 <br>
35 <ul>
40 </ul>
42 <ul>
45 </ul>
47 <ul>
50 </ul>
52 <ul>
55 <ul>
59 <li><a href="#DROPCAP_GUTTER">DROPCAP_GUTTER</a> (change space between drop cap and running text)
60 </ul>
61 </ul>
63 <ul>
67 </ul>
68 </ul>
70 <!---ALIAS--->
74 <br>
77 <p>
79 you can change the name of a macro to anything you like
80 (provided the new name is not already being used by
83 <p>
84 Groff has always been a bit intimidating for new users because
85 its standard macro packages use very terse macro names.
87 them to feel welcome. Consequently, she tries for easy-to-grasp,
89 that people have their own ways of thinking, their own preferences,
90 their own habits. Some of her macro names may not suit you; they
91 might be too long, or aren't what you automatically think of
92 when you want to do a particular thing, or might conflict with habits
93 you've developed over the years.
94 <p>
96 say, PAGEWIDTH, change it, like this:
97 <p>
98 <pre>
99 .ALIAS PW PAGEWIDTH
100 | |
101 new__| |__official
102 name name
103 </pre>
108 either can be used.
109 <p>
111 (dot) that precedes the macro when it's a
113 <p>
115 and always for the same things, consider creating an aliases
116 file of the form
117 <p>
118 <pre>
122 ...etc
123 </pre>
125 Put the file someplace convenient and source it at the
126 beginning of your documents using the groff
129 called mom_aliases in your home directory under a directory
131 <p>
132 <pre>
134 </pre>
136 at the top of your documents.
137 <p>
138 If you share documents that make use of an alias file, remember that
139 other people don't have the file! Paste the whole thing at the top
140 of your documents, please.
141 <p>
144 impunity.
145 <br>
147 <!---SILENT--->
151 <br>
153 <br>
156 <p>
159 from final output. This is most likely to be the case when setting
160 up string tabs (see the
162 for an example), but there are other places where you might want input
163 lines to be invisible as well. Any place you don't want input lines
165 <p>
167 turns it on; any argument turns it off. E.g.,
168 <p>
169 <pre>
170 .SILENT
171 A line of text
172 .SILENT OFF
173 </pre>
176 output copy.
177 <p>
179 If you want to insert non-printing comments into your documents,
180 you may prefer this.
181 <p>
184 (see
186 when you're in one of the
189 or
191 The same applies to tabs
193 or
197 portion of your text disappearing into a black hole.
198 <br>
200 <!---TRAP--->
204 <br>
207 <p>
208 Traps are vertical positions on the output page at which you or
210 something automatically. Commonly, this is near the bottom of
211 the page, where automatic behind-the-scenes processing is needed
212 in order for one page to finish and another to start.
213 <p>
214 Sometimes, traps get sprung when you don't want them, notably
215 when using the
217 and
219 macros. If this happens, surround just the offending macros and
220 input lines with
221 <p>
222 <pre>
223 .TRAP OFF
224 ...
225 .TRAP
226 </pre>
229 turns it off (i.e. suspends the trap), and no argument turns it
230 (back) on.
231 <p>
235 <br>
237 <!---SMARTQUOTES--->
241 <br>
244 <p>
247 into the appropriate instances of true open- and close-doublequotes.
248 <p>
249 Typographically, there is a difference between the inch-mark and
250 doublequotes -- a BIG difference. Sadly, typewriters and computer
251 keyboards supply only one: the inch-mark. While using inches for
252 doublequotes is, and always has been, acceptable in typewriter-style
253 copy, it has never been, and, God willing, never will be acceptable in
254 typeset copy. Failure to turn inches into quotes is the first thing
255 a professional typesetter notices in documents prepared by amateurs.
256 And you don't want to look like an amateur, do you?
257 <p>
258 When preparing documents for typesetting, by all means, use the
259 inch-mark. Just make sure to turn <strong>SMARTQUOTES</strong>
260 on. <strong>SMARTQUOTES</strong> is a toggle, so invoking it with
261 no argument turns it on, and invoking it with any argument at all
262 turns it off.
263 <p>
264 If you're using the
266 with
268 <strong>SMARTQUOTES</strong> is on by default; with
270 it's off by default (and should probably stay that way).
271 <p>
272 <strong>NOTE:</strong> <strong>SMARTQUOTES</strong> does not work on
273 single quotes, which most people input with the apostrophe (found at
274 the right-hand end of the "home row" on a QWERTY keyboard).
275 Groff will interpret all instances of the apostrophe as an apostrophe,
276 making the symbol useless as an open-single-quote. For open single
277 quotes, input the backtick character typically found under the tilde
278 on most keyboards. (Pour nous autres, "backtick" veut dire
279 l'accent grave.)
280 Here's an example of correct input copy with single quotes:
281 <p>
282 <pre>
284 </pre>
286 <strong>ADDITIONAL NOTE:</strong> Whether or not you have
287 <strong>SMARTQUOTES</strong> turned on, get into the habit of entering
288 the foot- and inch-marks, when you need them, with the
290 <strong>\*[FOOT]</strong> and <strong>\*[INCH]</strong>, instead
292 <br>
294 <!---CAPS--->
298 <br>
301 <p>
303 case. Primarily, it's a support macro used by the
306 is a toggle, therefore no argument turns it on, any argument
307 turns it off.
308 <p>
309 <pre>
310 .CAPS
311 All work and no play makes Jack a dull boy.
312 .CAPS OFF
313 </pre>
315 produces, on output
316 <p>
317 <pre>
318 ALL WORK AND NO PLAY MAKES JACK A DULL BOY.
319 </pre>
321 <!---UNDERSCORE--->
325 <br>
326 Macro: <strong>UNDERSCORE</strong> <var>[ <distance below baseline> ] "<string>"</var>
327 <br>
328 <em>*Optional argument requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em>
330 <p>
332 beneath the required
334 The string must be enclosed in double-quotes, like this:
335 <p>
336 <pre>
337 .UNDERSCORE "Unmonitored monopolies breed high prices and poor products."
338 </pre>
340 If you wish to change the distance of the rule from the
343 <p>
344 <pre>
346 </pre>
348 The above places the underscore 3 points below the baseline.
349 <p>
352 <br>
354 copy, which is to say that you can't underscore a multi-line passage
355 simply by putting the text of the whole thing in the string you pass
358 or portion of an output line you want underscored must be plugged
360 that underscoring should at best be an occasional effect in typeset
361 copy. If you want to emphasize an entire passage, it's much, much
362 better to change fonts (e.g. to italic or bold).
363 <p>
364 You can easily and successfully underline entire passages in simulated
365 typewriter-style copy (i.e. if your font is Courier, or you're using
366 the document processing macro
368 with the
371 purpose, but works only with the Courier font.
372 <p>
374 of the underscore precisely right in
376 copy, although she's fine with all the other
378 as well as with the no-fill modes. As of this writing, I have
379 no solution to the occasional problems with justified copy.
380 <p>
384 to preview files anyway. See the section on
386 <br>
388 <!---UNDERSCORE2--->
392 <br>
393 Macro: <strong>UNDERSCORE2</strong> <var>[ <distance below baseline> [ <distance between rules> ] ] "<string>"</var>
394 <br>
395 <em>*Optional arguments require a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em>
397 <p>
399 2 points beneath the required
401 The string must be enclosed in double-quotes, like this:
402 <p>
403 <pre>
404 .UNDERSCORE2 "Unmonitored monopolies breed high prices and poor products."
405 </pre>
407 The default distance between the two rules is 2 points.
408 <p>
409 If you wish to change the distance of the double underscore from
412 <p>
413 <pre>
415 </pre>
417 which places the double underscore 3 points below the baseline.
418 <p>
419 If you wish to change the distance between the two rules as
422 give a value for the first optional argument if you want to use
423 the second.
424 <p>
430 <br>
432 <!---UNDERLINE--->
436 <br>
439 <p>
440 If your font is Courier, or you're using the document processing macro
443 passages that, in typeset copy, would be italicised. You invoke
445 by itself (i.e. with no argument) to initiate underlining, and
446 with any argument to turn underlining off.
447 <p>
449 and numbers, but not punctuation or spaces. This makes for more
450 readable copy than a solid underline.
451 <p>
454 with the escapes
456 <br>
458 <!---UL--->
462 <br>
465 <p>
466 If your font is Courier, or you're using the document processing macro
469 passages that, in typeset copy, would be italicised.
470 <p>
472 following it, but not punctuation or spaces. This makes for more
473 readable copy than a solid underline. When you no longer want
475 <p>
476 The macro
479 identical, hence
480 <p>
481 <pre>
482 .FAM C
483 .FT R
484 .PS 12
485 .LS 24
486 .SS 0
487 .QUAD LEFT
488 Which should I heed?
489 .UNDERLINE
490 Just do it
491 .UNDERLINE OFF
492 or
493 .UNDERLINE
494 just say no?
495 .UNDERLINE OFF
496 </pre>
498 produces the same result as
499 <p>
500 <pre>
501 .FAM C
502 .FT R
503 .PS 12
504 .LS 24
505 .SS 0
506 .QUAD LEFT
507 Which should I heed? \*[UL]Just do it\*[ULX] or \*[UL]just say no?\*[ULX]
508 </pre>
510 <!---PAD--->
514 <br>
517 <p>
519 whitespace into a line.
520 <p>
522 text on the line and the distance remaining to its end, then inserts
523 the difference (as whitespace) at the place(s) you specify.
524 <p>
525 Take, for example, the following relatively common typesetting
526 situation, found at the bottom of legal agreements:
527 <p>
528 <pre>
529 Date Signature |
530 </pre>
532 The person signing the agreement is supposed to fill in the date
533 as well as a signature. Space needs to be left for both, but
534 the exact amount is neither known, nor important. All that
535 matters is that there be a little space after Date, and rather
536 more space after Signature. (In the above, | represents
537 the end of the line at the prevailing line length.)
538 <p>
539 The
541 (see below) is # (the pound or number sign on your keyboard) and
542 can be used multiple times in a line. With that in mind, here's how
543 you'd input the Date/Signature line (assuming a length of 30 picas):
544 <p>
545 <pre>
546 .LL 30P
547 .PAD "Date#Signature###"
548 </pre>
550 When the line is output, the space remaining on the line, after
552 account, is split into four (because there are four # signs).
553 One quarter of the space is inserted between Date and Signature,
554 the remainder is inserted after Signature.
555 <p>
556 One rarely wants merely to insert space in a line; one usually
558 particularly useful in conjunction with
560 The following uses the Date/Signature example above, but adds
561 rules into the whitespace through the use of string tabs and
562 groff's line drawing function,
564 <p>
565 <pre>
566 .LL 30P
567 .PAD "Date\*[ST1]#\*[ST1X]Signature\*[ST2]###\*[ST2X]"
568 .EL
569 .ST 1 J
570 .ST 2 J
571 .TAB 1
572 \l'\n(.lu'
573 .TN
574 \l'\n(.lu'
575 .TQ
576 </pre>
578 If you're not a typesetter, and if you're new to groff, the
579 example probably looks like gibberish. My apologies. However,
580 remember that typesetting is a craft, and without having studied
581 the craft, it takes a while to grasp its concepts. Also,
583 consistent-looking, comprehensible alternatives to groff's
584 native
588 <p>
589 Basically, what the example does is:
590 <br>
591 <ol>
592 <li>Pads the Date/Signature line (using the pad marker #),
593 encloses the padded space with two string tabs markers,
594 and outputs the line
595 <br>
596 <li>Sets the two string tabs (notice the use of
599 to advance a line at this point)
600 <br>
601 <li>Calls the first string tab and draws a rule to its full
602 length
603 <br>
604 <li>Calls the second tab with
606 (which moves to tab 2 and stays on the same baseline)
607 then draws a rule to the full length of string tab 2
608 </ol>
609 <br>
610 Often, when setting up string tabs this way, you don't want the
611 padded line to print immediately. To accomplish this, use
614 for an example.
615 <p>
617 marker, you can't use it as a literal part of the pad string. If you
618 need the sign to appear in the text of a padded line, change the pad
621 macro; at all other times it prints literally, just as you'd expect.
622 <p>
624 because the string must be enclosed in double-quotes, you can't use the
625 double-quote (") as part of the string. The way to circumvent
626 this is to use the groff
629 rightquote respectively) whenever double-quotes are required in the
631 <br>
633 <!---PAD_MARKER--->
637 <br>
640 <p>
642 (#), either because you want a literal # in the padded line,
643 or simply because you want to use another character instead, use
645 character you want.
646 <p>
647 <pre>
648 .PAD_MARKER @
649 </pre>
651 changes the pad marker to @.
652 <p>
653 Once you've changed the pad marker, the new marker remains in
654 effect for every instance of
656 until you change it again (say, back to the pound sign).
657 <br>
659 <!---\*[LEADER]--->
663 <br>
666 <p>
667 Whenever you want to fill a line or tab with
669 use the
673 default leader character is a period (dot), but you can change
674 it to any character you like with
676 <p>
678 or tabs right to their end. You cannot insert leaders into a
679 line or tab and have text following the leader on the same line
680 or in the same tab. Should you wish to achieve such an effect
681 typographically, create tabs for each element of the line and
682 fill them appropriately with the text and leaders you need.
684 example follows.
685 <p>
686 <pre>
687 .LL 30P
688 .PAD "Date\*[ST1]#\*[ST1X]Signature\*[ST2]###\*[ST2X]"
689 .EL
690 .ST 1 J
691 .ST 2 J
692 .TAB 1
693 \*[LEADER]
694 .TN
695 \*[LEADER]
696 .TQ
697 </pre>
700 and marks string tabs around the pad space inserted in the line.
702 with leaders. The result looks like this:
703 <p>
704 <pre>
705 Date.............Signature.....................................
706 </pre>
708 <!---LEADER_CHARACTER--->
712 <br>
715 <p>
717 character you would like to be used for
719 (See
721 fill lines with leaders.)
722 <p>
724 default (a period) to the underscore character, enter
725 <p>
726 <pre>
727 .LEADER_CHARACTER _
728 </pre>
730 <!---DROPCAP--->
734 <br>
735 Macro: <strong>DROPCAP</strong> <var><dropcap letter> <number of lines to drop> [ COND <percentage> | EXT <percentage> ]</var>
737 <p>
739 want to be the
741 and the number of lines you want it to drop. By default,
743 <p>
744 The optional argument (COND or EXT) indicates that you want the
745 drop cap condensed (narrower) or extended (wider). If you use
747 argument with the percentage of the letter's normal width you want
748 it condensed or extended. No percent sign (%) is required.
749 <p>
751 line up with the first line of text indented beside it, then set
752 the correct number of indented lines, and restore your left margin
753 when the number of drop cap lines has been reached.
754 <p>
756 like this:
757 <p>
758 <pre>
760 he thousand injuries of Fortunato I had borne as best I
761 could, but when he ventured upon insult, I vowed revenge.
762 You who so well know the nature of my soul will not suppose,
763 however, that I gave utterance to a threat...
764 </pre>
766 The drop cap, slightly condensed but in the current family and font,
767 will be three lines tall, with whatever text fills those three
768 lines indented to the right of the letter. The remainder of the
769 paragraph's text will revert to the left margin.
770 <p>
775 <br>
776 <ul>
777 <li>with initial paragraphs (i.e. at the start of the document,
778 or after
781 <li>and when the
783 is TYPESET.
784 </ul>
785 <br>
787 <p>
789 a strain on resource-challenged systems. If you have such a
790 system and use drop caps extensively in a document, be prepared
794 Drop caps are the bane of most typesetters' existence. It's
795 very difficult to get the size of the drop cap right for the
796 number of drop lines, especially if the drop cap is in a
797 different family from the prevailing family of running text.
798 Not only that, but there's the gutter around the drop cap to
799 take into account, plus the fact that the letter may be too wide
800 or too narrow to look anything but odd or misplaced.
801 <p>
804 rest she solves with macros that change the default behaviour of
806 <p>
808 <br>
810 <br>
812 <br>
813 and
814 <br>
816 <p>
817 These macros must, of course, come before you invoke
822 Set the drop cap family by giving
824 e.g.
825 <p>
826 <pre>
827 .DROPCAP_FAMILY H
828 </pre>
830 which will set the family to Helvetica for the drop cap only.
834 Set the drop cap font by giving
836 e.g.
837 <p>
838 <pre>
839 .DROPCAP_FONT I
840 </pre>
842 which will set the font to italic for the drop cap only.
847 isn't precisely what you want, you can increase or decrease it
849 e.g.
850 <p>
851 <pre>
852 .DROPCAP_ADJUST +1
853 or
854 .DROPCAP_ADJUST -.75
855 </pre>
859 therefore do not append any
861 to the argument. And always be sure to preprend the plus or
862 minus sign, depending on whether you want the drop cap larger or
863 smaller.
868 between the drop cap and the text indented beside it. If you
870 unit of measure), like this:
871 <p>
872 <pre>
873 .DROPCAP_GUTTER 6p
874 </pre>
876 <!---\*[SUP]--->
880 <br>
883 <p>
884 Superscripts are accomplished
886 Whenever you need one, typically for numerals, all you need to
887 do is surround the superscript with the inlines above.
892 <p>
893 If your running type is
895 or
897 and you want your superscripts to be equivalently pseudo-condensed or
900 <p>
901 The superscript inlines are primarily used by the
903 for automatic generation of numbered footnotes. However, you may
904 find them useful for other purposes.
905 <p>
907 making superscripts look good in any font and at any size. If you're
908 fussy, though (and I am), about precise vertical placement, kerning,
909 weight, size, and so on, you may want to roll your own solution.
911 I'm neither a mathematician nor a chemist, so I don't need them.
912 Of course, anyone who wishes to contribute a subscript routine to
914 lifetime, but in all lifetimes to come.
916 <p>
917 <hr>
922 </body>
923 </html>