contrib/mom/examples/mom-pdf.mom

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