1GROFF_MOM(7)           Miscellaneous Information Manual           GROFF_MOM(7)
2
3
4

NAME

6       groff_mom  -  groff  “mom”  macros; “mom” is a “roff” language, part of
7       “groff”
8

SYNOPSIS

10       pdfmom [-Tps [pdfroff-option ...]] [groff-option ...] file ...
11
12       groff -mom [option ...] file ...
13       groff -m mom [option ...] file ...
14

CALLING MOM

16       mom is a macro set for groff, designed primarily  to  format  documents
17       for PDF and PostScript output.
18
19       mom  provides  two  categories  of  macros: macros for typesetting, and
20       macros for document processing.  The typesetting macros provide  access
21       to  groff's typesetting capabilities in ways that are simpler to master
22       than groff's primitives.  The document processing macros provide highly
23       customizable  markup tags that allow the user to design and output pro‐
24       fessional-looking documents with a minimum of typesetting intervention.
25
26       Files processed with pdfmom(1) with or without the -Tps option, produce
27       PDF documents.  The documents include a PDF outline that appears in the
28       ‘Contents’ panel of document viewers, and may contain clickable  inter‐
29       nal and external links.
30
31       When -Tps is absent, groff's native PDF driver, gropdf, is used to gen‐
32       erate the output.  When given, the output is still PDF, but  processing
33       is passed over to pdfroff, which uses groff's PostScript driver, grops.
34       Not all PDF features are available when -Tps is given; its primary  use
35       is to allow processing of files with embedded PostScript images.
36
37       Files  processed  with groff -mom (or -m mom) produce PostScript output
38       by default.
39
40       mom comes with her own very complete documentation in HTML  format.   A
41       separate PDF manual, Producing PDFs with groff and mom, covers full mom
42       or PDF usage.
43

FILES

45       /usr/share/groff/1.22.4/tmac/om.tmac
46              – the main macro file
47       /usr/share/groff/1.22.4/tmac/mom.tmac
48              – a wrapper file that calls om.tmac directly.
49
50       /usr/share/doc/groff/html/mom/toc.html
51              – entry point to the HTML documentation
52
53       /usr/share/doc/groff/pdf/mom-pdf.pdf
54              – the PDF manual, Producing PDFs with groff and mom
55
56       /usr/share/doc/groff/examples/mom/*.mom
57              – example files using mom
58

DOCUMENTATION IN ALPHABETICAL ORDER

60       This part of the man page contains information just as in groff(7), mom
61       macros and mom escape sequences in alphabetical order.
62
63       The  logical  order of mom macros and mom escape sequences is very well
64       documented in
65
66       /usr/share/doc/groff/html/mom/toc.html
67              – entry point to the HTML documentation
68
69       That document is quite good for beginners, but other  users  should  be
70       happy to have some documentation in reference style.
71
72       So we restrict this part to the alphabetical order of macros and escape
73       sequences.  But, so far, we took all  documentation  details  from  the
74       toc.html  file, just in a more useful alphabetical order.  So this part
75       of the man page is nothing new, but only a logical arrangement.
76

QUICK REFERENCE

78   Quick Reference of Inline Escape Sequences in alphabetical Order
79       \*[<colorname>]
80              begin using an initialized colour inline
81
82       \*[BCK n]
83              move backwards in a line
84
85       \*[BOLDER]
86              invoke pseudo bold inline (related to macro .SETBOLDER)
87
88       \*[BOLDERX]
89              off pseudo bold inline (related to macro .SETBOLDER)
90
91       \*[BU n]
92              move characters pairs closer together inline (related  to  macro
93              .KERN)
94
95       \*[COND]
96              invoke pseudo condensing inline (related to macro .CONDENSE)
97
98       \*[CONDX]
99              off pseudo condensing inline (related to macro .CONDENSE)
100
101       \*[CONDSUP]...\*[CONDSUPX]
102              pseudo-condensed superscript
103
104       \*[DOWN n]
105              temporarily move downwards in a line
106
107       \*[EN-MARK]
108              mark  initial line of a range of line numbers (for use with line
109              numbered endnotes)
110
111       \*[EXT]
112              invoke pseudo extending inline (related to macro .EXTEND)
113
114       \*[EXTX]
115              off pseudo condensing inline (related to macro .EXTEND)
116
117       \*[EXTSUP]...\*[EXTSUPX]
118              pseudo extended superscript
119
120       \*[FU n]
121              move characters pairs further apart  inline  (related  to  macro
122              .KERN)
123
124       \*[FWD n]
125              move forward in a line
126
127       \*[LEADER]
128              insert leaders at the end of a line
129
130       \*[RULE]
131              draw a full measure rule
132
133       \*[SIZE n]
134              change the point size inline (related to macro .PT_SIZE)
135
136       \*[SLANT]
137              invoke pseudo italic inline (related to macro .SETSLANT)
138
139       \*[SLANTX]
140              off pseudo italic inline (related to macro .SETSLANT)
141
142       \*[ST<n>]...\*[ST<n>X]
143              string tabs (mark tab positions inline)
144
145       \*[SUP]...\*[SUPX]
146              superscript
147
148       \*[TB+]
149              inline escape for .TN (Tab Next)
150
151       \*[UL]...\*[ULX]
152              invoke underlining inline (fixed width fonts only)
153
154       \*[UP n]
155              temporarily move upwards in a line
156
157   Quick Reference of Macros in alphabetical Order
158       .AUTOLEAD
159              set the linespacing relative to the point size
160
161       .B_MARGIN
162              set a bottom margin
163
164       .BR    break a justified line
165
166       .CENTER
167              set line-by-line quad centre
168
169       .CONDENSE
170              set the amount to pseudo condense
171
172       .EL    break a line without advancing on the page
173
174       .EXTEND
175              set the amount to pseudo extend
176
177       .FALLBACK_FONT
178              establish a fallback font (for missing fonts)
179
180       .FAM   alias to .FAMILY
181
182       .FAMILY <family>
183              set the family type
184
185       .FT    set the font style (roman, italic, etc.)
186
187       .HI [ <measure> ]
188              hanging indent
189
190       .HY    automatic hyphenation on/off
191
192       .HY_SET
193              set automatic hyphenation parameters
194
195       .IB [ <left measure> <right measure> ]
196              indent both
197
198       .IBX [ CLEAR ]
199              exit indent both
200
201       .IL [ <measure> ]
202              indent left
203
204       .ILX [ CLEAR ]
205              exit indent left
206
207       .IQ [ CLEAR ]
208              quit any/all indents
209
210       .IR [ <measure> ]
211              indent right
212
213       .IRX [ CLEAR ]
214              exit indent right
215
216       .JUSTIFY
217              justify text to both margins
218
219       .KERN  automatic character pair kerning on/off
220
221       .L_MARGIN
222              set a left margin (page offset)
223
224       .LEFT  set line-by-line quad left
225
226       .LL    set a line length
227
228       .LS    set a linespacing (leading)
229
230       .PAGE  set explicit page dimensions and margins
231
232       .PAGEWIDTH
233              set a custom page width
234
235       .PAGELENGTH
236              set a custom page length
237
238       .PAPER <paper_type>
239              set common paper sizes (letter, A4, etc)
240
241       .PT_SIZE
242              set the point size
243
244       .QUAD  "justify" text left, centre, or right
245
246       .R_MARGIN
247              set a right margin
248
249       .RIGHT set line-by-line quad right
250
251       .SETBOLDER
252              set the amount of emboldening
253
254       .SETSLANT
255              set the degree of slant
256
257       .SPREAD
258              force justify a line
259
260       .SS    set the sentence space size
261
262       .T_MARGIN
263              set a top margin
264
265       .TI [ <measure> ]
266              temporary left indent
267
268       .WS    set the minimum word space size
269

DOCUMENTATION OF DETAILS

271   Details of Inline Escape Sequences in alphabetical Order
272       \*[<colorname>]
273              begin using an initialized colour inline
274
275       \*[BCK n]
276              move wards in a line
277
278       \*[BOLDER]
279       \*[BOLDERX]
280              Emboldening on/off
281
282              \*[BOLDER]  begins emboldening type.  \*[BOLDERX] turns the fea‐
283              ture off.  Both are inline escapes, therefore  they  should  not
284              appear  as separate lines, but rather be embedded in text lines,
285              like this:
286                     Not \*[BOLDER]everything\*[BOLDERX] is as it seems.
287
288              Alternatively, if you wanted  the  whole  line  emboldened,  you
289              should do
290                     \*[BOLDER]Not everything is as it seems.\*[BOLDERX]
291              Once  \*[BOLDER]  is  invoked, it remains in effect until turned
292              off.
293
294              Note: If  you're  using  the  document  processing  macros  with
295              .PRINTSTYLE TYPEWRITE, mom ignores \*[BOLDER] requests.
296
297       \*[BU n]
298              move  characters  pairs closer together inline (related to macro
299              .KERN)
300
301       \*[COND]
302       \*[CONDX]
303              Pseudo-condensing on/off
304
305              \*[COND] begins pseudo-condensing  type.   \*[CONDX]  turns  the
306              feature off.  Both are inline escapes, therefore they should not
307              appear as separate lines, but rather be embedded in text  lines,
308              like this:
309                     \*[COND]Not everything is as it seems.\*[CONDX]
310              \*[COND] remains in effect until you turn it off with \*[CONDX].
311
312              IMPORTANT:  You must turn \*[COND] off before making any changes
313              to the point size of your type, either via the .PT_SIZE macro or
314              with the \s inline escape.  If you wish the new point size to be
315              pseudo-condensed, simply reinvoke \*[COND] afterwards.  Equally,
316              \*[COND]  must  be  turned off before changing the condense per‐
317              centage with .CONDENSE.
318
319              Note: If  you're  using  the  document  processing  macros  with
320              .PRINTSTYLE TYPEWRITE, mom ignores \*[COND] requests.
321
322       \*[CONDSUP]...\*[CONDSUPX]
323              pseudo-condensed superscript
324
325       \*[DOWN n]
326              temporarily move downwards in a line
327
328       \*[EN-MARK]
329              mark  initial line of a range of line numbers (for use with line
330              numbered endnotes)
331
332       \*[EXT]
333       \*[EXTX]
334              Pseudo-extending on/off
335
336              \*[EXT] begins pseudo-extending type.  \*[EXTX] turns  the  fea‐
337              ture  off.   Both  are inline escapes, therefore they should not
338              appear as separate lines, but rather be embedded in text  lines,
339              like this:
340                     \*[EXT]Not everything is as it seems.\*[EXTX]
341              \*[EXT] remains in effect until you turn it off with \*[EXTX].
342
343              IMPORTANT:  You  must turn \*[EXT] off before making any changes
344              to the point size of your type, either via the .PT_SIZE macro or
345              with the \s inline escape.  If you wish the new point size to be
346              pseudo-extended, simply reinvoke \*[EXT]  afterwards.   Equally,
347              \*[EXT] must be turned off before changing the extend percentage
348              with .EXTEND.
349
350              Note: If you are  using  the  document  processing  macros  with
351              .PRINTSTYLE TYPEWRITE, mom ignores \*[EXT] requests.
352
353       \*[EXTSUP]...\*[EXTSUPX]
354              pseudo extended superscript
355
356       \*[FU n]
357              move  characters  pairs  further  apart inline (related to macro
358              .KERN)
359
360       \*[FWD n]
361              move forward in a line
362
363       \*[LEADER]
364              insert leaders at the end of a line
365
366       \*[RULE]
367              draw a full measure rule
368
369       \*[SIZE n]
370              change the point size inline (related to macro .PT_SIZE)
371
372       \*[SLANT]
373       \*[SLANTX]
374              Pseudo italic on/off
375
376              \*[SLANT] begins pseudo-italicizing type.  \*[SLANTX] turns  the
377              feature off.  Both are inline escapes, therefore they should not
378              appear as separate lines, but rather be embedded in text  lines,
379              like this:
380                     Not \*[SLANT]everything\*[SLANTX] is as it seems.
381
382              Alternatively,  if  you wanted the whole line pseudo-italicized,
383              you'd do
384                     \*[SLANT]Not everything is as it seems.\*[SLANTX]
385
386              Once \*[SLANT] is invoked, it remains  in  effect  until  turned
387              off.
388
389              Note:  If  you're  using  the  document  processing  macros with
390              .PRINTSTYLE TYPEWRITE, mom underlines pseudo-italics by default.
391              To    change    this    behaviour,   use   the   special   macro
392              .SLANT_MEANS_SLANT.
393
394       \*[ST<number>]...\*[ST<number>X]
395              Mark positions of string tabs
396
397              The quad direction must  be  LEFT  or  JUSTIFY  (see  .QUAD  and
398              .JUSTIFY) or the no-fill mode set to LEFT in order for these in‐
399              lines to function properly.  Please see IMPORTANT, below.
400
401              String tabs need to be marked off with inline escapes before be‐
402              ing  set  up  with  the  .ST  macro.  Any input line may contain
403              string tab markers.  <number>, above, means the numeric  identi‐
404              fier of the tab.
405
406              The following shows a sample input line with string tab markers.
407                     \*[ST1]Now is the time\*[ST1X] for all \*[ST2]good men\*ST2X] to come to the aid of the party.
408
409              String  tab 1 begins at the start of the line and ends after the
410              word time.  String tab 2 starts at good and ends after men.  In‐
411              line  escapes  (e.g.  font  or point size changes, or horizontal
412              movements, including padding) are taken into  account  when  mom
413              determines the position and length of string tabs.
414
415              Up to nineteen string tabs may be marked (not necessarily all on
416              the same line, of course), and they must be numbered  between  1
417              and 19.
418
419              Once  string  tabs have been marked in input lines, they have to
420              be set with .ST, after which they may be called, by number, with
421              .TAB.
422
423              Note: Lines with string tabs marked off in them are normal input
424              lines, i.e. they get printed, just like any input line.  If  you
425              want  to  set  up string tabs without the line printing, use the
426              .SILENT macro.
427
428              IMPORTANT: Owing to the way  groff  processes  input  lines  and
429              turns  them  into  output  lines,  it is not possible for mom to
430              guess the correct starting position of string tabs marked off in
431              lines that are centered or set flush right.
432
433              Equally,  she  cannot  guess  the starting position if a line is
434              fully justified and broken with .SPREAD.
435
436              In other words, in order to use string tabs, LEFT  must  be  ac‐
437              tive, or, if .QUAD LEFT or JUSTIFY are active, the line on which
438              the string tabs are marked must be broken manually with .BR (but
439              not .SPREAD).
440
441              To  circumvent  this behaviour, I recommend using the PAD to set
442              up string tabs in centered or flush right lines.  Say, for exam‐
443              ple,  you  want  to use a string tab to underscore the text of a
444              centered line with a rule.  Rather than this,
445                     .CENTER
446                     \*[ST1]A line of text\*[ST1X]\c
447                     .EL
448                     .ST 1
449                     .TAB 1
450                     .PT_SIZE 24
451                     .ALD 3p
452                     \*[RULE]
453                     .RLD 3p
454                     .TQ
455              you should do:
456                     .QUAD CENTER
457                     .PAD "#\*[ST1]A line of text\*[ST1X]#"
458                     .EL
459                     .ST 1
460                     .TAB 1
461                     .PT_SIZE 24
462                     .ALD 3p
463                     \*[RULE] \" Note that you can't use \*[UP] or \*[DOWN] with \*[RULE]
464                     .RLD 3p
465                     .TQ
466
467       \*[SUP]...\*[SUPX]
468              superscript
469
470       \*[TB+]
471              Inline escape for .TN (Tab Next)
472
473       \*[UL]...\*[ULX]
474              invoke underlining inline (fixed width fonts only)
475
476       \*[UP n]
477              temporarily move upwards in a line
478
479   Details of Macros in alphabetical Order
480       .AUTOLEAD
481              set the linespacing relative to the point size
482
483       .B_MARGIN <bottom margin>
484              Bottom Margin
485
486              Requires a unit of measure
487
488              .B_MARGIN sets a nominal position at the bottom of the page  be‐
489              yond which you don't want your type to go.  When the bottom mar‐
490              gin is reached, mom starts a new  page.   .B_MARGIN  requires  a
491              unit of measure.  Decimal fractions are allowed.  To set a nomi‐
492              nal bottom margin of 3/4 inch, enter
493                     .B_MARGIN .75i
494
495              Obviously, if you haven't spaced the type on your pages so  that
496              the  last  lines fall perfectly at the bottom margin, the margin
497              will vary from page to page.  Usually, but not always, the  last
498              line of type that fits on a page before the bottom margin causes
499              mom to start a new page.
500
501              Occasionally, owing to a peculiarity in  groff,  an  extra  line
502              will  fall below the nominal bottom margin.  If you're using the
503              document processing macros, this is unlikely to happen; the doc‐
504              ument  processing macros are very hard-nosed about aligning bot‐
505              tom margins.
506
507              Note: The meaning of .B_MARGIN is slightly different when you're
508              using the document processing macros.
509
510       .FALLBACK_FONT <fallback font> [ ABORT | WARN ]
511              Fallback Font
512
513              In  the event that you pass an invalid argument to .FAMILY (i.e.
514              a non-existent family), mom, by default, uses the fallback font,
515              Courier  Medium Roman (CR), in order to continue processing your
516              file.
517
518              If you'd prefer another fallback font, pass  .FALLBACK_FONT  the
519              full  family+font  name of the font you'd like.  For example, if
520              you'd rather the fallback font were Times Roman Medium Roman,
521                     .FALLBACK_FONT TR
522              would do the trick.
523
524              Mom issues a warning whenever a font style set with .FT does not
525              exist,  either  because  you haven't registered the style or be‐
526              cause the font style does not exist in the  current  family  set
527              with  .FAMILY.  By default, mom then aborts, which allows you to
528              correct the problem.
529
530              If you'd prefer that mom not abort on  non-existent  fonts,  but
531              rather  continue  processing using a fallback font, you can pass
532              .FALLBACK_FONT the argument WARN, either by itself, or  in  con‐
533              junction with your chosen fallback font.
534
535              Some examples of invoking .FALLBACK_FONT:
536
537              .FALLBACK_FONT WARN
538                     mom  will  issue  a  warning whenever you try to access a
539                     non-existent font but will continue processing your  file
540                     with the default fallback font, Courier Medium Roman.
541
542              .FALLBACK_FONT TR WARN
543                     mom  will  issue  a  warning whenever you try to access a
544                     non-existent font but will continue processing your  file
545                     with  a  fallback font of Times Roman Medium Roman; addi‐
546                     tionally, TR will be the fallback font whenever  you  try
547                     to access a family that does not exist.
548
549              .FALLBACK_FONT TR ABORT
550                     mom  will abort whenever you try to access a non-existent
551                     font, and will use the fallback font TR whenever you  try
552                     to  access  a  family  that does not exist.  If, for some
553                     reason,  you  want  to  revert  to  ABORT,   just   enter
554                     ".FALLBACK_FONT  ABORT"  and mom will once again abort on
555                     font errors.
556
557       .FAM <family>
558              Type Family, alias of .FAMILY
559
560       .FAMILY <family>
561              Type Family, alias .FAM
562
563              .FAMILY takes one argument: the name of  the  family  you  want.
564              Groff  comes with a small set of basic families, each identified
565              by a 1-, 2- or 3-letter mnemonic.  The standard families are:
566                     A   = Avant Garde
567                     BM  = Bookman
568                     H   = Helvetica
569                     HN  = Helvetica Narrow
570                     N   = New Century Schoolbook
571                     P   = Palatino
572                     T   = Times Roman
573                     ZCM = Zapf Chancery
574
575              The argument you pass to .FAMILY  is  the  identifier  at  left,
576              above.  For example, if you want Helvetica, enter
577                     .FAMILY H
578
579              Note: The font macro (.FT) lets you specify both the type family
580              and the desired font with a single macro.  While  this  saves  a
581              few  keystrokes,  I  recommend using .FAMILY for family, and .FT
582              for font, except where doing so is genuinely inconvenient.  ZCM,
583              for example, only exists in one style: Italic (I).
584
585              Therefore,
586                     .FT ZCMI
587              makes  more  sense  than setting the family to ZCM, then setting
588              the font to I.
589
590              Additional note: If you are running a  version  of  groff  lower
591              than 1.19.2, you must follow all .FAMILY requests with a .FT re‐
592              quest, otherwise mom will set all type up to the  next  .FT  re‐
593              quest in the fallback font.
594
595              If  you  are running a version of groff greater than or equal to
596              1.19.2, when you invoke the .FAMILY  macro,  mom  remembers  the
597              font  style  (Roman,  Italic, etc) currently in use (if the font
598              style exists in the new family) and will  continue  to  use  the
599              same font style in the new family.  For example:
600                     .FAMILY BM \" Bookman family
601                     .FT I \" Medium Italic
602                     <some text> \" Bookman Medium Italic
603                     .FAMILY H \" Helvetica family
604                     <more text> \" Helvetica Medium Italic
605
606              However, if the font style does not exist in the new family, mom
607              will set all subsequent type in the fallback font  (by  default,
608              Courier  Medium Roman) until she encounters a .FT request that's
609              valid for the family.
610
611              For example, assuming you don't have the font  Medium  Condensed
612              Roman (mom extension CD) in the Helvetica family:
613                     .FAMILY UN \" Univers family
614                     .FT CD \" Medium Condensed
615                     <some text> \" Univers Medium Condensed
616                     .FAMILY H \" Helvetica family
617                     <more text> \" Courier Medium Roman!
618
619              In  the  above example, you must follow .FAMILY H with a .FT re‐
620              quest that's valid for Helvetica.
621
622              Please see the Appendices, Adding fonts to groff,  for  informa‐
623              tion  on adding fonts and families to groff, as well as to see a
624              list of the extensions mom provides to groff's basic R, I, B, BI
625              styles.
626
627              Suggestion: When adding families to groff, I recommend following
628              the established standard for the naming families and fonts.  For
629              example, if you add the Garamond family, name the font files
630                     GARAMONDR
631                     GARAMONDI
632                     GARAMONDB
633                     GARAMONDBI
634              GARAMOND  then becomes a valid family name you can pass to .FAM‐
635              ILY.  (You could, of course, shorten GARAMOND to just G, or GD.)
636              R,  I,  B, and BI after GARAMOND are the roman, italic, bold and
637              bold-italic fonts respectively.
638
639       .FONT R | B | BI | <any other valid font style>
640              Alias to .FT
641
642       .FT R | B | BI | <any other valid font style>
643              Set font
644
645              By default, groff permits .FT to take one of four possible argu‐
646              ments specifying the desired font:
647                     R = (Medium) Roman
648                     I = (Medium) Italic
649                     B = Bold (Roman)
650                     BI = Bold Italic
651
652              For example, if your family is Helvetica, entering
653                     .FT B
654              will  give  you  the  Helvetica  bold font.  If your family were
655              Palatino, you'd get the Palatino bold font.
656
657              Mom considerably extends the range of arguments you can pass  to
658              .FT,  making  it more convenient to add and access fonts of dif‐
659              fering weights and shapes within the same family.
660
661              Have a look here for a list of the  weight/style  arguments  mom
662              allows.   Be  aware,  though, that you must have the fonts, cor‐
663              rectly installed and named, in order to use the arguments.  (See
664              Adding fonts to groff for instructions and information.)  Please
665              also read the ADDITIONAL NOTE found in the  description  of  the
666              .FAMILY macro.
667
668              How  mom  reacts  to an invalid argument to .FT depends on which
669              version of groff you're using.  If your groff version is greater
670              than or equal to 1.19.2, mom will issue a warning and, depending
671              on how you've set up the fallback font, either continue process‐
672              ing  using  the fallback font, or abort (allowing you to correct
673              the problem).  If your groff version is less  than  1.19.2,  mom
674              will  silently  continue  processing,  using either the fallback
675              font or the font that was in effect prior  to  the  invalid  .FT
676              call.
677
678              .FT  will  also  accept,  as an argument, a full family and font
679              name.
680
681              For example,
682                     .FT HB
683              will set subsequent type in Helvetica Bold.
684
685              However, I strongly recommend keeping family and  font  separate
686              except where doing so is genuinely inconvenient.
687
688              For inline control of fonts, see Inline Escapes, font control.
689
690       .HI [ <measure> ]
691              Hanging  indent  — the optional argument requires a unit of mea‐
692              sure.
693
694              A hanging indent looks like this:
695                       The thousand injuries of Fortunato I had borne as best I
696                         could, but when he ventured upon insult, I vowed
697                         revenge.  You who so well know the nature of my soul
698                         will not suppose, however, that I gave utterance to a
699                         threat, at length I would be avenged...
700              The first line of text hangs outside the left margin.
701
702              In order to use hanging indents, you must first have a left  in‐
703              dent  active  (set  with  either .IL or .IB).  Mom will not hang
704              text outside the left margin set with .L_MARGIN or  outside  the
705              left margin of a tab.
706
707              The  first  time you invoke .HI, you must give it a measure.  If
708              you want the first line of a paragraph to hang by, say, 1  pica,
709              do
710                     .IL 1P
711                     .HI 1P
712              Subsequent  invocations  of  .HI  do not require you to supply a
713              measure; mom keeps track of the last measure you gave it.
714
715              Generally speaking, you should invoke .HI immediately  prior  to
716              the  line  you  want  hung (i.e. without any intervening control
717              lines).  And because  hanging  indents  affect  only  one  line,
718              there's no need to turn them off.
719
720              IMPORTANT:  Unlike  IL, IR and IB, measures given to .HI are NOT
721              additive.  Each time you pass a measure to .HI , the measure  is
722              treated  literally.   Recipe:  A numbered list using hanging in‐
723              dents
724
725              Note: mom has macros for setting lists.  This recipe  exists  to
726              demonstrate the use of hanging indents only.
727                     .PAGE 8.5i 11i 1i 1i 1i 1i
728                     .FAMILY  T
729                     .FT      R
730                     .PT_SIZE 12
731                     .LS      14
732                     .JUSTIFY
733                     .KERN
734                     .SS 0
735                     .IL \w'\0\0.'
736                     .HI \w'\0\0.'
737                     1.\0The most important point to be considered is whether the
738                     answer to the meaning of Life, the Universe, and Everything
739                     really is 42.  We have no-one's word on the subject except
740                     Mr. Adams'.
741                     .HI
742                     2.\0If the answer to the meaning of Life, the Universe,
743                     and Everything is indeed 42, what impact does this have on
744                     the politics of representation?  42 is, after all not a
745                     prime number.  Are we to infer that prime numbers don't
746                     deserve equal rights and equal access in the universe?
747                     .HI
748                     3.\0If 42 is deemed non-exclusionary, how do we present it
749                     as the answer and, at the same time, forestall debate on its
750                     exclusionary implications?
751
752              First, we invoke a left indent with a measure equal to the width
753              of 2 figures spaces plus a period (using the \w inline  escape).
754              At  this point, the left indent is active; text afterwards would
755              normally be indented.  However, we invoke a  hanging  indent  of
756              exactly  the  same  width, which hangs the first line (and first
757              line only!) to the left of the indent by the same  distance  (in
758              this case, that means “out to the left margin”).  Because we be‐
759              gin the first line with a number, a period, and a figure  space,
760              the  actual text (The most important point...) starts at exactly
761              the same spot as the indented lines that follow.
762
763              Notice that subsequent invocations of .HI don't require  a  mea‐
764              sure to be given.
765
766              Paste the example above into a file and preview it with
767                     pdfmom filename.mom | ps2pdf - filename.pdf
768              to see hanging indents in action.
769
770       .IB [ <left measure> <right measure> ]
771              Indent both — the optional argument requires a unit of measure
772
773              .IB allows you to set or invoke a left and a right indent at the
774              same time.
775
776              At its first invocation, you must supply a measure for both  in‐
777              dents;  at subsequent invocations when you wish to supply a mea‐
778              sure, both must be given again.  As with .IL and .IR,  the  mea‐
779              sures  are  added  to the values previously passed to the macro.
780              Hence, if you wish to change just one of the  values,  you  must
781              give an argument of zero to the other.
782
783              A  word  of advice: If you need to manipulate left and right in‐
784              dents separately, use a combination of .IL and  .IR  instead  of
785              .IB.  You'll save yourself a lot of grief.
786
787              A  minus sign may be prepended to the arguments to subtract from
788              their current values.  The \w inline escape may be used to spec‐
789              ify text-dependent measures, in which case no unit of measure is
790              required.  For example,
791                     .IB \w'margarine' \w'jello'
792              left indents text by the width of the word margarine  and  right
793              indents by the width of jello.
794
795              Like  .IL  and .IR, .IB with no argument indents by its last ac‐
796              tive values.  See the brief explanation of how mom  handles  in‐
797              dents for more details.
798
799              Note:  Calling  a  tab (with .TAB <n>) automatically cancels any
800              active indents.
801
802              Additional note: Invoking .IB automatically turns  off  .IL  and
803              .IR.
804
805       .IL [ <measure> ]
806              Indent left — the optional argument requires a unit of measure
807
808              .IL  indents text from the left margin of the page, or if you're
809              in a tab, from the left edge of the tab.  Once  IL  is  on,  the
810              left  indent  is  applied  uniformly to every subsequent line of
811              text, even if you change the line length.
812
813              The first time you invoke .IL, you must give it a measure.  Sub‐
814              sequent  invocations with a measure add to the previous measure.
815              A minus sign may be prepended to the argument to  subtract  from
816              the  current measure.  The \w inline escape may be used to spec‐
817              ify a text-dependent measure, in which case no unit  of  measure
818              is required.  For example,
819                     .IL \w'margarine'
820              indents text by the width of the word margarine.
821
822              With no argument, .IL indents by its last active value.  See the
823              brief explanation of how mom handles indents for more details.
824
825              Note: Calling a tab (with .TAB <n>)  automatically  cancels  any
826              active indents.
827
828              Additional note: Invoking .IL automatically turns off IB.
829
830       .IQ [ <measure> ]
831              IQ — quit any/all indents
832
833              IMPORTANT  NOTE: The original macro for quitting all indents was
834              .IX.  This usage has been deprecated in favour of IQ.  .IX  will
835              continue  to  behave  as before, but mom will issue a warning to
836              stderr indicating that you should update your documents.
837
838              As a consequence of this change, .ILX, .IRX  and  .IBX  may  now
839              also  be invoked as .ILQ, .IRQ and .IBQ.  Both forms are accept‐
840              able.
841
842              Without an argument, the macros to quit indents  merely  restore
843              your  original  margins and line length.  The measures stored in
844              the indent macros themselves are saved  so  you  can  call  them
845              again without having to supply a measure.
846
847              If  you  pass these macros the optional argument CLEAR, they not
848              only restore your original left margin and line length, but also
849              clear any values associated with a particular indent style.  The
850              next time you need an indent of the same style, you have to sup‐
851              ply a measure again.
852
853              .IQ CLEAR, as you'd suspect, quits and clears the values for all
854              indent styles at once.
855
856       .IR [ <measure> ]
857              Indent right — the optional argument requires a unit of measure
858
859              .IR indents text from the right margin of the page, or if you're
860              in a tab, from the end of the tab.
861
862              The first time you invoke .IR, you must give it a measure.  Sub‐
863              sequent invocations with a measure add to  the  previous  indent
864              measure.   A minus sign may be prepended to the argument to sub‐
865              tract from the current indent measure.  The \w inline escape may
866              be  used  to  specify a text-dependent measure, in which case no
867              unit of measure is required.  For example,
868                     .IR \w'jello'
869              indents text by the width of the word jello.
870
871              With no argument, .IR indents by its last active value.  See the
872              brief explanation of how mom handles indents for more details.
873
874              Note:  Calling  a  tab (with .TAB <n>) automatically cancels any
875              active indents.
876
877              Additional note: Invoking .IR automatically turns off IB.
878
879       .L_MARGIN <left margin>
880              Left Margin
881
882              L_MARGIN establishes the distance from  the  left  edge  of  the
883              printer  sheet  at which you want your type to start.  It may be
884              used any time, and remains in  effect  until  you  enter  a  new
885              value.
886
887              Left  indents and tabs are calculated from the value you pass to
888              .L_MARGIN, hence it's always a good idea  to  invoke  it  before
889              starting  any  serious  typesetting.   A  unit of measure is re‐
890              quired.  Decimal fractions are allowed.  Therefore, to  set  the
891              left margin at 3 picas (1/2 inch), you'd enter either
892                     .L_MARGIN 3P
893              or
894                     .L_MARGIN .5i
895
896              If you use the macros .PAGE, .PAGEWIDTH or .PAPER without invok‐
897              ing .L_MARGIN (either before or afterwards),  mom  automatically
898              sets .L_MARGIN to 1 inch.
899
900              Note:  .L_MARGIN  behaves in a special way when you're using the
901              document processing macros.
902
903       .MCO   Begin multi-column setting.
904
905              .MCO (Multi-Column On) is the macro you use to begin  multi-col‐
906              umn  setting.   It marks the current baseline as the top of your
907              columns, for use later with .MCR.  See the introduction to  col‐
908              umns for an explanation of multi-columns and some sample input.
909
910              Note:  Do  not confuse .MCO with the .COLUMNS macro in the docu‐
911              ment processing macros.
912
913       .MCR   Once you've turned multi-columns on (with .MCO),  .MCR,  at  any
914              time, returns you to the top of your columns.
915
916       .MCX [ <distance to advance below longest column> ]
917              Optional argument requires a unit of measure.
918
919              .MCX  takes you out of any tab you were in (by silently invoking
920              .TQ) and advances to the bottom of the longest column.
921
922              Without an argument, .MCX advances 1 linespace below the longest
923              column.
924
925              Linespace, in this instance, is the leading in effect at the mo‐
926              ment .MCX is invoked.
927
928              If you pass the <distance> argument to .MCX, it advances 1 line‐
929              space  below  the  longest  column (see above) PLUS the distance
930              specified by the argument.  The argument requires a unit of mea‐
931              sure;  therefore,  to advance an extra 6 points below where .MCX
932              would normally place you, you'd enter
933                     .MCX 6p
934
935              Note: If you wish to advance a precise distance below the  base‐
936              line  of  the  longest  column,  use  .MCX with an argument of 0
937              (zero; no unit of measure required) in conjunction with the .ALD
938              macro, like this:
939                     .MCX 0
940                     .ALD 24p
941              The  above advances to precisely 24 points below the baseline of
942              the longest column.
943
944       .NEWPAGE
945
946              Whenever you want to start a new page, use .NEWPAGE,  by  itself
947              with  no  argument.   Mom  will finish up processing the current
948              page and move you to the top of a new one (subject  to  the  top
949              margin set with .T_MARGIN).
950
951       .PAGE <width> [ <length> [ <lm> [ <rm> [ <tm> [ <bm> ] ] ] ] ]
952
953              All arguments require a unit of measure
954
955              IMPORTANT: If you're using the document processing macros, .PAGE
956              must come after .START.  Otherwise, it should go at the top of a
957              document,  prior  to  any text.  And remember, when you're using
958              the document processing macros, top  margin  and  bottom  margin
959              mean  something  slightly  different than when you're using just
960              the typesetting macros (see Top and bottom margins  in  document
961              processing).
962
963              .PAGE  lets you establish paper dimensions and page margins with
964              a single macro.  The only required argument is page width.   The
965              rest  are  optional, but they must appear in order and you can't
966              skip over any.  <lm>, <rm>, <tm> and <bm>  refer  to  the  left,
967              right, top and bottom margins respectively.
968
969              Assuming  your  page  dimensions are 11 inches by 17 inches, and
970              that's all you want to set, enter
971                     .PAGE 11i 17i
972              If you want to set the left margin as well, say, at 1 inch, PAGE
973              would look like this:
974                     .PAGE 11i 17i 1i
975
976              Now  suppose  you also want to set the top margin, say, at 1–1/2
977              inches.  <tm> comes after <rm> in the  optional  arguments,  but
978              you can't skip over any arguments, therefore to set the top mar‐
979              gin, you must also give a right margin.  The .PAGE  macro  would
980              look like this:
981                     .PAGE 11i 17i 1i 1i 1.5i
982                                      |   |
983                     required right---+   +---top margin
984                             margin
985
986              Clearly,  .PAGE  is  best used when you want a convenient way to
987              tell mom just the dimensions of your printer  sheet  (width  and
988              length),  or when you want to tell her everything about the page
989              (dimensions and all the margins), for example
990                     .PAGE 8.5i 11i 45p 45p 45p 45p
991              This sets up an 8½ by 11 inch page with  margins  of  45  points
992              (5/8-inch) all around.
993
994              Additionally,  if  you  invoke .PAGE with a top margin argument,
995              any macros you invoke after .PAGE will almost certainly move the
996              baseline  of  the  first line of text down by one linespace.  To
997              compensate, do
998                     .RLD 1v
999              immediately before entering any text, or, if it's feasible, make
1000              .PAGE the last macro you invoke prior to entering text.
1001
1002              Please  read the Important note on page dimensions and papersize
1003              for information on ensuring groff respects your .PAGE dimensions
1004              and margins.
1005
1006       .PAGELENGTH <length of printer sheet>
1007              tells  mom  how  long your printer sheet is.  It works just like
1008              .PAGEWIDTH.
1009
1010              Therefore, to tell mom your printer sheet is 11 inches long, you
1011              enter
1012                     .PAGELENGTH 11i
1013              Please  read the important note on page dimensions and papersize
1014              for information on ensuring groff respects your PAGELENGTH.
1015
1016       .PAGEWIDTH <width of printer sheet>
1017
1018              The argument to .PAGEWIDTH is the width of your printer sheet.
1019
1020              .PAGEWIDTH requires a unit of measure.   Decimal  fractions  are
1021              allowed.   Hence,  to  tell  mom  that the width of your printer
1022              sheet is 8½ inches, you enter
1023                     .PAGEWIDTH 8.5i
1024
1025              Please read the Important note on page dimensions and  papersize
1026              for information on ensuring groff respects your PAGEWIDTH.
1027
1028       .PAPER <paper type>
1029              provides  a  convenient  way to set the page dimensions for some
1030              common printer sheet sizes.  The argument <paper  type>  can  be
1031              one  of:  LETTER,  LEGAL,  STATEMENT,  TABLOID,  LEDGER,  FOLIO,
1032              QUARTO, EXECUTIVE, 10x14, A3, A4, A5, B4, B5.
1033
1034       .PRINTSTYLE
1035
1036       .PT_SIZE <size of type in points>
1037              Point size of type, does not require a unit of measure.
1038
1039              .PT_SIZE (Point Size) takes one argument: the size  of  type  in
1040              points.   Unlike  most  other  macros that establish the size or
1041              measure of something, .PT_SIZE does not require that you  supply
1042              a  unit  of  measure since it's a near universal convention that
1043              type size is measured in points.  Therefore, to change the  type
1044              size to, say, 11 points, enter
1045                     .PT_SIZE 11
1046              Point sizes may be fractional (e.g. 10.25 or 12.5).
1047
1048              You  can  prepend  a  plus  or  a  minus sign to the argument to
1049              .PT_SIZE, in which case the point size will be changed by + or -
1050              the  original value.  For example, if the point size is 12 , and
1051              you want 14 , you can do
1052                     .PT_SIZE +2
1053              then later reset it to 12 with
1054                     .PT_SIZE -2
1055              The size of type can also be changed inline.
1056
1057              Note: It is unfortunate that the pic  preprocessor  has  already
1058              taken the name, PS, and thus mom's macro for setting point sizes
1059              can't use it.  However, if you aren't using pic, you might  want
1060              to alias .PT_SIZE as .PS, since there'd be no conflict.  For ex‐
1061              ample
1062                     .ALIAS PS PT_SIZE
1063              would allow you to set point sizes with .PS.
1064
1065       .R_MARGIN <right margin>
1066              Right Margin
1067
1068              Requires a unit of measure.
1069
1070              IMPORTANT:  .R_MARGIN,  if  used,  must   come   after   .PAPER,
1071              .PAGEWIDTH,  .L_MARGIN,  and/or  .PAGE  (if a right margin isn't
1072              given to PAGE).  The reason is that  .R_MARGIN  calculates  line
1073              length from the overall page dimensions and the left margin.
1074
1075              Obviously,  it can't make the calculation if it doesn't know the
1076              page width and the left margin.
1077
1078              .R_MARGIN establishes the amount of space you want  between  the
1079              end  of  typeset  lines  and  the right hand edge of the printer
1080              sheet.  In other words, it sets the line length.  .R_MARGIN  re‐
1081              quires a unit of measure.  Decimal fractions are allowed.
1082
1083              The  line  length  macro (LL) can be used in place of .R_MARGIN.
1084              In either case, the last one invoked sets the line length.   The
1085              choice of which to use is up to you.  In some instances, you may
1086              find it easier to think of a section of type as having  a  right
1087              margin.  In others, giving a line length may make more sense.
1088
1089              For  example,  if  you're setting a page of type you know should
1090              have 6-pica margins left and right, it makes sense  to  enter  a
1091              left and right margin, like this:
1092                     .L_MARGIN 6P
1093                     .R_MARGIN 6P
1094
1095              That  way,  you  don't  have to worry about calculating the line
1096              length.  On the other hand, if you know the line  length  for  a
1097              patch of type should be 17 picas and 3 points, entering the line
1098              length with LL is much easier than calculating the right margin,
1099              e.g.
1100                     .LL 17P+3p
1101
1102              If  you use the macros .PAGE, .PAGEWIDTH or PAPER without invok‐
1103              ing .R_MARGIN afterwards, mom automatically sets .R_MARGIN to  1
1104              inch.   If  you set a line length after these macros (with .LL),
1105              the line length calculated by .R_MARGIN is, of course,  overrid‐
1106              den.
1107
1108              Note:  .R_MARGIN  behaves in a special way when you're using the
1109              document processing macros.
1110
1111       .ST <tab number> L | R | C | J [ QUAD ]
1112
1113              After string tabs have been marked off on  an  input  line  (see
1114              \*[ST]...\*[STX]),  you need to set them by giving them a direc‐
1115              tion and, optionally, the QUAD argument.
1116
1117              In this respect, .ST is like .TAB_SET except that you don't have
1118              to  give  .ST  an  indent or a line length (that's already taken
1119              care of, inline, by \*[ST]...\*[STX]).
1120
1121              If you want string tab 1 to be left, enter
1122                     .ST 1 L
1123              If you want it to be left and filled, enter
1124                     .ST 1 L QUAD
1125              If you want it to be justified, enter
1126                     .ST 1 J
1127
1128       .TAB <tab number>
1129              After tabs have been defined (either with .TAB_SET or .ST), .TAB
1130              moves to whatever tab number you pass it as an argument.
1131
1132              For example,
1133                     .TAB 3
1134              moves you to tab 3.
1135
1136              Note:  .TAB  breaks  the  line preceding it and advances 1 line‐
1137              space.  Hence,
1138                     .TAB 1
1139                     A line of text in tab 1.
1140                     .TAB 2
1141                     A line of text in tab 2.
1142              produces, on output
1143                     A line of text in tab 1.
1144                                                  A line of text in tab 2.
1145
1146              If you want the tabs to line up, use .TN  (Tab  Next)  or,  more
1147              conveniently, the inline escape \*[TB+]:
1148                     .TAB 1
1149                     A line of text in tab 1.\*[TB+]
1150                     A line of text in tab 2.
1151              which produces
1152                     A line of text in tab 1.   A line of text in tab 2.
1153
1154              If the text in your tabs runs to several lines, and you want the
1155              first lines of each tab to align, you must use the  multi-column
1156              macros.
1157
1158              Additional  note:  Any  indents in effect prior to calling a tab
1159              are automatically turned off by TAB.  If you were  happily  zip‐
1160              ping  down the page with a left indent of 2 picas turned on, and
1161              you call a tab whose indent from the left  margin  is  6  picas,
1162              your  new distance from the left margin will be 6 picas, not I 6
1163              picas plus the 2 pica indent.
1164
1165              Tabs are not by nature columnar, which is to  say  that  if  the
1166              text  inside  a  tab  runs to several lines, calling another tab
1167              does not automatically move to the baseline of the first line in
1168              the previous tab.  To demonstrate:
1169                     TAB 1
1170                     Carrots
1171                     Potatoes
1172                     Broccoli
1173                     .TAB 2
1174                     $1.99/5 lbs
1175                     $0.25/lb
1176                     $0.99/bunch
1177              produces, on output
1178                     Carrots
1179                     Potatoes
1180                     Broccoli
1181                                 $1.99/5 lbs
1182                                 $0.25/lb
1183                                 $0.99/bunch
1184
1185       .TB <tab number>
1186              Alias to .TAB
1187
1188       .TI [ <measure> ]
1189              Temporary left indent — the optional argument requires a unit of
1190              measure
1191
1192              A temporary indent is one that applies only to the first line of
1193              text  that comes after it.  Its chief use is indenting the first
1194              line of paragraphs.  (Mom's .PP macro, for example, uses a  tem‐
1195              porary indent.)
1196
1197              The  first  time you invoke .TI, you must give it a measure.  If
1198              you want to indent the first line of a paragraph by, say, 2 ems,
1199              do
1200                     .TI 2m
1201
1202              Subsequent  invocations  of  .TI  do not require you to supply a
1203              measure; mom keeps track of the last measure you gave it.
1204
1205              Because temporary indents are temporary, there's no need to turn
1206              them off.
1207
1208              IMPORTANT: Unlike .IL, .IR and IB, measures given to .TI are NOT
1209              additive.  In the following example, the second ".TI 2P" is  ex‐
1210              actly 2 picas.
1211                     .TI 1P
1212                     The beginning of a paragraph...
1213                     .TI 2P
1214                     The beginning of another paragraph...
1215
1216       .TN    Tab Next
1217
1218              Inline escape \*[TB+]
1219
1220              TN  moves  over  to  the  next tab in numeric sequence (tab n+1)
1221              without advancing on the page.  See the NOTE in the  description
1222              of the .TAB macro for an example of how TN works.
1223
1224              In  tabs that aren't given the QUAD argument when they're set up
1225              with .TAB_SET or ST, you must terminate the line  preceding  .TN
1226              with  the  \c inline escape.  Conversely, if you did give a QUAD
1227              argument to .TAB_SET or ST, the \c must not be used.
1228
1229              If you find remembering whether to put in the \c bothersome, you
1230              may prefer to use the inline escape alternative to .TN, \*[TB+],
1231              which works consistently regardless of the fill mode.
1232
1233              Note: You must put text in the input line immediately after .TN.
1234              Stacking of .TN's is not allowed.  In other words, you cannot do
1235                     .TAB 1
1236                     Some text\c
1237                     .TN
1238                     Some more text\c
1239                     .TN
1240                     .TN
1241                     Yet more text
1242              The above example, assuming tabs numbered from 1 to 4, should be
1243              entered
1244                     .TAB 1
1245                     Some text\c
1246                     .TN
1247                     Some more text\c
1248                     .TN
1249                     \&\c
1250                     .TN
1251                     Yet more text
1252              \& is a zero-width, non-printing character that groff recognizes
1253              as  valid input, hence meets the requirement for input text fol‐
1254              lowing .TN.
1255
1256       .TQ    TQ takes you out of whatever tab you were in, advances  1  line‐
1257              space, and restores the left margin, line length, quad direction
1258              and fill mode that were in effect prior to invoking any tabs.
1259
1260       .T_MARGIN <top margin>
1261              Top margin
1262
1263              Requires a unit of measure
1264
1265              .T_MARGIN establishes the distance from the top of  the  printer
1266              sheet  at which you want your type to start.  It requires a unit
1267              of measure, and decimal fractions are allowed.   To  set  a  top
1268              margin of 2½ centimetres, you'd enter
1269                     .T_MARGIN 2.5c
1270              .T_MARGIN  calculates the vertical position of the first line of
1271              type on a page by treating the top edge of the printer sheet  as
1272              a baseline.  Therefore,
1273                     .T_MARGIN 1.5i
1274              puts  the  baseline  of the first line of type 1½ inches beneath
1275              the top of the page.
1276
1277              Note: .T_MARGIN means something slightly different  when  you're
1278              using  the  document processing macros.  See Top and bottom mar‐
1279              gins in document processing for an explanation.
1280
1281              IMPORTANT: .T_MARGIN does two things:  it  establishes  the  top
1282              margin  for  pages that come after it and it moves to that posi‐
1283              tion on the current page.  Therefore, .T_MARGIN should  only  be
1284              used at the top of a file (prior to entering text) or after NEW‐
1285              PAGE, like this:
1286                     .NEWPAGE
1287                     .T_MARGIN 6P
1288                     <text>
1289

AUTHORS

1291       mom was written by Peter Schaffter ⟨peter@schaffter.ca⟩.   PDF  support
1292       was  provided  by Deri James ⟨deri@chuzzlewit.demon.co.uk⟩.  The alpha‐
1293       betical documentation of macros and escape sequences in this  man  page
1294       were written by the mom team.
1295

SEE ALSO

1297       groff(1), groff_mom(7),
1298
1299       /usr/share/doc/groff/html/mom/toc.html
1300              – entry point to the HTML documentation
1301
1302http://www.schaffter.ca/mom/momdoc/toc.html
1303              – HTML documentation online
1304
1305http://www.schaffter.ca/mom/
1306              – the mom macros homepage
1307
1308
1309
1310groff 1.22.4                    20 January 2022                   GROFF_MOM(7)
Impressum