contrib/mom/examples/mom-pdf.mom

   1 .\" -*- nroff -*-
   2 .\" Copyright (C) 2012-2014  Free Software Foundation, Inc.
   3 .\"
   4 .\" This file is part of mom, which is part of groff, a free software
   5 .\" project.
   6 .\"
   7 .\" You can redistribute it and/or modify it under the terms of the
   8 .\" GNU General Public License as published by the "Free Software
   9  \" Foundation", version\~2.
  10 .\"
  11 .\" The license text is available in the internet at
  12 .\" <http://www.gnu.org/licenses/gpl-2.0.html>
  13 .\"
  14 .PAPER      A4
  15 .\" Reference macros (metadata)
  16 .TITLE     "Producing PDFs" "with groff and mom"
  17 .PDF_TITLE "\*[$TITLE]
  18 .AUTHOR    "\v'-.5v'\*[UP 4p]Deri James" \
  19            "\v'-.5v'\*[UP 8p]and" \
  20            "\v'-.5v'\*[UP 11p]Peter Schaffter"
  21 .MISC      "This file is part of groff." \
  22            ".sp .25v" \
  23            "groff is free software; you can redistribute it" \
  24            "and\*[FU3]/or modify it under the terms of the GNU" \
  25            "General Public License as published by the" \
  26            "Free Software Foundation, either version 3" \
  27            "of the License, or (at your option) any later" \
  28            "version." \
  29            ".sp .25v" \
  30            "You should have received a copy of the GNU" \
  31            "General Public License along with this program." \
  32            "If not, see:" \
  33            ".sp .25v" \
  34            ".IL 2P" \
  35            ".PDF_WWW_LINK http://www.gnu.org/licenses/" \
  36            ".IQ CLEAR"
  37 .COPYRIGHT "20\*[BU3]1\*[BU2]2 Free Software Foundation
  38 .ATTRIBUTE_STRING ""  \" Don't print 'by'
  39 .PDF_BOOKMARKS_OPEN 2
  40 .\" Cover and page header
  41 .COVER       TITLE AUTHOR COPYRIGHT MISC
  42 .HEADER_LEFT "James, Schaffter"
  43 .\" Page, style, formatting
  44 .PRINTSTYLE TYPESET
  45 .L_MARGIN   2.5c
  46 .R_MARGIN   2.5c
  47 .B_MARGIN   2.5c
  48 .\"
  49 .FAM      H
  50 .FT       R
  51 .PT_SIZE  10.5
  52 .AUTOLEAD 3
  53 .PARA_INDENT 0  \" Because we're spacing paragraphs.
  54 .\"
  55 .COVER_LEAD     +3.5
  56 .DOCHEADER_LEAD +3.5
  57 .\" Color for code snippets
  58 .NEWCOLOUR dark-grey RGB #343434
  59 .\" Make QUOTE look like CODE
  60 .QUOTE_FAMILY C
  61 .QUOTE_FONT   B
  62 .QUOTE_SIZE   +1.5
  63 .QUOTE_COLOR  dark-grey
  64 .QUOTE_INDENT 9p
  65 .\"
  66 .CODE_FONT  B
  67 .CODE_SIZE  115
  68 .CODE_COLOR dark-grey
  69 .CONDENSE   87
  70 .\"
  71 .HEADING_STYLE 1 NUMBER FONT B SIZE +1 BASELINE_ADJUST \n[.v]/5
  72 .HEADING_STYLE 2 NUMBER FONT I SIZE +.25 BASELINE_ADJUST \n[.v]/5
  73 .\"
  74 .FOOTNOTE_SIZE -1
  75 .\" Character definitions for program names, opts, etc.
  76 .char \[ghostscript]      \*[BD]ghostscript\*[PREV]
  77 .char \[groff]            \*[BD]groff\*[PREV]
  78 .char \[gropdf]           \*[BD]gropdf\*[PREV]
  79 .char \[grops]            \*[BD]grops\*[PREV]
  80 .char \[man]              \*[BD]man\*[PREV]
  81 .char \[-mom]             \*[BD]-mom\*[PREV]
  82 .char \[mom]              \*[BD]mom\*[PREV]
  83 .char \[-mpdfmark]        \*[BD]-mpdfmark\*[PREV]
  84 .char \[ms]               \*[BD]ms\*[PREV]
  85 .char \[pdfmom]           \*[BD]pdfmom\*[PREV]
  86 .char \[pdfroff]          \*[BD]pdfroff\*[PREV]
  87 .char \[-P-e]             \*[BD]-P-e\*[PREV]
  88 .char \[-P-p<papersize>]  \*[BD]-P-p<papersize>\*[PREV]
  89 .char \[ps2pdf]           \*[BD]ps2pdf\*[PREV]
  90 .char \[psselect]         \*[BD]psselect\*[PREV]
  91 .char \[-T]               \*[BD]-T\*[PREV]
  92 .char \[-Tpdf]            \*[BD]-Tpdf\*[PREV]
  93 .char \[-Tps]             \*[BD]-Tps\*[PREV]
  94 .\" Strings for inline code
  95 .ds cod  "\E*[CODE]\&\E*[COND]
  96 .ds codx "\E*[CONDX]\E*[CODE off]\&
  97 .\" Paragraph spacing
  98 .de PP2
  99 . ALD .3v
 100 . PP
 101 ..
 102 .\" Wrapper around QUOTE
 103 .de COD
 104 . QUOTE
 105 . nop \*[COND]\\$*\*[CONDX]
 106 . QUOTE OFF
 107 ..
 108 .\" Note box
 109 .de BOX-NOTE
 110 . ie \\n[#NUM_ARGS]=1 .DBX .5 0 \\n[.l]u \\$1
 111 . el .DBX .5 0 \\$1 \\$2
 112 . ALD 15p
 113 . IB 6p
 114 ..
 115 .\" Table of contents
 116 .TOC_PADDING 2
 117 .SPACE_TOC_ITEMS
 118 .AUTO_RELOCATE_TOC
 119 .TOC_ENTRY_STYLE 2 FONT I
 120 .TOC_LEAD 14
 121 .\"
 122 .DOCHEADER_ADVANCE 5c \" Begin this distance down from top of page
 123 .\"
 124 .START
 125 .\"
 126 .HEADING 1 NAMED intro "Introduction"
 127 .PP
 128 .RW .12
 129 PDF documents are intended to be "electronic paper,\*[BU6]" and, as
 130 such, take advantage of the digital medium in ways that PostScript
 131 documents do not.  Chief amongst these are clickable links that
 132 point to named destinations, either within the documents themselves
 133 .PDF_LINK internal PREFIX ( SUFFIX ) "internal links"
 134 or to remote web pages
 135 .PDF_LINK external PREFIX ( SUFFIX ), "external links"
 136 and the generation of a clickable document outline that appears in
 137 the Contents panel of most PDF viewers.
 138 .PP2
 139 .RW .01
 140 Using \[groff] and \[mom] to produce PDF documents results in the
 141 automatic generation of clickable document outlines (discussed
 142 below,
 143 .PDF_LINK outline SUFFIX ), +
 144 and, if the \*[cod]TOC\*[codx] macro is included in the source file,
 145 entries in the printable table of contents can be clicked on as well
 146 when the document is viewed at the screen (see
 147 .PDF_LINK toc SUFFIX ). +
 148 .RW 0
 149 .HEADING 1 NAMED generating "Using groff to generate PDF files"
 150 .PP
 151 Groff provides more than one way to generate PDF documents from
 152 files formatted with the \[mom] macros.  One is to call \[groff]
 153 directly, either with
 154 .COD "groff [-Tps] -mom -m pdfmark doc.mom | ps2pdf - doc.pdf
 155 which pipes output from the \[grops] PostScript driver through
 156 \[ps2pdf], or
 157 .COD "groff -Tpdf -mom doc.mom > doc.pdf
 158 which uses the native PDF driver, \[gropdf].  Alternatively, one may
 159 call the wrapper
 160 .COD "pdfroff -mom -mpdfmark --no-toc doc.mom > doc.pdf
 161 A fourth, preferred method is to use
 162 .PDF_LINK pdfmom SUFFIX , "\[pdfmom]"
 163 which is strongly recommended since it implements the full range
 164 of PDF features available in \[mom].
 165 .COD "pdfmom doc.mom > doc.pdf
 166 One reason to prefer using the native PDF driver (via \[pdfmom] or
 167 \[-Tpdf]) is that papersizes set within mom source files (see
 168 .PDF_WWW_LINK http://www.schaffter.ca/mom/momdoc/typesetting.html#page-setup-intro SUFFIX ) \
 169   "paper and page setup macros"
 170 do not require a corresponding \[-P-p<papersize>] flag on the
 171 command line.
 172 .PP2
 173 There are other minor differences between the methods, discussed
 174 .PDF_LINK pdf-diff SUFFIX . "here"
 175 .RW 0
 176 .HEADING 1 NAMED links "Creating PDF links with mom"
 177 .PP
 178 Often, but not always, links in the body of a PDF document point
 179 to headings elsewhere in the same document.  Creating these links
 180 is a simple process.  First, identify the places to link to
 181 ("destinations"), then link to them from any place in the document.
 182 .NO_SHIM
 183 .HEADING 2 NAMED naming "Creating destination points at headings"
 184 .PP
 185 The first step in creating links to a heading is to give the
 186 heading a unique destination name.  With mom, this is done by
 187 adding \*[cod]NAMED\|<id>\*[codx] to the HEADING macro, where
 188 \*[cod]<id>\*[codx] is a unique identifier for the heading.  For
 189 example,
 190 .PDF_TARGET intro-ex
 191 .COD "\&.HEADING 1 NAMED intro \[dq]Introduction\[dq]"
 192 would, in addition to printing the head in the body of the document,
 193 identify the introduction by the unique id, "intro"\*[BU6].  This
 194 id, or name, can then be used to create links to the introduction
 195 from any part of the document.
 196 .PP2
 197 Furthermore, \*[cod]NAMED\|<id>\*[codx] stores the text of the
 198 heading for use later on when linking to it (see
 199 .PDF_LINK internal SUFFIX ). +
 200 If headings are being numbered, the heading number is prepended.
 201 .HEADING 2 NAMED target  "Creating destination points at arbitrary locations"
 202 .PP
 203 Any part of a document can be a link destination, not just headings.
 204 For example, say you create a table that needs to be referred to
 205 from other parts of the document.  You'd identify the location of
 206 the table by placing
 207 .COD "\&.PDF_TARGET <id> \[dq]<text>\[dq]"
 208 just above the table in the source file.  As with
 209 \*[cod]HEADING\*[codx], \*[cod]<id>\*[codx] is any unique name.
 210 \*[cod]<text>\*[codx] is optional. \*[cod]<id>\*[codx] can now be linked
 211 to from anywhere in the document.
 212 .HEADING 2 NAMED internal "Creating internal links"
 213 .PP
 214 Internal links are clickable text areas that allow you to jump to
 215 named destinations within a document.  (See
 216 .PDF_LINK external "here"
 217 for a description of external links.)
 218 .PP2
 219 Internal links are created with the macro \*[cod]PDF_LINK\*[codx],
 220 which takes the form
 221 .COD "\&.PDF_LINK <id> [PREFIX <text>] [SUFFIX <text>] \
 222 \[dq]<hotlink text>\[dq]"
 223 where \*[cod]<id>\*[codx] is a named destination point elsewhere in
 224 the document (see
 225 .PDF_LINK naming +
 226 and
 227 .PDF_LINK target SUFFIX ). +
 228 .PP2
 229 \*[cod]PREFIX\|<text>\*[codx] and \*[cod]SUFFIX\|<text>\*[codx], both or
 230 either of which are optional, are printed around the clickable area
 231 but do not form part of the link itself.
 232 .PP2
 233 \*[cod]<hotlink text>\*[codx] is the text that should be clickable,
 234 identifiable in the PDF document by the colour assigned to links
 235 (see
 236 .PDF_LINK colour SUFFIX ). +
 237 .PDF_TARGET expando
 238 .PP2
 239 If the hotlink text ends in \*[cod]\[dq]*\[dq]\*[codx]\*[BU9],
 240 the asterisk is replaced by the text of the destination
 241 point, assuming it's a heading.  If the hotlink text ends in
 242 \*[cod]\[dq]+\[dq]\*[codx]\*[BU9], the replacement text is surrounded
 243 by quotes.
 244 .PP2
 245 Using our
 246 .PDF_LINK intro-ex SUFFIX , "HEADING example"
 247 .RW .1
 248 above, the following invocation of \*[cod]PDF_LINK\*[codx] would
 249 produce a click\%able link to the introduction:
 250 .COD "\&.PDF_LINK intro PREFIX ( SUFFIX ). \[dq]see: +\[dq]"
 251 .RW 0
 252 In the text, the link would look like this:
 253 .PDF_LINK intro PREFIX ( SUFFIX ). "see: +"
 254 .HEADING 2 NAMED external "Creating external links"
 255 .PP
 256 External links are clickable text areas whose destination is a
 257 URL.  Clicking on them causes a browser window to pop up with the
 258 destination address.
 259 .PP2
 260 The format of the macro to create external links is similar to the
 261 one for creating internal links:
 262 .COD "\&.PDF_WWW_LINK <url> [PREFIX <text>] [SUFFIX <text>] [\[dq]<hotlink text>\[dq]]"
 263 \*[cod]<url>\*[codx] is any valid URL, usually a web address;
 264 \*[cod]PREFIX\|<text>\*[codx] and \*[cod]SUFFIX\|<text>\*[codx] have
 265 exactly the same meaning, as does \*[cod]<hotlink text>\*[codx],
 266 which furthermore accepts the same expandos, \*[cod]\[dq]+\[dq]\*[codx] and
 267 \*[cod]\[dq]*\[dq]\*[codx].
 268 .PP2
 269 .RW .1
 270 If no hotlink text is given, then \*[cod]<url>\*[codx] is
 271 used as the text.  If hotlink text is given and ends in
 272 \*[cod]\[dq]*\[dq]\*[codx]\*[BU9], the asterisk is replaced by the
 273 URL.  If it ends in \*[cod]\[dq]+\[dq]\*[codx]\*[BU9], the URL is
 274 surrounded by quotes.  As an example,
 275 .RW 0
 276 .COD "\&.PDF_WWW_LINK http://www.schaffter.ca/mom/momdoc/toc.html
 277 would open mom's online documentation at
 278 .PDF_WWW_LINK http://www.schaffter.ca/mom/momdoc/toc.html SUFFIX "."
 279 The same, with \*[cod]\[dq]here\[dq]\*[codx] supplied as
 280 hotlink text, lets you click
 281 .PDF_WWW_LINK http://www.schaffter.ca/mom/momdoc/toc.html "here"
 282 instead.
 283 .HEADING 2 NAMED colour  "Assigning a colour to links"
 284 .PP
 285 The colour of links is set with
 286 .COD "\&.PDF_LINK_COLOR <xcolor> | <newcolor> | <r g b> | <#rrggbb>
 287 where \*[cod]<xcolor>\*[codx] or \*[cod]<newcolor>\*[codx] are the names
 288 of colours already initialized with
 289 .PDF_WWW_LINK http://www.schaffter.ca/mom/momdoc/color.html#xcolor "XCOLOR"
 290 or
 291 .PDF_WWW_LINK http://www.schaffter.ca/mom/momdoc/color.html#newcolor SUFFIX . "NEWCOLOR"
 292 If you prefer to define a new colour (using the RGB colour scheme),
 293 enter it either as 3 numbers between
 294 0.0 \*[UP 1p]\[->]\*[DOWN 1p] 1\*[BU4].0
 295 or as a 6 character hex string.  Thus
 296 .SP .5v
 297 \*[FWD 6p]\*[cod].PDF_LINK_COLOR #ff0000\*[codx]
 298 \ \*[SIZE -.5]and\*[SIZE]\ \"
 299 \*[cod].PDF_LINK_COLOR 1.0 0 0\*[codx]
 300 .SP .5v
 301 both lead to mom using
 302 .PDF_LINK_COLOR 1 0 0
 303 .PDF_LINK colour red
 304 .PDF_LINK_COLOR
 305 links.
 306 .PP2
 307 The default colour can be restored by calling
 308 \*[cod]PDF_LINK_COLOR\*[codx] with no parameter.
 309 .FLOAT
 310 .JUSTIFY
 311 .BOX-NOTE 3P
 312 \*[BD]Note:\*[PREV]
 313 The decimal scheme for creating colours must be used if a file is to
 314 be processed with
 315 \[oq]\[groff]\~\[-Tps]\~\[-mpdfmark]\[cq],
 316 \[oq]\[pdfroff]\[cq], or
 317 \[oq]\[pdfmom]\~\[-Tps]\[cq].
 318 .IBQ
 319 .FLOAT off
 320 .NO_SHIM off
 321 .HEADING 1 NAMED outline "The PDF Outline"
 322 .PP
 323 Most PDF viewers provide a panel that displays a document's outline,
 324 similar to a table of contents.  Clicking on an entry navigates
 325 directly to the appropriate place in the document.
 326 .PP2
 327 Mom generates PDF outlines the same way she populates
 328 her own table of contents: by intercepting calls to the
 329 \*[cod]HEADING\*[codx] macro, as well as to the various title
 330 and chapter macros used in namimg documents, and allocating each a
 331 hierarchic level.
 332 .PP2
 333 Covers, titles/chapters, and the table of contents are all
 334 assigned to level 1\*[BU5].  Subsequent headings are assigned to
 335 n\*[UP 1p]+\*[DOWN 1p]\*[BU4]1, where n is the level given to
 336 \*[cod]HEADING\*[codx].
 337 .PP2
 338 .RW .22
 339 The PDF outline can sensibly recover from skipped or omitted heading
 340 levels; the printed table of contents cannot.  Users are therefore
 341 advised to use headings in logical order, not for typographic
 342 effects.
 343 .RW 0
 344 .HEADING 2 NAMED open-close "Opening and closing levels
 345 .PP
 346 A level is said to be open if one or more levels beneath it is
 347 visible in the PDF outline.  Closed \%levels have at least one level
 348 beneath them that is not visible unless the closed link is clicked.
 349 It is common for only the first two levels to be open so the outline
 350 doesn't look cluttered.
 351 .PP2
 352 To establish which levels should be open by default when a document
 353 loads, use
 354 .COD "\&.PDF_BOOKMARKS_OPEN n
 355 where \*[cod]n\*[codx] is a number specifying at which level all
 356 subsequent ones should be closed.
 357 .PP2
 358 If, at any point in the document, you specify
 359 .COD "\&.PDF_BOOKMARKS_OPEN NO  \e\[dq] or any other text argument
 360 then all subsequent bookmarks will be closed until
 361 \*[cod]PDF_BOOKMARKS_OPEN\*[codx] opens them again.
 362 .HEADING 2 NAMED disabling "Suspending/disabling collection of outline entries
 363 .PP
 364 Suspending the collection of entries for the PDF outline is
 365 accomplished with
 366 .COD "\&.PDF_BOOKMARKS OFF
 367 Mom's default is to collect entries, so if the command is placed at
 368 the start of a document, it \%disables entry collection completely.
 369 Elsewhere, it suspends collection until you re-enable it with
 370 .COD "\&.PDF_BOOKMARKS  \e\[dq] i.e. with no parameter
 371 .HEADING 2 NAMED pdf:title "The PDF window title"
 372 .PP
 373 While not strictly part of the PDF outline, the title of a document
 374 can be displayed as the document viewer's window title.  The macro
 375 to accomplish this is
 376 .COD "\&.PDF_TITLE\ \[dq]<window title>\[dq]
 377 It can take any text, so the viewer window title need not be the
 378 same as the document's title.
 379 .FLOAT
 380 .JUSTIFY
 381 .BOX-NOTE 4P+8p
 382 \*[BD]Note:\*[PREV] The macro, \*[cod]DOC_TITLE\*[codx], always
 383 invokes \*[cod]PDF_TITLE\*[codx].  If this is not what you want, you
 384 can remove the window title by issuing
 385 .COD ".PDF_TITLE \[dq]\[dq] \e\[dq] ie. with a blank argument
 386 .IBQ
 387 .FLOAT off
 388 .NO_SHIM
 389 .HEADING 1 NAMED toc "Tables of Contents"
 390 .RLD .5v
 391 .HEADING 2 NAMED toc:gen "Generating a Table of Contents
 392 .PP
 393 .RW .1
 394 To generate a printable Table of Contents for any document, simply
 395 insert the macro, \*[cod]TOC\*[codx], as the last line of the source
 396 file. (Formatting of the printable Table of Contents is discussed in
 397 detail in the
 398 .PDF_WWW_LINK \
 399 http://www.schaffter.ca/mom/momdoc/tables-of-contents.html#top \
 400 SUFFIX ). "mom documentation"
 401 When the file is processed and loaded in a viewer, entries in the
 402 Table of Contents will be clickable links.
 403 .RW 0
 404 .PP2
 405 Whichever link colour is active at the end of the document, prior to
 406 \*[cod]TOC\*[codx], will be used for the \%Table of Contents
 407 links.
 408 .HEADING 2 NAMED toc:pos  "Positioning the Table of Contents"
 409 .PP
 410 If \[groff]'s PostScript device (\[-Tps]) is used to process a mom
 411 file, the Table of Contents is printed at the end of the document.
 412 When this is not desirable, the PostScript output from \[groff]
 413 must be processed with \[psselect] in order to place the TOC in the
 414 preferred location.
 415 .PP2
 416 When using mom and \[groff]'s native pdf device (via \[pdfmom] or
 417 \[groff] \[-Tpdf]), positioning of the Table of Contents can be done
 418 within the source file.
 419 .PP2
 420 The command to control the placement of the TOC is
 421 .COD "\&.AUTO_RELOCATE_TOC [<position>]
 422 where the optional \*[cod]<position>\*[codx] can be one of these
 423 keywords:
 424 .LEFT
 425 .IL 2P
 426 .SP .25v
 427 \*[SIZE -.7]TOP\*[FU2]\*[UP .5p]\c
 428 .FOOTNOTE
 429 \*[BD]Note:\*[PREV] Documents without a COVER or DOC_COVER require
 430 the \*[cod]TOP\*[codx] argument.
 431 .FOOTNOTE off
 432 \*[IT]\*[SIZE +.2]\
 433 (ie. at the very start of the document)\*[SIZE -.2]\*[PREV]
 434 BEFORE_DOCCOVER
 435 AFTER_DOCCOVER
 436 BEFORE_COVER
 437 AFTER_COVER\*[SIZE]
 438 .SP .25v
 439 .ILQ
 440 .JUSTIFY
 441 It is normally not necessary to supply a keyword, since
 442 \*[cod]AUTO_RELOCATE_TOC\*[codx] places the TOC after the DOC_COVER,
 443 if there is one, or the first COVER when no DOC_COVER is present.
 444 .NO_SHIM off
 445 In rare instances where it is desirable to place the TOC somewhere
 446 else in the document, there are two low-level commands,
 447 .SP .5v
 448 \*[FWD 6p]\*[cod].TOC_BEFORE_HERE\*[codx]
 449 \ \*[SIZE -.5]and\*[SIZE]\ \"
 450 \*[cod].TOC_AFTER_HERE\*[codx]
 451 .SP .5v
 452 which place the TOC either before or after the current page.
 453 .PP2
 454 These last two commands have a small catch: although the TOC will
 455 appear where specified, the \%"Contents" entry in the PDF outline,
 456 which observes a hierarchy of levels, will assign the TOC to
 457 level\~\*[BU4]1\*[BU4], possibly disrupting the visual ordering of
 458 levels in the outline.
 459 .HEADING 1 NAMED simplify "pdfmom: Simplifying PDF output"
 460 .PP
 461 As explained in the section
 462 .PDF_LINK generating SUFFIX , *
 463 .RW .15
 464 there are two established methods
 465 .RW 0
 466 for creating PDF files with \[groff]: the original method, ie.
 467 passing the \[-Tps] and \[-mpdfmark] options to \[groff] (or using
 468 \[pdfroff], which does this for you); or the newer \[-Tpdf], which
 469 produces PDF files natively.
 470 .NO_SHIM
 471 .HEADING 2 NAMED fwd:ref "The problem of forward references"
 472 .PP
 473 .EW .2
 474 Both methods encounter difficulties when dealing with forward
 475 references; that is, when a link \*[IT]\%earlier\/\*[PREV] in a
 476 document refers to a destination \*[IT]later\/\*[PREV] in the
 477 document and the link text terminates
 478 .EW 0
 479 with one of the expandos,
 480 \*[cod]\[dq]*\[dq]\*[codx] or \*[cod]\[dq]+\[dq]\*[codx]
 481 (explained
 482 .PDF_LINK expando SUFFIX ). "here"
 483 Mom doesn't know what text to put in the expando because it has not
 484 yet been defined.  This means that \[groff] must be run multiple
 485 times to find the unknown text.
 486 .PP2
 487 .EW .2
 488 The program \[pdfroff] exists to handle these multiple runs, but it
 489 imposes some limitations on the PDF features available with \[mom].
 490 .EW 0
 491 .HEADING 2 NAMED pdfmom "pdfmom"
 492 .PP
 493 \[pdfmom] performs the same function as \[pdfroff], and is the
 494 preferred, trouble-free way to generate PDF documents from a mom
 495 source file.  Like \[pdfroff], it is a frontend to \[groff] and
 496 accepts all the same options (see \[man]\~\[groff]).
 497 .PP2
 498 .EW .2
 499 Called as-is, \[pdfmom] accepts all the same options as \[groff],
 500 and requires no additional flags.  PDF generation is performed by
 501 \[gropdf], \[groff]'s native PDF driver:
 502 .EW 0
 503 .COD "pdfmom doc.mom [groff opts] > doc.pdf
 504 If a \[-Tps] option is supplied, \[pdfmom] hands control over to
 505 \[pdfroff], and both \[groff] and \[pdfroff] options may given.
 506 The resulting PDF is produced from PostScript output fed into
 507 \[ghostscript].
 508 .COD "pdfmom -Tps [pdfroff opts [groff opts]] doc.mom > doc.pdf
 509 For either invocation, it is not necessary to add \[-mom] or
 510 \[-mpdfmark], as these are implied.
 511 .PP2
 512 If Encapsulated PostScript or plain PostScript images have been
 513 embedded in a document with
 514 .PDF_WWW_LINK http://www.schaffter.ca/mom/momdoc/images.html#pspic SUFFIX , \
 515   "PSPIC"
 516 the \[-Tps] option must be used.  In most other cases, \[pdfmom]
 517 with no \[-T] flag is preferable.
 518 .HEADING 2 NAMED papersize "Setting papersize within a source file"
 519 A significant convenience afforded by using \[pdfmom] (or \[groff]
 520 with the \[-Tpdf] flag) is that papersizes or page dimensions set
 521 within mom source files (see
 522 .PDF_WWW_LINK http://www.schaffter.ca/mom/momdoc/typesetting.html#page-setup-intro \
 523   SUFFIX ) "paper and page setup macros"
 524 do not require a corresponding \[-P-p<papersize>] option on the
 525 command line.  It is even possible to create documents with
 526 unequal-sized pages.
 527 .HEADING 2 NAMED pdf-diff \
 528 "Differences between pdfmom and pdfroff"
 529 .PP
 530 Several features described in this manual are not available when
 531 using \[pdfmom] with the \[-Tps] option, or when using \[pdfroff], or
 532 \[groff]\~\[-Tps]\~\[-mpdfmark].
 533 .SP .25v
 534 .QUAD LEFT
 535 .HYPHENATION off
 536 .IB 16p
 537 .LIST
 538 .ITEM
 539 .PDF_LINK toc:pos "Relocation of the Table of Contents"
 540 is not supported.  The TOC appears at the end of the document;
 541 \[psselect] must be used to re-order pages.
 542 .ITEM
 543 If a link crosses a page boundary, it will stop being a clickable
 544 hotspot on subsequent pages.
 545 .ITEM
 546 When establishing whether PDF outline levels are
 547 .PDF_LINK open-close SUFFIX , "open or closed"
 548 only the numerical parameter to \*[cod]PDF_BOOKMARKS_OPEN\*[codx] has
 549 any effect.
 550 .ITEM
 551 .PDF_LINK colour "PDF_LINK_COLOR"
 552 only accepts colour definitions in decimal notation.
 553 .LIST OFF
 554 .IQ
 555 .HEADING 1 \
 556 "Comparison of -Tps\*[FU4]/\*[FU2]-mpdfmark with -Tpdf\*[FU4]/\*[FU2]-mom
 557 .SP .25v
 558 .IB
 559 \[-Tps]\*[FU4]/\*[FU2]\[-mpdfmark]
 560 .LIST
 561 .SHIFT_LIST 1P+6p
 562 .ITEM
 563 does not support all the features described here
 564 .ITEM
 565 accepts images and graphics embedded with PSPIC
 566 .ITEM
 567 is mature and well-tested code
 568 .LIST OFF
 569 .IQ
 570 .ALD .4v
 571 .IB
 572 \[-Tpdf]\*[FU4]/\*[FU2]\[-mom]
 573 .LIST
 574 .SHIFT_LIST 1P+6p
 575 .ITEM
 576 facilitates embedding fonts directly in the PDF file (if the
 577 \[-P-e] flag is given on the command line)
 578 .ITEM
 579 sets papersize from within the source file, circumventing the need
 580 for the papersize flag (\[-P-p<papersize>]) on the command line
 581 .ITEM
 582 is not compatible with
 583 .PDF_WWW_LINK \
 584   http://www.schaffter.ca/mom/momdoc/docprocessing.html#printstyle \
 585   "PRINTSTYLE TYPEWRITE"
 586 underlining (eg of italics)
 587 .ITEM
 588 generally produces larger files; these can be reduced by piping
 589 the output through \[ps2pdf]\*[B]
 590 .RLD .5v
 591 .FLOAT
 592 .QUAD LEFT
 593 .BR_AT_LINE_KERN
 594 .IQ
 595 .BOX-NOTE (\n[.l]u-6P) 3P
 596 .EW .3
 597 \*[BD]Note:\*[PREV] Owing to a known bug, PDF files piped
 598 through \[ps2pdf] lose some of
 599 .EW 0
 600 their metadata, notably the window title set with
 601 \*[cod]PDF_TITLE\*[codx].
 602 .FLOAT off
 603 .ITEM
 604 is newer code with less testing\c
 605 .EL
 606 .LIST OFF
 607 .IQ CLEAR
 608 .TOC