OpenSystemsDevelopment / qpdf

Commit 78206a465176ae7748b2aa34a3ceda8d5aea6503

Authored by Jay Berkenbilt
1 parent f721fed9

Prepare for docbook -> rst: protect some XML elements 

Pandoc docbook -> rst fails to convert the following elements, so
change them to @1@tag@1@ ... @2@tag@2@ for later processing. This way,
they will survive the conversion, and we can deal with them later.

<application>
<command>
<filename>
<firstterm>
<option>
<replaceable>
Inline Side-by-side
Showing 1 changed file with 743 additions and 743 deletions
manual/qpdf-manual.xml
  View file @78206a4
... ... @@ -107,8 +107,8 @@
107 107 <title>Building and Installing QPDF</title>
108 108 <para>
109 109 This chapter describes how to build and install qpdf. Please see
110   - also the <filename>README.md</filename> and
111   - <filename>INSTALL</filename> files in the source distribution.
  110 + also the @1@filename@1@README.md@2@filename@2@ and
  111 + @1@filename@1@INSTALL@2@filename@2@ files in the source distribution.
112 112 </para>
113 113 <sect1 id="ref.prerequisites">
114 114 <title>System Requirements</title>
... ... @@ -162,8 +162,8 @@
162 162 url="http://www.gnu.org/software/diffutils/">http://www.gnu.org/software/diffutils/</ulink>
163 163 is required to run the test suite. Note that this is the
164 164 version of diff present on virtually all GNU/Linux systems.
165   - This is required because the test suite uses <command>diff
166   - -u</command>.
  165 + This is required because the test suite uses @1@command@1@diff
  166 + -u@2@command@2@.
167 167 </para>
168 168 </listitem>
169 169 </itemizedlist>
... ... @@ -182,8 +182,8 @@
182 182 contents of PDF files. If you are making deep changes to the
183 183 library that cause changes in the contents of the files that qpdf
184 184 generates, then you should enable the image comparison tests.
185   - Enable them by running <command>configure</command> with the
186   - <option>--enable-test-compare-images</option> flag. If you enable
  185 + Enable them by running @1@command@1@configure@2@command@2@ with the
  186 + @1@option@1@--enable-test-compare-images@2@option@2@ flag. If you enable
187 187 this, the following additional requirements are required by the
188 188 test suite. Note that in no case are these items required to use
189 189 qpdf.
... ... @@ -223,23 +223,23 @@
223 223 <programlisting>./configure
224 224 make
225 225 </programlisting>
226   - You can also run <command>make check</command> to run the test
227   - suite and <command>make install</command> to install. Please run
228   - <command>./configure --help</command> for options on what can be
  226 + You can also run @1@command@1@make check@2@command@2@ to run the test
  227 + suite and @1@command@1@make install@2@command@2@ to install. Please run
  228 + @1@command@1@./configure --help@2@command@2@ for options on what can be
229 229 configured. You can also set the value of
230 230 <varname>DESTDIR</varname> during installation to install to a
231 231 temporary location, as is common with many open source packages.
232   - Please see also the <filename>README.md</filename> and
233   - <filename>INSTALL</filename> files in the source distribution.
  232 + Please see also the @1@filename@1@README.md@2@filename@2@ and
  233 + @1@filename@1@INSTALL@2@filename@2@ files in the source distribution.
234 234 </para>
235 235 <para>
236 236 Building on Windows is a little bit more complicated. For
237   - details, please see <filename>README-windows.md</filename> in the
  237 + details, please see @1@filename@1@README-windows.md@2@filename@2@ in the
238 238 source distribution. You can also download a binary distribution
239 239 for Windows. There is a port of qpdf to Visual C++ version 6 in
240   - the <filename>contrib</filename> area generously contributed by
  240 + the @1@filename@1@contrib@2@filename@2@ area generously contributed by
241 241 Jian Ma. This is also discussed in more detail in
242   - <filename>README-windows.md</filename>.
  242 + @1@filename@1@README-windows.md@2@filename@2@.
243 243 </para>
244 244 <para>
245 245 While <type>wchar_t</type> is part of the C++ standard, qpdf uses
... ... @@ -253,11 +253,11 @@ make
253 253 </para>
254 254 <para>
255 255 There are some other things you can do with the build. Although
256   - qpdf uses <application>autoconf</application>, it does not use
257   - <application>automake</application> but instead uses a
  256 + qpdf uses @1@application@1@autoconf@2@application@2@, it does not use
  257 + @1@application@1@automake@2@application@2@ but instead uses a
258 258 hand-crafted non-recursive Makefile that requires gnu make. If
259 259 you're really interested, please read the comments in the
260   - top-level <filename>Makefile</filename>.
  260 + top-level @1@filename@1@Makefile@2@filename@2@.
261 261 </para>
262 262 </sect1>
263 263 <sect1 id="ref.crypto">
... ... @@ -284,41 +284,41 @@ make
284 284 <para>
285 285 When building with qpdf's build system, crypto providers can be
286 286 enabled at build time using various
287   - <command>./configure</command> options. The default behavior is
288   - for <command>./configure</command> to discover which crypto
  287 + @1@command@1@./configure@2@command@2@ options. The default behavior is
  288 + for @1@command@1@./configure@2@command@2@ to discover which crypto
289 289 providers can be supported based on available external libraries,
290 290 to build all available crypto providers, and to use an external
291 291 provider as the default over the native one. This behavior can be
292 292 changed with the following flags to
293   - <command>./configure</command>:
  293 + @1@command@1@./configure@2@command@2@:
294 294 <itemizedlist>
295 295 <listitem>
296 296 <para>
297   - <option>--enable-crypto-<replaceable>x</replaceable></option>
298   - (where <replaceable>x</replaceable> is a supported crypto
299   - provider): enable the <replaceable>x</replaceable> crypto
  297 + @1@option@1@--enable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@
  298 + (where @1@replaceable@1@x@2@replaceable@2@ is a supported crypto
  299 + provider): enable the @1@replaceable@1@x@2@replaceable@2@ crypto
300 300 provider, requiring any external dependencies it needs
301 301 </para>
302 302 </listitem>
303 303 <listitem>
304 304 <para>
305   - <option>--disable-crypto-<replaceable>x</replaceable></option>:
306   - disable the <replaceable>x</replaceable> provider, and do not
  305 + @1@option@1@--disable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@:
  306 + disable the @1@replaceable@1@x@2@replaceable@2@ provider, and do not
307 307 link against its dependencies even if they are available
308 308 </para>
309 309 </listitem>
310 310 <listitem>
311 311 <para>
312   - <option>--with-default-crypto=<replaceable>x</replaceable></option>:
313   - make <replaceable>x</replaceable> the default provider even if
  312 + @1@option@1@--with-default-crypto=@1@replaceable@1@x@2@replaceable@2@@2@option@2@:
  313 + make @1@replaceable@1@x@2@replaceable@2@ the default provider even if
314 314 a higher priority one is available
315 315 </para>
316 316 </listitem>
317 317 <listitem>
318 318 <para>
319   - <option>--disable-implicit-crypto</option>: only build crypto
  319 + @1@option@1@--disable-implicit-crypto@2@option@2@: only build crypto
320 320 providers that are explicitly requested with an
321   - <option>--enable-crypto-<replaceable>x</replaceable></option>
  321 + @1@option@1@--enable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@
322 322 option
323 323 </para>
324 324 </listitem>
... ... @@ -327,19 +327,19 @@ make
327 327 <para>
328 328 For example, if you want to guarantee that the gnutls crypto
329 329 provider is used and that the native provider is not built, you
330   - could run <command>./configure --enable-crypto-gnutls
331   - --disable-implicit-crypto</command>.
  330 + could run @1@command@1@./configure --enable-crypto-gnutls
  331 + --disable-implicit-crypto@2@command@2@.
332 332 </para>
333 333 <para>
334 334 If you build qpdf using your own build system, in order for qpdf
335 335 to work at all, you need to enable at least one crypto provider.
336   - The file <filename>libqpdf/qpdf/qpdf-config.h.in</filename>
  336 + The file @1@filename@1@libqpdf/qpdf/qpdf-config.h.in@2@filename@2@
337 337 provides macros <literal>DEFAULT_CRYPTO</literal>, whose value
338 338 must be a string naming the default crypto provider, and various
339 339 symbols starting with <literal>USE_CRYPTO_</literal>, at least
340 340 one of which has to be enabled. Additionally, you must compile
341 341 the source files that implement a crypto provider. To get a list
342   - of those files, look at <filename>libqpdf/build.mk</filename>. If
  342 + of those files, look at @1@filename@1@libqpdf/build.mk@2@filename@2@. If
343 343 you want to omit a particular crypto provider, as long as its
344 344 <literal>USE_CRYPTO_</literal> symbol is undefined, you can
345 345 completely ignore the source files that belong to a particular
... ... @@ -354,16 +354,16 @@ make
354 354 <literal>"native"</literal>. Then you must include the source
355 355 files used in the native implementation, some of which were added
356 356 or renamed from earlier versions, to your build, and you can
357   - ignore <filename>QPDFCrypto_gnutls.cc</filename>. Always consult
358   - <filename>libqpdf/build.mk</filename> to get the list of source
  357 + ignore @1@filename@1@QPDFCrypto_gnutls.cc@2@filename@2@. Always consult
  358 + @1@filename@1@libqpdf/build.mk@2@filename@2@ to get the list of source
359 359 files you need to build.
360 360 </para>
361 361 </sect2>
362 362 <sect2 id="ref.crypto.runtime">
363 363 <title>Runtime Crypto Provider Selection</title>
364 364 <para>
365   - You can use the <option>--show-crypto</option> option to
366   - <command>qpdf</command> to get a list of available crypto
  365 + You can use the @1@option@1@--show-crypto@2@option@2@ option to
  366 + @1@command@1@qpdf@2@command@2@ to get a list of available crypto
367 367 providers. The default provider is always listed first, and the
368 368 rest are listed in lexical order. Each crypto provider is listed
369 369 on a line by itself with no other text, enabling the output of
... ... @@ -390,7 +390,7 @@ make
390 390 class derived from <classname>QPDFCryptoImpl</classname> and
391 391 register it with <classname>QPDFCryptoProvider</classname>. For
392 392 additional information, see comments in
393   - <filename>include/qpdf/QPDFCryptoImpl.hh</filename>.
  393 + @1@filename@1@include/qpdf/QPDFCryptoImpl.hh@2@filename@2@.
394 394 </para>
395 395 </sect2>
396 396 <sect2 id="ref.crypto.design">
... ... @@ -502,8 +502,8 @@ make
502 502 </listitem>
503 503 <listitem>
504 504 <para>
505   - Passing <option>--enable-show-failed-test-output</option> to
506   - <command>./configure</command> will cause any failed test
  505 + Passing @1@option@1@--enable-show-failed-test-output@2@option@2@ to
  506 + @1@command@1@./configure@2@command@2@ will cause any failed test
507 507 output to be written to the console. This can be very useful
508 508 for seeing test failures generated by autobuilders where you
509 509 can't access qtest.log after the fact.
... ... @@ -519,25 +519,25 @@ make
519 519 automatic files after modifying their sources. If your
520 520 packaging environment automatically refreshes automatic files,
521 521 it can cause this check to fail. Suppress qpdf's checks by
522   - passing <option>--disable-check-autofiles</option> to
523   - <command>/.configure</command>. This is safe since qpdf's
524   - <command>autogen.sh</command> just runs autotools in the normal
  522 + passing @1@option@1@--disable-check-autofiles@2@option@2@ to
  523 + @1@command@1@/.configure@2@command@2@. This is safe since qpdf's
  524 + @1@command@1@autogen.sh@2@command@2@ just runs autotools in the normal
525 525 way.
526 526 </para>
527 527 </listitem>
528 528 <listitem>
529 529 <para>
530   - QPDF's <command>make install</command> does not install
  530 + QPDF's @1@command@1@make install@2@command@2@ does not install
531 531 completion files by default, but as a packager, it's good if
532 532 you install them wherever your distribution expects such files
533 533 to go. You can find completion files to install in the
534   - <filename>completions</filename> directory.
  534 + @1@filename@1@completions@2@filename@2@ directory.
535 535 </para>
536 536 </listitem>
537 537 <listitem>
538 538 <para>
539 539 Packagers are encouraged to install the source files from the
540   - <filename>examples</filename> directory along with qpdf
  540 + @1@filename@1@examples@2@filename@2@ directory along with qpdf
541 541 development packages.
542 542 </para>
543 543 </listitem>
... ... @@ -556,45 +556,45 @@ make
556 556 <para>
557 557 When running qpdf, the basic invocation is as follows:
558 558  
559   - <programlisting><command>qpdf</command><option> [ <replaceable>options</replaceable> ] { <replaceable>infilename</replaceable> | <option>--empty</option> } [ <replaceable>page_selection_options</replaceable> ] <replaceable>outfilename</replaceable></option>
  559 + <programlisting>@1@command@1@qpdf@2@command@2@@1@option@1@ [ @1@replaceable@1@options@2@replaceable@2@ ] { @1@replaceable@1@infilename@2@replaceable@2@ | @1@option@1@--empty@2@option@2@ } [ @1@replaceable@1@page_selection_options@2@replaceable@2@ ] @1@replaceable@1@outfilename@2@replaceable@2@@2@option@2@
560 560 </programlisting>
561   - This converts PDF file <option>infilename</option> to PDF file
562   - <option>outfilename</option>. The output file is functionally
  561 + This converts PDF file @1@option@1@infilename@2@option@2@ to PDF file
  562 + @1@option@1@outfilename@2@option@2@. The output file is functionally
563 563 identical to the input file but may have been structurally
564 564 reorganized. Also, orphaned objects will be removed from the
565 565 file. Many transformations are available as controlled by the
566   - options below. In place of <option>infilename</option>, the
567   - parameter <option>--empty</option> may be specified. This causes
  566 + options below. In place of @1@option@1@infilename@2@option@2@, the
  567 + parameter @1@option@1@--empty@2@option@2@ may be specified. This causes
568 568 qpdf to use a dummy input file that contains zero pages. The only
569   - normal use case for using <option>--empty</option> would be if you
  569 + normal use case for using @1@option@1@--empty@2@option@2@ would be if you
570 570 were going to add pages from another source, as discussed in <xref
571 571 linkend="ref.page-selection"/>.
572 572 </para>
573 573 <para>
574   - If <option>@filename</option> appears as a word anywhere in the
  574 + If @1@option@1@@filename@2@option@2@ appears as a word anywhere in the
575 575 command-line, it will be read line by line, and each line will be
576 576 treated as a command-line argument. Leading and trailing
577 577 whitespace is intentionally not removed from lines, which makes it
578 578 possible to handle arguments that start or end with spaces. The
579   - <option>@-</option> option allows arguments to be read from
  579 + @1@option@1@@-@2@option@2@ option allows arguments to be read from
580 580 standard input. This allows qpdf to be invoked with an arbitrary
581 581 number of arbitrarily long arguments. It is also very useful for
582 582 avoiding having to pass passwords on the command line. Note that
583   - the <option>@filename</option> can't appear in the middle of an
584   - argument, so constructs such as <option>--arg=@option</option>
  583 + the @1@option@1@@filename@2@option@2@ can't appear in the middle of an
  584 + argument, so constructs such as @1@option@1@--arg=@option@2@option@2@
585 585 will not work. You would have to include the argument and its
586 586 options together in the arguments file.
587 587 </para>
588 588 <para>
589   - <option>outfilename</option> does not have to be seekable, even
  589 + @1@option@1@outfilename@2@option@2@ does not have to be seekable, even
590 590 when generating linearized files. Specifying
591   - &ldquo;<option>-</option>&rdquo; as <option>outfilename</option>
  591 + &ldquo;@1@option@1@-@2@option@2@&rdquo; as @1@option@1@outfilename@2@option@2@
592 592 means to write to standard output. If you want to overwrite the
593 593 input file with the output, use the option
594   - <option>--replace-input</option> and omit the output file name.
  594 + @1@option@1@--replace-input@2@option@2@ and omit the output file name.
595 595 You can't specify the same file as both the input and the output.
596 596 If you do this, qpdf will tell you about the
597   - <option>--replace-input</option> option.
  597 + @1@option@1@--replace-input@2@option@2@ option.
598 598 </para>
599 599 <para>
600 600 Most options require an output file, but some testing or
... ... @@ -603,14 +603,14 @@ make
603 603 <sect2 id="ref.exit-status">
604 604 <title>Exit Status</title>
605 605 <para>
606   - The exit status of <command>qpdf</command> may be interpreted as
  606 + The exit status of @1@command@1@qpdf@2@command@2@ may be interpreted as
607 607 follows:
608 608 <itemizedlist>
609 609 <listitem>
610 610 <para>
611 611 <literal>0</literal>: no errors or warnings were found. The
612 612 file may still have problems qpdf can't detect. If
613   - <option>--warning-exit-0</option> was specified, exit status 0
  613 + @1@option@1@--warning-exit-0@2@option@2@ was specified, exit status 0
614 614 is used even if there are warnings.
615 615 </para>
616 616 </listitem>
... ... @@ -626,16 +626,16 @@ make
626 626 able to recover from. In some cases, the resulting file may
627 627 still be damaged. Note that qpdf still exits with status
628 628 <literal>3</literal> if it finds warnings even when
629   - <option>--no-warn</option> is specified. With
630   - <option>--warning-exit-0</option>, warnings without errors
  629 + @1@option@1@--no-warn@2@option@2@ is specified. With
  630 + @1@option@1@--warning-exit-0@2@option@2@, warnings without errors
631 631 exit with status 0 instead of 3.
632 632 </para>
633 633 </listitem>
634 634 </itemizedlist>
635   - Note that <command>qpdf</command> never exists with status
  635 + Note that @1@command@1@qpdf@2@command@2@ never exists with status
636 636 <literal>1</literal>. If you get an exit status of
637 637 <literal>1</literal>, it was something else, like the shell not
638   - being able to find or execute <command>qpdf</command>.
  638 + being able to find or execute @1@command@1@qpdf@2@command@2@.
639 639 </para>
640 640 </sect2>
641 641 </sect1>
... ... @@ -644,9 +644,9 @@ make
644 644 <para>
645 645 Starting in qpdf version 8.3.0, qpdf provides its own completion
646 646 support for zsh and bash. You can enable bash completion with
647   - <command>eval $(qpdf --completion-bash)</command> and zsh
648   - completion with <command>eval $(qpdf --completion-zsh)</command>.
649   - If <command>qpdf</command> is not in your path, you should invoke
  647 + @1@command@1@eval $(qpdf --completion-bash)@2@command@2@ and zsh
  648 + completion with @1@command@1@eval $(qpdf --completion-zsh)@2@command@2@.
  649 + If @1@command@1@qpdf@2@command@2@ is not in your path, you should invoke
650 650 it above with an absolute path. If you invoke it with a relative
651 651 path, it will warn you, and the completion won't work if you're in
652 652 a different directory.
... ... @@ -667,7 +667,7 @@ make
667 667 commonly needed transformations.
668 668 <variablelist>
669 669 <varlistentry>
670   - <term><option>--help</option></term>
  670 + <term>@1@option@1@--help@2@option@2@</term>
671 671 <listitem>
672 672 <para>
673 673 Display command-line invocation help.
... ... @@ -675,7 +675,7 @@ make
675 675 </listitem>
676 676 </varlistentry>
677 677 <varlistentry>
678   - <term><option>--version</option></term>
  678 + <term>@1@option@1@--version@2@option@2@</term>
679 679 <listitem>
680 680 <para>
681 681 Display the current version of qpdf.
... ... @@ -683,7 +683,7 @@ make
683 683 </listitem>
684 684 </varlistentry>
685 685 <varlistentry>
686   - <term><option>--copyright</option></term>
  686 + <term>@1@option@1@--copyright@2@option@2@</term>
687 687 <listitem>
688 688 <para>
689 689 Show detailed copyright information.
... ... @@ -691,7 +691,7 @@ make
691 691 </listitem>
692 692 </varlistentry>
693 693 <varlistentry>
694   - <term><option>--show-crypto</option></term>
  694 + <term>@1@option@1@--show-crypto@2@option@2@</term>
695 695 <listitem>
696 696 <para>
697 697 Show a list of available crypto providers, each on a line by
... ... @@ -702,7 +702,7 @@ make
702 702 </listitem>
703 703 </varlistentry>
704 704 <varlistentry>
705   - <term><option>--completion-bash</option></term>
  705 + <term>@1@option@1@--completion-bash@2@option@2@</term>
706 706 <listitem>
707 707 <para>
708 708 Output a completion command you can eval to enable shell
... ... @@ -711,7 +711,7 @@ make
711 711 </listitem>
712 712 </varlistentry>
713 713 <varlistentry>
714   - <term><option>--completion-zsh</option></term>
  714 + <term>@1@option@1@--completion-zsh@2@option@2@</term>
715 715 <listitem>
716 716 <para>
717 717 Output a completion command you can eval to enable shell
... ... @@ -720,31 +720,31 @@ make
720 720 </listitem>
721 721 </varlistentry>
722 722 <varlistentry>
723   - <term><option>--password=<replaceable>password</replaceable></option></term>
  723 + <term>@1@option@1@--password=@1@replaceable@1@password@2@replaceable@2@@2@option@2@</term>
724 724 <listitem>
725 725 <para>
726 726 Specifies a password for accessing encrypted files. To read
727 727 the password from a file or standard input, you can use
728   - <option>--password-file</option>, added in qpdf 10.2. Note
729   - that you can also use <option>@filename</option> or
730   - <option>@-</option> as described above to put the password in
  728 + @1@option@1@--password-file@2@option@2@, added in qpdf 10.2. Note
  729 + that you can also use @1@option@1@@filename@2@option@2@ or
  730 + @1@option@1@@-@2@option@2@ as described above to put the password in
731 731 a file or pass it via standard input, but you would do so by
732 732 specifying the entire
733   - <option>--password=<replaceable>password</replaceable></option>
  733 + @1@option@1@--password=@1@replaceable@1@password@2@replaceable@2@@2@option@2@
734 734 option in the file. Syntax such as
735   - <option>--password=@filename</option> won't work since
736   - <option>@filename</option> is not recognized in the middle of
  735 + @1@option@1@--password=@filename@2@option@2@ won't work since
  736 + @1@option@1@@filename@2@option@2@ is not recognized in the middle of
737 737 an argument.
738 738 </para>
739 739 </listitem>
740 740 </varlistentry>
741 741 <varlistentry>
742   - <term><option>--password-file=<replaceable>filename</replaceable></option></term>
  742 + <term>@1@option@1@--password-file=@1@replaceable@1@filename@2@replaceable@2@@2@option@2@</term>
743 743 <listitem>
744 744 <para>
745 745 Reads the first line from the specified file and uses it as
746 746 the password for accessing encrypted files.
747   - <option><replaceable>filename</replaceable></option> may be
  747 + @1@option@1@@1@replaceable@1@filename@2@replaceable@2@@2@option@2@ may be
748 748 <literal>-</literal> to read the password from standard input.
749 749 Note that, in this case, the password is echoed and there is
750 750 no prompt, so use with caution.
... ... @@ -752,21 +752,21 @@ make
752 752 </listitem>
753 753 </varlistentry>
754 754 <varlistentry>
755   - <term><option>--is-encrypted</option></term>
  755 + <term>@1@option@1@--is-encrypted@2@option@2@</term>
756 756 <listitem>
757 757 <para>
758 758 Silently exit with status 0 if the file is encrypted or status
759 759 2 if the file is not encrypted. This is useful for shell
760 760 scripts. Other options are ignored if this is given. This
761 761 option is mutually exclusive with
762   - <option>--requires-password</option>. Both this option and
763   - <option>--requires-password</option> exit with status 2 for
  762 + @1@option@1@--requires-password@2@option@2@. Both this option and
  763 + @1@option@1@--requires-password@2@option@2@ exit with status 2 for
764 764 non-encrypted files.
765 765 </para>
766 766 </listitem>
767 767 </varlistentry>
768 768 <varlistentry>
769   - <term><option>--requires-password</option></term>
  769 + <term>@1@option@1@--requires-password@2@option@2@</term>
770 770 <listitem>
771 771 <para>
772 772 Silently exit with status 0 if a password (other than as
... ... @@ -775,18 +775,18 @@ make
775 775 requires no password or the correct password has been
776 776 supplied. This is useful for shell scripts. Note that any
777 777 supplied password is used when opening the file. When used
778   - with a <option>--password</option> option, this option can be
  778 + with a @1@option@1@--password@2@option@2@ option, this option can be
779 779 used to check the correctness of the password. In that case,
780 780 an exit status of 3 means the file works with the supplied
781 781 password. This option is mutually exclusive with
782   - <option>--is-encrypted</option>. Both this option and
783   - <option>--is-encrypted</option> exit with status 2 for
  782 + @1@option@1@--is-encrypted@2@option@2@. Both this option and
  783 + @1@option@1@--is-encrypted@2@option@2@ exit with status 2 for
784 784 non-encrypted files.
785 785 </para>
786 786 </listitem>
787 787 </varlistentry>
788 788 <varlistentry>
789   - <term><option>--verbose</option></term>
  789 + <term>@1@option@1@--verbose@2@option@2@</term>
790 790 <listitem>
791 791 <para>
792 792 Increase verbosity of output. For now, this just prints some
... ... @@ -795,7 +795,7 @@ make
795 795 </listitem>
796 796 </varlistentry>
797 797 <varlistentry>
798   - <term><option>--progress</option></term>
  798 + <term>@1@option@1@--progress@2@option@2@</term>
799 799 <listitem>
800 800 <para>
801 801 Indicate progress while writing files.
... ... @@ -803,29 +803,29 @@ make
803 803 </listitem>
804 804 </varlistentry>
805 805 <varlistentry>
806   - <term><option>--no-warn</option></term>
  806 + <term>@1@option@1@--no-warn@2@option@2@</term>
807 807 <listitem>
808 808 <para>
809 809 Suppress writing of warnings to stderr. If warnings were
810   - detected and suppressed, <command>qpdf</command> will still
  810 + detected and suppressed, @1@command@1@qpdf@2@command@2@ will still
811 811 exit with exit code 3. See also
812   - <option>--warning-exit-0</option>.
  812 + @1@option@1@--warning-exit-0@2@option@2@.
813 813 </para>
814 814 </listitem>
815 815 </varlistentry>
816 816 <varlistentry>
817   - <term><option>--warning-exit-0</option></term>
  817 + <term>@1@option@1@--warning-exit-0@2@option@2@</term>
818 818 <listitem>
819 819 <para>
820 820 If warnings are found but no errors, exit with exit code 0
821   - instead 3. When combined with <option>--no-warn</option>, the
822   - effect is for <command>qpdf</command> to completely ignore
  821 + instead 3. When combined with @1@option@1@--no-warn@2@option@2@, the
  822 + effect is for @1@command@1@qpdf@2@command@2@ to completely ignore
823 823 warnings.
824 824 </para>
825 825 </listitem>
826 826 </varlistentry>
827 827 <varlistentry>
828   - <term><option>--linearize</option></term>
  828 + <term>@1@option@1@--linearize@2@option@2@</term>
829 829 <listitem>
830 830 <para>
831 831 Causes generation of a linearized (web-optimized) output file.
... ... @@ -833,27 +833,27 @@ make
833 833 </listitem>
834 834 </varlistentry>
835 835 <varlistentry>
836   - <term><option>--replace-input</option></term>
  836 + <term>@1@option@1@--replace-input@2@option@2@</term>
837 837 <listitem>
838 838 <para>
839 839 If specified, the output file name should be omitted. This
840 840 option tells qpdf to replace the input file with the output.
841 841 It does this by writing to
842   - <filename><replaceable>infilename</replaceable>.~qpdf-temp#</filename>
  842 + @1@filename@1@@1@replaceable@1@infilename@2@replaceable@2@.~qpdf-temp#@2@filename@2@
843 843 and, when done, overwriting the input file with the temporary
844 844 file. If there were any warnings, the original input is saved
845 845 as
846   - <filename><replaceable>infilename</replaceable>.~qpdf-orig</filename>.
  846 + @1@filename@1@@1@replaceable@1@infilename@2@replaceable@2@.~qpdf-orig@2@filename@2@.
847 847 </para>
848 848 </listitem>
849 849 </varlistentry>
850 850 <varlistentry>
851   - <term><option>--copy-encryption=file</option></term>
  851 + <term>@1@option@1@--copy-encryption=file@2@option@2@</term>
852 852 <listitem>
853 853 <para>
854 854 Encrypt the file using the same encryption parameters,
855 855 including user and owner password, as the specified file. Use
856   - <option>--encryption-file-password</option> to specify a password
  856 + @1@option@1@--encryption-file-password@2@option@2@ to specify a password
857 857 if one is needed to open this file. Note that copying the
858 858 encryption parameters from a file also copies the first half
859 859 of <literal>/ID</literal> from the file since this is part of
... ... @@ -862,10 +862,10 @@ make
862 862 </listitem>
863 863 </varlistentry>
864 864 <varlistentry>
865   - <term><option>--encryption-file-password=password</option></term>
  865 + <term>@1@option@1@--encryption-file-password=password@2@option@2@</term>
866 866 <listitem>
867 867 <para>
868   - If the file specified with <option>--copy-encryption</option>
  868 + If the file specified with @1@option@1@--copy-encryption@2@option@2@
869 869 requires a password, specify the password using this option.
870 870 Note that only one of the user or owner password is required.
871 871 Both passwords will be preserved since QPDF does not
... ... @@ -876,7 +876,7 @@ make
876 876 </listitem>
877 877 </varlistentry>
878 878 <varlistentry>
879   - <term><option>--allow-weak-crypto</option></term>
  879 + <term>@1@option@1@--allow-weak-crypto@2@option@2@</term>
880 880 <listitem>
881 881 <para>
882 882 Starting with version 10.4, qpdf issues warnings when
... ... @@ -889,7 +889,7 @@ make
889 889 </listitem>
890 890 </varlistentry>
891 891 <varlistentry>
892   - <term><option>--encrypt options --</option></term>
  892 + <term>@1@option@1@--encrypt options --@2@option@2@</term>
893 893 <listitem>
894 894 <para>
895 895 Causes generation an encrypted output file. Please see <xref
... ... @@ -899,7 +899,7 @@ make
899 899 </listitem>
900 900 </varlistentry>
901 901 <varlistentry>
902   - <term><option>--decrypt</option></term>
  902 + <term>@1@option@1@--decrypt@2@option@2@</term>
903 903 <listitem>
904 904 <para>
905 905 Removes any encryption on the file. A password must be
... ... @@ -908,17 +908,17 @@ make
908 908 </listitem>
909 909 </varlistentry>
910 910 <varlistentry>
911   - <term><option>--password-is-hex-key</option></term>
  911 + <term>@1@option@1@--password-is-hex-key@2@option@2@</term>
912 912 <listitem>
913 913 <para>
914 914 Overrides the usual computation/retrieval of the PDF file's
915 915 encryption key from user/owner password with an explicit
916 916 specification of the encryption key. When this option is
917   - specified, the argument to the <option>--password</option>
  917 + specified, the argument to the @1@option@1@--password@2@option@2@
918 918 option is interpreted as a hexadecimal-encoded key value. This
919 919 only applies to the password used to open the main input file.
920 920 It does not apply to other files opened by
921   - <option>--pages</option> or other options or to files being
  921 + @1@option@1@--pages@2@option@2@ or other options or to files being
922 922 written.
923 923 </para>
924 924 <para>
... ... @@ -931,13 +931,13 @@ make
931 931 heavily damaged, it may be possible to derive the encryption
932 932 key and recover parts of the file using it directly. To expose
933 933 the encryption key used by an encrypted file that you can open
934   - normally, use the <option>--show-encryption-key</option>
  934 + normally, use the @1@option@1@--show-encryption-key@2@option@2@
935 935 option.
936 936 </para>
937 937 </listitem>
938 938 </varlistentry>
939 939 <varlistentry>
940   - <term><option>--suppress-password-recovery</option></term>
  940 + <term>@1@option@1@--suppress-password-recovery@2@option@2@</term>
941 941 <listitem>
942 942 <para>
943 943 Ordinarily, qpdf attempts to automatically compensate for
... ... @@ -949,14 +949,14 @@ make
949 949 </listitem>
950 950 </varlistentry>
951 951 <varlistentry>
952   - <term><option>--password-mode=<replaceable>mode</replaceable></option></term>
  952 + <term>@1@option@1@--password-mode=@1@replaceable@1@mode@2@replaceable@2@@2@option@2@</term>
953 953 <listitem>
954 954 <para>
955 955 This option can be used to fine-tune how qpdf interprets
956 956 Unicode (non-ASCII) password strings passed on the command
957   - line. With the exception of the <option>hex-bytes</option>
  957 + line. With the exception of the @1@option@1@hex-bytes@2@option@2@
958 958 mode, these only apply to passwords provided when encrypting
959   - files. The <option>hex-bytes</option> mode also applies to
  959 + files. The @1@option@1@hex-bytes@2@option@2@ mode also applies to
960 960 passwords specified for reading files. For additional
961 961 discussion of the supported password modes and when you might
962 962 want to use them, see <xref linkend="ref.unicode-passwords"/>.
... ... @@ -964,7 +964,7 @@ make
964 964 <itemizedlist>
965 965 <listitem>
966 966 <para>
967   - <option>auto</option>: Automatically determine whether the
  967 + @1@option@1@auto@2@option@2@: Automatically determine whether the
968 968 specified password is a properly encoded Unicode (UTF-8)
969 969 string, and transcode it as required by the PDF spec based
970 970 on the type encryption being applied. On Windows starting
... ... @@ -975,22 +975,22 @@ make
975 975 </listitem>
976 976 <listitem>
977 977 <para>
978   - <option>unicode</option>: Tells qpdf that the incoming
  978 + @1@option@1@unicode@2@option@2@: Tells qpdf that the incoming
979 979 password is UTF-8, overriding whatever its automatic
980 980 detection determines. The only difference between this mode
981   - and <option>auto</option> is that qpdf will fail with an
  981 + and @1@option@1@auto@2@option@2@ is that qpdf will fail with an
982 982 error message if the password is not valid UTF-8 instead of
983   - falling back to <option>bytes</option> mode with a warning.
  983 + falling back to @1@option@1@bytes@2@option@2@ mode with a warning.
984 984 </para>
985 985 </listitem>
986 986 <listitem>
987 987 <para>
988   - <option>bytes</option>: Interpret the password as a literal
  988 + @1@option@1@bytes@2@option@2@: Interpret the password as a literal
989 989 byte string. For non-Windows platforms, this is what
990 990 versions of qpdf prior to 8.4.0 did. For Windows platforms,
991 991 there is no way to specify strings of binary data on the
992 992 command line directly, but you can use the
993   - <option>@filename</option> option to do it, in which case
  993 + @1@option@1@@filename@2@option@2@ option to do it, in which case
994 994 this option forces qpdf to respect the string of bytes as
995 995 provided. This option will allow you to encrypt PDF files
996 996 with passwords that will not be usable by other readers.
... ... @@ -998,10 +998,10 @@ make
998 998 </listitem>
999 999 <listitem>
1000 1000 <para>
1001   - <option>hex-bytes</option>: Interpret the password as a
  1001 + @1@option@1@hex-bytes@2@option@2@: Interpret the password as a
1002 1002 hex-encoded string. This provides a way to pass binary data
1003 1003 as a password on all platforms including Windows. As with
1004   - <option>bytes</option>, this option may allow creation of
  1004 + @1@option@1@bytes@2@option@2@, this option may allow creation of
1005 1005 files that can't be opened by other readers. This mode
1006 1006 affects qpdf's interpretation of passwords specified for
1007 1007 decrypting files as well as for encrypting them. It makes
... ... @@ -1014,33 +1014,33 @@ make
1014 1014 </listitem>
1015 1015 </varlistentry>
1016 1016 <varlistentry>
1017   - <term><option>--rotate=[+|-]angle[:page-range]</option></term>
  1017 + <term>@1@option@1@--rotate=[+|-]angle[:page-range]@2@option@2@</term>
1018 1018 <listitem>
1019 1019 <para>
1020 1020 Apply rotation to specified pages. The
1021   - <option>page-range</option> portion of the option value has
  1021 + @1@option@1@page-range@2@option@2@ portion of the option value has
1022 1022 the same format as page ranges in <xref
1023 1023 linkend="ref.page-selection"/>. If the page range is omitted,
1024 1024 the rotation is applied to all pages. The
1025   - <option>angle</option> portion of the parameter may be either
1026   - 0, 90, 180, or 270. If preceded by <option>+</option> or
1027   - <option>-</option>, the angle is added to or subtracted from
  1025 + @1@option@1@angle@2@option@2@ portion of the parameter may be either
  1026 + 0, 90, 180, or 270. If preceded by @1@option@1@+@2@option@2@ or
  1027 + @1@option@1@-@2@option@2@, the angle is added to or subtracted from
1028 1028 the specified pages' original rotations. This is almost always
1029 1029 what you want. Otherwise the pages' rotations are set to the
1030 1030 exact value, which may cause the appearances of the pages to
1031 1031 be inconsistent, especially for scans. For example, the
1032   - command <command>qpdf in.pdf out.pdf --rotate=+90:2,4,6
1033   - --rotate=180:7-8</command> would rotate pages 2, 4, and 6 90
  1032 + command @1@command@1@qpdf in.pdf out.pdf --rotate=+90:2,4,6
  1033 + --rotate=180:7-8@2@command@2@ would rotate pages 2, 4, and 6 90
1034 1034 degrees clockwise from their original rotation and force the
1035 1035 rotation of pages 7 through 8 to 180 degrees regardless of
1036   - their original rotation, and the command <command>qpdf in.pdf
1037   - out.pdf --rotate=+180</command> would rotate all pages by 180
  1036 + their original rotation, and the command @1@command@1@qpdf in.pdf
  1037 + out.pdf --rotate=+180@2@command@2@ would rotate all pages by 180
1038 1038 degrees.
1039 1039 </para>
1040 1040 </listitem>
1041 1041 </varlistentry>
1042 1042 <varlistentry>
1043   - <term><option>--keep-files-open=<replaceable>[yn]</replaceable></option></term>
  1043 + <term>@1@option@1@--keep-files-open=@1@replaceable@1@[yn]@2@replaceable@2@@2@option@2@</term>
1044 1044 <listitem>
1045 1045 <para>
1046 1046 This option controls whether qpdf keeps individual files open
... ... @@ -1056,33 +1056,33 @@ make
1056 1056 with version 8.2.1, the default behavior is that files are
1057 1057 kept open if no more than 200 files are specified, but that
1058 1058 the behavior can be explicitly overridden with the
1059   - <option>--keep-files-open</option> flag. If you are merging
  1059 + @1@option@1@--keep-files-open@2@option@2@ flag. If you are merging
1060 1060 more than 200 files but less than the operating system's max
1061 1061 open files limit, you may want to use
1062   - <option>--keep-files-open=y</option>, especially if working
  1062 + @1@option@1@--keep-files-open=y@2@option@2@, especially if working
1063 1063 over a networked file system. If you are using a local file
1064 1064 system where the overhead is low and you might sometimes merge
1065 1065 more than the OS limit's number of files from a script and are
1066 1066 not worried about a few seconds additional processing time,
1067   - you may want to specify <option>--keep-files-open=n</option>.
  1067 + you may want to specify @1@option@1@--keep-files-open=n@2@option@2@.
1068 1068 The threshold for switching may be changed from the default
1069   - 200 with the <option>--keep-files-open-threshold</option>
  1069 + 200 with the @1@option@1@--keep-files-open-threshold@2@option@2@
1070 1070 option.
1071 1071 </para>
1072 1072 </listitem>
1073 1073 </varlistentry>
1074 1074 <varlistentry>
1075   - <term><option>--keep-files-open-threshold=<replaceable>count</replaceable></option></term>
  1075 + <term>@1@option@1@--keep-files-open-threshold=@1@replaceable@1@count@2@replaceable@2@@2@option@2@</term>
1076 1076 <listitem>
1077 1077 <para>
1078 1078 If specified, overrides the default value of 200 used as the
1079 1079 threshold for qpdf deciding whether or not to keep files open.
1080   - See <option>--keep-files-open</option> for details.
  1080 + See @1@option@1@--keep-files-open@2@option@2@ for details.
1081 1081 </para>
1082 1082 </listitem>
1083 1083 </varlistentry>
1084 1084 <varlistentry>
1085   - <term><option>--pages options --</option></term>
  1085 + <term>@1@option@1@--pages options --@2@option@2@</term>
1086 1086 <listitem>
1087 1087 <para>
1088 1088 Select specific pages from one or more input files. See <xref
... ... @@ -1092,19 +1092,19 @@ make
1092 1092 </listitem>
1093 1093 </varlistentry>
1094 1094 <varlistentry>
1095   - <term><option>--collate=<replaceable>n</replaceable></option></term>
  1095 + <term>@1@option@1@--collate=@1@replaceable@1@n@2@replaceable@2@@2@option@2@</term>
1096 1096 <listitem>
1097 1097 <para>
1098 1098 When specified, collate rather than concatenate pages from
1099   - files specified with <option>--pages</option>. With a numeric
1100   - argument, collate in groups of <replaceable>n</replaceable>.
  1099 + files specified with @1@option@1@--pages@2@option@2@. With a numeric
  1100 + argument, collate in groups of @1@replaceable@1@n@2@replaceable@2@.
1101 1101 The default is 1. See <xref linkend="ref.page-selection"/> for
1102 1102 additional details.
1103 1103 </para>
1104 1104 </listitem>
1105 1105 </varlistentry>
1106 1106 <varlistentry>
1107   - <term><option>--flatten-rotation</option></term>
  1107 + <term>@1@option@1@--flatten-rotation@2@option@2@</term>
1108 1108 <listitem>
1109 1109 <para>
1110 1110 For each page that is rotated using the
... ... @@ -1117,11 +1117,11 @@ make
1117 1117 </listitem>
1118 1118 </varlistentry>
1119 1119 <varlistentry>
1120   - <term><option>--split-pages=[n]</option></term>
  1120 + <term>@1@option@1@--split-pages=[n]@2@option@2@</term>
1121 1121 <listitem>
1122 1122 <para>
1123   - Write each group of <option>n</option> pages to a separate
1124   - output file. If <option>n</option> is not specified, create
  1123 + Write each group of @1@option@1@n@2@option@2@ pages to a separate
  1124 + output file. If @1@option@1@n@2@option@2@ is not specified, create
1125 1125 single pages. Output file names are generated as follows:
1126 1126 <itemizedlist>
1127 1127 <listitem>
... ... @@ -1134,7 +1134,7 @@ make
1134 1134 <listitem>
1135 1135 <para>
1136 1136 Otherwise, if the output file name ends in
1137   - <filename>.pdf</filename> (case insensitive), a zero-padded
  1137 + @1@filename@1@.pdf@2@filename@2@ (case insensitive), a zero-padded
1138 1138 page range, preceded by a dash, is inserted before the file
1139 1139 extension.
1140 1140 </para>
... ... @@ -1150,29 +1150,29 @@ make
1150 1150 <para>
1151 1151 Page ranges are a single number in the case of single-page
1152 1152 groups or two numbers separated by a dash otherwise.
1153   - For example, if <filename>infile.pdf</filename> has 12 pages
  1153 + For example, if @1@filename@1@infile.pdf@2@filename@2@ has 12 pages
1154 1154 <itemizedlist>
1155 1155 <listitem>
1156 1156 <para>
1157   - <command>qpdf --split-pages infile.pdf %d-out</command>
1158   - would generate files <filename>01-out</filename> through
1159   - <filename>12-out</filename>
  1157 + @1@command@1@qpdf --split-pages infile.pdf %d-out@2@command@2@
  1158 + would generate files @1@filename@1@01-out@2@filename@2@ through
  1159 + @1@filename@1@12-out@2@filename@2@
1160 1160 </para>
1161 1161 </listitem>
1162 1162 <listitem>
1163 1163 <para>
1164   - <command>qpdf --split-pages=2 infile.pdf
1165   - outfile.pdf</command> would generate files
1166   - <filename>outfile-01-02.pdf</filename> through
1167   - <filename>outfile-11-12.pdf</filename>
  1164 + @1@command@1@qpdf --split-pages=2 infile.pdf
  1165 + outfile.pdf@2@command@2@ would generate files
  1166 + @1@filename@1@outfile-01-02.pdf@2@filename@2@ through
  1167 + @1@filename@1@outfile-11-12.pdf@2@filename@2@
1168 1168 </para>
1169 1169 </listitem>
1170 1170 <listitem>
1171 1171 <para>
1172   - <command>qpdf --split-pages infile.pdf
1173   - something.else</command> would generate files
1174   - <filename>something.else-01</filename> through
1175   - <filename>something.else-12</filename>
  1172 + @1@command@1@qpdf --split-pages infile.pdf
  1173 + something.else@2@command@2@ would generate files
  1174 + @1@filename@1@something.else-01@2@filename@2@ through
  1175 + @1@filename@1@something.else-12@2@filename@2@
1176 1176 </para>
1177 1177 </listitem>
1178 1178 </itemizedlist>
... ... @@ -1182,15 +1182,15 @@ make
1182 1182 original PDF file are not preserved. For each page of output,
1183 1183 this option creates an empty PDF and copies a single page from
1184 1184 the output into it. If you require the global data, you will
1185   - have to run <command>qpdf</command> with the
1186   - <option>--pages</option> option once for each file. Using
1187   - <option>--split-pages</option> is much faster if you don't
  1185 + have to run @1@command@1@qpdf@2@command@2@ with the
  1186 + @1@option@1@--pages@2@option@2@ option once for each file. Using
  1187 + @1@option@1@--split-pages@2@option@2@ is much faster if you don't
1188 1188 require the global data.
1189 1189 </para>
1190 1190 </listitem>
1191 1191 </varlistentry>
1192 1192 <varlistentry>
1193   - <term><option>--overlay options --</option></term>
  1193 + <term>@1@option@1@--overlay options --@2@option@2@</term>
1194 1194 <listitem>
1195 1195 <para>
1196 1196 Overlay pages from another file onto the output pages. See
... ... @@ -1200,7 +1200,7 @@ make
1200 1200 </listitem>
1201 1201 </varlistentry>
1202 1202 <varlistentry>
1203   - <term><option>--underlay options --</option></term>
  1203 + <term>@1@option@1@--underlay options --@2@option@2@</term>
1204 1204 <listitem>
1205 1205 <para>
1206 1206 Overlay pages from another file onto the output pages. See
... ... @@ -1214,9 +1214,9 @@ make
1214 1214 <para>
1215 1215 Password-protected files may be opened by specifying a password.
1216 1216 By default, qpdf will preserve any encryption data associated with
1217   - a file. If <option>--decrypt</option> is specified, qpdf will
  1217 + a file. If @1@option@1@--decrypt@2@option@2@ is specified, qpdf will
1218 1218 attempt to remove any encryption information. If
1219   - <option>--encrypt</option> is specified, qpdf will replace the
  1219 + @1@option@1@--encrypt@2@option@2@ is specified, qpdf will replace the
1220 1220 document's encryption parameters with whatever is specified.
1221 1221 </para>
1222 1222 <para>
... ... @@ -1234,7 +1234,7 @@ make
1234 1234 the user. Starting in qpdf 8.4.0, qpdf does this automatically in
1235 1235 most cases. For an in-depth discussion, please see <xref
1236 1236 linkend="ref.unicode-passwords"/>. Previous versions of this
1237   - manual described workarounds using the <command>iconv</command>
  1237 + manual described workarounds using the @1@command@1@iconv@2@command@2@
1238 1238 command. Such workarounds are no longer required or recommended
1239 1239 with qpdf 8.4.0. However, for backward compatibility, qpdf
1240 1240 attempts to detect those workarounds and do the right thing in
... ... @@ -1247,9 +1247,9 @@ make
1247 1247 To change the encryption parameters of a file, use the --encrypt
1248 1248 flag. The syntax is
1249 1249  
1250   - <programlisting><option>--encrypt <replaceable>user-password</replaceable> <replaceable>owner-password</replaceable> <replaceable>key-length</replaceable> [ <replaceable>restrictions</replaceable> ] --</option>
  1250 + <programlisting>@1@option@1@--encrypt @1@replaceable@1@user-password@2@replaceable@2@ @1@replaceable@1@owner-password@2@replaceable@2@ @1@replaceable@1@key-length@2@replaceable@2@ [ @1@replaceable@1@restrictions@2@replaceable@2@ ] --@2@option@2@
1251 1251 </programlisting>
1252   - Note that &ldquo;<option>--</option>&rdquo; terminates parsing of
  1252 + Note that &ldquo;@1@option@1@--@2@option@2@&rdquo; terminates parsing of
1253 1253 encryption flags and must be present even if no restrictions are
1254 1254 present.
1255 1255 </para>
... ... @@ -1259,22 +1259,22 @@ make
1259 1259 allowing creation of PDF files with a non-empty user password, an
1260 1260 empty owner password, and a 256-bit key since such files can be
1261 1261 opened with no password. If you want to create such files, specify
1262   - the encryption option <option>--allow-insecure</option>, as
  1262 + the encryption option @1@option@1@--allow-insecure@2@option@2@, as
1263 1263 described below.
1264 1264 </para>
1265 1265 <para>
1266 1266 The value for
1267   - <option><replaceable>key-length</replaceable></option> may be 40,
  1267 + @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@ may be 40,
1268 1268 128, or 256. The restriction flags are dependent upon key length.
1269 1269 When no additional restrictions are given, the default is to be
1270 1270 fully permissive.
1271 1271 </para>
1272 1272 <para>
1273   - If <option><replaceable>key-length</replaceable></option> is 40,
  1273 + If @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@ is 40,
1274 1274 the following restriction options are available:
1275 1275 <variablelist>
1276 1276 <varlistentry>
1277   - <term><option>--print=[yn]</option></term>
  1277 + <term>@1@option@1@--print=[yn]@2@option@2@</term>
1278 1278 <listitem>
1279 1279 <para>
1280 1280 Determines whether or not to allow printing.
... ... @@ -1282,7 +1282,7 @@ make
1282 1282 </listitem>
1283 1283 </varlistentry>
1284 1284 <varlistentry>
1285   - <term><option>--modify=[yn]</option></term>
  1285 + <term>@1@option@1@--modify=[yn]@2@option@2@</term>
1286 1286 <listitem>
1287 1287 <para>
1288 1288 Determines whether or not to allow document modification.
... ... @@ -1290,7 +1290,7 @@ make
1290 1290 </listitem>
1291 1291 </varlistentry>
1292 1292 <varlistentry>
1293   - <term><option>--extract=[yn]</option></term>
  1293 + <term>@1@option@1@--extract=[yn]@2@option@2@</term>
1294 1294 <listitem>
1295 1295 <para>
1296 1296 Determines whether or not to allow text/image extraction.
... ... @@ -1298,7 +1298,7 @@ make
1298 1298 </listitem>
1299 1299 </varlistentry>
1300 1300 <varlistentry>
1301   - <term><option>--annotate=[yn]</option></term>
  1301 + <term>@1@option@1@--annotate=[yn]@2@option@2@</term>
1302 1302 <listitem>
1303 1303 <para>
1304 1304 Determines whether or not to allow comments and form fill-in
... ... @@ -1307,11 +1307,11 @@ make
1307 1307 </listitem>
1308 1308 </varlistentry>
1309 1309 </variablelist>
1310   - If <option><replaceable>key-length</replaceable></option> is 128,
  1310 + If @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@ is 128,
1311 1311 the following restriction options are available:
1312 1312 <variablelist>
1313 1313 <varlistentry>
1314   - <term><option>--accessibility=[yn]</option></term>
  1314 + <term>@1@option@1@--accessibility=[yn]@2@option@2@</term>
1315 1315 <listitem>
1316 1316 <para>
1317 1317 Determines whether or not to allow accessibility to visually
... ... @@ -1325,7 +1325,7 @@ make
1325 1325 </listitem>
1326 1326 </varlistentry>
1327 1327 <varlistentry>
1328   - <term><option>--extract=[yn]</option></term>
  1328 + <term>@1@option@1@--extract=[yn]@2@option@2@</term>
1329 1329 <listitem>
1330 1330 <para>
1331 1331 Determines whether or not to allow text/graphic extraction.
... ... @@ -1333,7 +1333,7 @@ make
1333 1333 </listitem>
1334 1334 </varlistentry>
1335 1335 <varlistentry>
1336   - <term><option>--assemble=[yn]</option></term>
  1336 + <term>@1@option@1@--assemble=[yn]@2@option@2@</term>
1337 1337 <listitem>
1338 1338 <para>
1339 1339 Determines whether document assembly (rotation and reordering
... ... @@ -1342,18 +1342,18 @@ make
1342 1342 </listitem>
1343 1343 </varlistentry>
1344 1344 <varlistentry>
1345   - <term><option>--annotate=[yn]</option></term>
  1345 + <term>@1@option@1@--annotate=[yn]@2@option@2@</term>
1346 1346 <listitem>
1347 1347 <para>
1348 1348 Determines whether modifying annotations is allowed. This
1349 1349 includes adding comments and filling in form fields. Also
1350 1350 allows editing of form fields if
1351   - <option>--modify-other=y</option> is given.
  1351 + @1@option@1@--modify-other=y@2@option@2@ is given.
1352 1352 </para>
1353 1353 </listitem>
1354 1354 </varlistentry>
1355 1355 <varlistentry>
1356   - <term><option>--form=[yn]</option></term>
  1356 + <term>@1@option@1@--form=[yn]@2@option@2@</term>
1357 1357 <listitem>
1358 1358 <para>
1359 1359 Determines whether filling form fields is allowed.
... ... @@ -1361,37 +1361,37 @@ make
1361 1361 </listitem>
1362 1362 </varlistentry>
1363 1363 <varlistentry>
1364   - <term><option>--modify-other=[yn]</option></term>
  1364 + <term>@1@option@1@--modify-other=[yn]@2@option@2@</term>
1365 1365 <listitem>
1366 1366 <para>
1367 1367 Allow all document editing except those controlled separately
1368   - by the <option>--assemble</option>,
1369   - <option>--annotate</option>, and <option>--form</option>
  1368 + by the @1@option@1@--assemble@2@option@2@,
  1369 + @1@option@1@--annotate@2@option@2@, and @1@option@1@--form@2@option@2@
1370 1370 options.
1371 1371 </para>
1372 1372 </listitem>
1373 1373 </varlistentry>
1374 1374 <varlistentry>
1375   - <term><option>--print=<replaceable>print-opt</replaceable></option></term>
  1375 + <term>@1@option@1@--print=@1@replaceable@1@print-opt@2@replaceable@2@@2@option@2@</term>
1376 1376 <listitem>
1377 1377 <para>
1378 1378 Controls printing access.
1379   - <option><replaceable>print-opt</replaceable></option> may be
  1379 + @1@option@1@@1@replaceable@1@print-opt@2@replaceable@2@@2@option@2@ may be
1380 1380 one of the following:
1381 1381 <itemizedlist>
1382 1382 <listitem>
1383 1383 <para>
1384   - <option>full</option>: allow full printing
  1384 + @1@option@1@full@2@option@2@: allow full printing
1385 1385 </para>
1386 1386 </listitem>
1387 1387 <listitem>
1388 1388 <para>
1389   - <option>low</option>: allow low-resolution printing only
  1389 + @1@option@1@low@2@option@2@: allow low-resolution printing only
1390 1390 </para>
1391 1391 </listitem>
1392 1392 <listitem>
1393 1393 <para>
1394   - <option>none</option>: disallow printing
  1394 + @1@option@1@none@2@option@2@: disallow printing
1395 1395 </para>
1396 1396 </listitem>
1397 1397 </itemizedlist>
... ... @@ -1399,53 +1399,53 @@ make
1399 1399 </listitem>
1400 1400 </varlistentry>
1401 1401 <varlistentry>
1402   - <term><option>--modify=<replaceable>modify-opt</replaceable></option></term>
  1402 + <term>@1@option@1@--modify=@1@replaceable@1@modify-opt@2@replaceable@2@@2@option@2@</term>
1403 1403 <listitem>
1404 1404 <para>
1405 1405 Controls modify access. This way of controlling modify access
1406 1406 has less granularity than new options added in qpdf 8.4.
1407   - <option><replaceable>modify-opt</replaceable></option> may be
  1407 + @1@option@1@@1@replaceable@1@modify-opt@2@replaceable@2@@2@option@2@ may be
1408 1408 one of the following:
1409 1409 <itemizedlist>
1410 1410 <listitem>
1411 1411 <para>
1412   - <option>all</option>: allow full document modification
  1412 + @1@option@1@all@2@option@2@: allow full document modification
1413 1413 </para>
1414 1414 </listitem>
1415 1415 <listitem>
1416 1416 <para>
1417   - <option>annotate</option>: allow comment authoring, form
  1417 + @1@option@1@annotate@2@option@2@: allow comment authoring, form
1418 1418 operations, and document assembly
1419 1419 </para>
1420 1420 </listitem>
1421 1421 <listitem>
1422 1422 <para>
1423   - <option>form</option>: allow form field fill-in and signing
  1423 + @1@option@1@form@2@option@2@: allow form field fill-in and signing
1424 1424 and document assembly
1425 1425 </para>
1426 1426 </listitem>
1427 1427 <listitem>
1428 1428 <para>
1429   - <option>assembly</option>: allow document assembly only
  1429 + @1@option@1@assembly@2@option@2@: allow document assembly only
1430 1430 </para>
1431 1431 </listitem>
1432 1432 <listitem>
1433 1433 <para>
1434   - <option>none</option>: allow no modifications
  1434 + @1@option@1@none@2@option@2@: allow no modifications
1435 1435 </para>
1436 1436 </listitem>
1437 1437 </itemizedlist>
1438   - Using the <option>--modify</option> option does not allow you
  1438 + Using the @1@option@1@--modify@2@option@2@ option does not allow you
1439 1439 to create certain combinations of permissions such as allowing
1440 1440 form filling but not allowing document assembly. Starting with
1441 1441 qpdf 8.4, you can either just use the other options to control
1442 1442 fields individually, or you can use something like
1443   - <option>--modify=form --assembly=n</option> to fine tune.
  1443 + @1@option@1@--modify=form --assembly=n@2@option@2@ to fine tune.
1444 1444 </para>
1445 1445 </listitem>
1446 1446 </varlistentry>
1447 1447 <varlistentry>
1448   - <term><option>--cleartext-metadata</option></term>
  1448 + <term>@1@option@1@--cleartext-metadata@2@option@2@</term>
1449 1449 <listitem>
1450 1450 <para>
1451 1451 If specified, any metadata stream in the document will be left
... ... @@ -1455,17 +1455,17 @@ make
1455 1455 </listitem>
1456 1456 </varlistentry>
1457 1457 <varlistentry>
1458   - <term><option>--use-aes=[yn]</option></term>
  1458 + <term>@1@option@1@--use-aes=[yn]@2@option@2@</term>
1459 1459 <listitem>
1460 1460 <para>
1461   - If <option>--use-aes=y</option> is specified, AES encryption
  1461 + If @1@option@1@--use-aes=y@2@option@2@ is specified, AES encryption
1462 1462 will be used instead of RC4 encryption. This forces the PDF
1463 1463 version to be at least 1.6.
1464 1464 </para>
1465 1465 </listitem>
1466 1466 </varlistentry>
1467 1467 <varlistentry>
1468   - <term><option>--allow-insecure</option></term>
  1468 + <term>@1@option@1@--allow-insecure@2@option@2@</term>
1469 1469 <listitem>
1470 1470 <para>
1471 1471 From qpdf 10.2, qpdf defaults to not allowing creation of PDF
... ... @@ -1480,7 +1480,7 @@ make
1480 1480 </listitem>
1481 1481 </varlistentry>
1482 1482 <varlistentry>
1483   - <term><option>--force-V4</option></term>
  1483 + <term>@1@option@1@--force-V4@2@option@2@</term>
1484 1484 <listitem>
1485 1485 <para>
1486 1486 Use of this option forces the <literal>/V</literal> and
... ... @@ -1494,14 +1494,14 @@ make
1494 1494 </listitem>
1495 1495 </varlistentry>
1496 1496 </variablelist>
1497   - If <option><replaceable>key-length</replaceable></option> is 256,
  1497 + If @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@ is 256,
1498 1498 the minimum PDF version is 1.7 with extension level 8, and the
1499 1499 AES-based encryption format used is the PDF 2.0 encryption method
1500 1500 supported by Acrobat X. the same options are available as with
1501 1501 128 bits with the following exceptions:
1502 1502 <variablelist>
1503 1503 <varlistentry>
1504   - <term><option>--use-aes</option></term>
  1504 + <term>@1@option@1@--use-aes@2@option@2@</term>
1505 1505 <listitem>
1506 1506 <para>
1507 1507 This option is not available with 256-bit keys. AES is always
... ... @@ -1510,7 +1510,7 @@ make
1510 1510 </listitem>
1511 1511 </varlistentry>
1512 1512 <varlistentry>
1513   - <term><option>--force-V4</option></term>
  1513 + <term>@1@option@1@--force-V4@2@option@2@</term>
1514 1514 <listitem>
1515 1515 <para>
1516 1516 This option is not available with 256 keys.
... ... @@ -1518,7 +1518,7 @@ make
1518 1518 </listitem>
1519 1519 </varlistentry>
1520 1520 <varlistentry>
1521   - <term><option>--force-R5</option></term>
  1521 + <term>@1@option@1@--force-R5@2@option@2@</term>
1522 1522 <listitem>
1523 1523 <para>
1524 1524 If specified, qpdf sets the minimum version to 1.7 at
... ... @@ -1543,17 +1543,17 @@ make
1543 1543 file is given as the primary input file is used as the starting
1544 1544 point, but its pages are replaced with pages as specified.
1545 1545  
1546   - <programlisting><option>--pages <replaceable>input-file</replaceable> [ <replaceable>--password=password</replaceable> ] [ <replaceable>page-range</replaceable> ] [ ... ] --</option>
  1546 + <programlisting>@1@option@1@--pages @1@replaceable@1@input-file@2@replaceable@2@ [ @1@replaceable@1@--password=password@2@replaceable@2@ ] [ @1@replaceable@1@page-range@2@replaceable@2@ ] [ ... ] --@2@option@2@
1547 1547 </programlisting>
1548 1548 Multiple input files may be specified. Each one is given as the
1549 1549 name of the input file, an optional password (if required to open
1550 1550 the file), and the range of pages. Note that
1551   - &ldquo;<option>--</option>&rdquo; terminates parsing of page
  1551 + &ldquo;@1@option@1@--@2@option@2@&rdquo; terminates parsing of page
1552 1552 selection flags.
1553 1553 </para>
1554 1554 <para>
1555 1555 Starting with qpf 8.4, the special input file name
1556   - &ldquo;<filename>.</filename>&rdquo; can be used as a shortcut for the
  1556 + &ldquo;@1@filename@1@.@2@filename@2@&rdquo; can be used as a shortcut for the
1557 1557 primary input filename.
1558 1558 </para>
1559 1559 <para>
... ... @@ -1566,7 +1566,7 @@ make
1566 1566 multiple times. If a file that is repeated has a password, the
1567 1567 password only has to be given the first time. All non-page data
1568 1568 (info, outlines, page numbers, etc.) are taken from the primary
1569   - input file. To discard these, use <option>--empty</option> as the
  1569 + input file. To discard these, use @1@option@1@--empty@2@option@2@ as the
1570 1570 primary input.
1571 1571 </para>
1572 1572 <para>
... ... @@ -1576,7 +1576,7 @@ make
1576 1576 will implicitly use the range <literal>1-z</literal>, meaning that
1577 1577 it will include all pages in the file. This makes it possible to
1578 1578 easily combine all pages in a set of files with a command like
1579   - <command>qpdf --empty out.pdf --pages *.pdf --</command>.
  1579 + @1@command@1@qpdf --empty out.pdf --pages *.pdf --@2@command@2@.
1580 1580 </para>
1581 1581 <para>
1582 1582 The page range is a set of numbers separated by commas, ranges of
... ... @@ -1634,22 +1634,22 @@ make
1634 1634 </para>
1635 1635 <para>
1636 1636 Starting in qpdf version 8.3, you can specify the
1637   - <option>--collate</option> option. Note that this option is
1638   - specified outside of <option>--pages&nbsp;...&nbsp;--</option>.
1639   - When <option>--collate</option> is specified, it changes the
1640   - meaning of <option>--pages</option> so that the specified files,
  1637 + @1@option@1@--collate@2@option@2@ option. Note that this option is
  1638 + specified outside of @1@option@1@--pages&nbsp;...&nbsp;--@2@option@2@.
  1639 + When @1@option@1@--collate@2@option@2@ is specified, it changes the
  1640 + meaning of @1@option@1@--pages@2@option@2@ so that the specified files,
1641 1641 as modified by page ranges, are collated rather than concatenated.
1642   - For example, if you add the files <filename>odd.pdf</filename> and
1643   - <filename>even.pdf</filename> containing odd and even pages of a
1644   - document respectively, you could run <command>qpdf --collate
1645   - odd.pdf --pages odd.pdf even.pdf -- all.pdf</command> to collate
  1642 + For example, if you add the files @1@filename@1@odd.pdf@2@filename@2@ and
  1643 + @1@filename@1@even.pdf@2@filename@2@ containing odd and even pages of a
  1644 + document respectively, you could run @1@command@1@qpdf --collate
  1645 + odd.pdf --pages odd.pdf even.pdf -- all.pdf@2@command@2@ to collate
1646 1646 the pages. This would pick page 1 from odd, page 1 from even, page
1647 1647 2 from odd, page 2 from even, etc. until all pages have been
1648 1648 included. Any number of files and page ranges can be specified. If
1649 1649 any file has fewer pages, that file is just skipped when its pages
1650   - have all been included. For example, if you ran <command>qpdf
  1650 + have all been included. For example, if you ran @1@command@1@qpdf
1651 1651 --collate --empty --pages a.pdf 1-5 b.pdf 6-4 c.pdf r1 --
1652   - out.pdf</command>, you would get the following pages in this
  1652 + out.pdf@2@command@2@, you would get the following pages in this
1653 1653 order:
1654 1654 <itemizedlist>
1655 1655 <listitem><para>a.pdf page 1</para></listitem>
... ... @@ -1665,12 +1665,12 @@ make
1665 1665 </para>
1666 1666 <para>
1667 1667 Starting in qpdf version 10.2, you may specify a numeric argument
1668   - to <option>--collate</option>. With
1669   - <option>--collate=<replaceable>n</replaceable></option>, pull
1670   - groups of <replaceable>n</replaceable> pages from each file,
  1668 + to @1@option@1@--collate@2@option@2@. With
  1669 + @1@option@1@--collate=@1@replaceable@1@n@2@replaceable@2@@2@option@2@, pull
  1670 + groups of @1@replaceable@1@n@2@replaceable@2@ pages from each file,
1671 1671 again, stopping when there are no more pages. For example, if you
1672   - ran <command>qpdf --collate=2 --empty --pages a.pdf 1-5 b.pdf 6-4
1673   - c.pdf r1 -- out.pdf</command>, you would get the following pages
  1672 + ran @1@command@1@qpdf --collate=2 --empty --pages a.pdf 1-5 b.pdf 6-4
  1673 + c.pdf r1 -- out.pdf@2@command@2@, you would get the following pages
1674 1674 in this order:
1675 1675 <itemizedlist>
1676 1676 <listitem><para>a.pdf page 1</para></listitem>
... ... @@ -1693,46 +1693,46 @@ make
1693 1693 outlines (bookmarks) point to actual page objects, so if you
1694 1694 select some pages and not others, bookmarks that point to pages
1695 1695 that are in the output file will work, and remaining bookmarks
1696   - will not work. A future version of <command>qpdf</command> may do
  1696 + will not work. A future version of @1@command@1@qpdf@2@command@2@ may do
1697 1697 a better job at handling these issues. (Note that the qpdf library
1698 1698 already contains all of the APIs required in order to implement
1699 1699 this in your own application if you need it.) In the mean time,
1700   - you can always use <option>--empty</option> as the primary input
  1700 + you can always use @1@option@1@--empty@2@option@2@ as the primary input
1701 1701 file to avoid copying all of that from the first file. For
1702 1702 example, to take pages 1 through 5 from a
1703   - <filename>infile.pdf</filename> while preserving all metadata
  1703 + @1@filename@1@infile.pdf@2@filename@2@ while preserving all metadata
1704 1704 associated with that file, you could use
1705 1705  
1706   - <programlisting><command>qpdf</command> <option>infile.pdf --pages . 1-5 -- outfile.pdf</option>
  1706 + <programlisting>@1@command@1@qpdf@2@command@2@ @1@option@1@infile.pdf --pages . 1-5 -- outfile.pdf@2@option@2@
1707 1707 </programlisting>
1708 1708 If you wanted pages 1 through 5 from
1709   - <filename>infile.pdf</filename> but you wanted the rest of the
  1709 + @1@filename@1@infile.pdf@2@filename@2@ but you wanted the rest of the
1710 1710 metadata to be dropped, you could instead run
1711 1711  
1712   - <programlisting><command>qpdf</command> <option>--empty --pages infile.pdf 1-5 -- outfile.pdf</option>
  1712 + <programlisting>@1@command@1@qpdf@2@command@2@ @1@option@1@--empty --pages infile.pdf 1-5 -- outfile.pdf@2@option@2@
1713 1713 </programlisting>
1714 1714 If you wanted to take pages 1&ndash;5 from
1715   - <filename>file1.pdf</filename> and pages 11&ndash;15 from
1716   - <filename>file2.pdf</filename> in reverse, taking document-level
1717   - metadata from <filename>file2.pdf</filename>, you would run
  1715 + @1@filename@1@file1.pdf@2@filename@2@ and pages 11&ndash;15 from
  1716 + @1@filename@1@file2.pdf@2@filename@2@ in reverse, taking document-level
  1717 + metadata from @1@filename@1@file2.pdf@2@filename@2@, you would run
1718 1718  
1719   - <programlisting><command>qpdf</command> <option>file2.pdf --pages file1.pdf 1-5 . 15-11 -- outfile.pdf</option>
  1719 + <programlisting>@1@command@1@qpdf@2@command@2@ @1@option@1@file2.pdf --pages file1.pdf 1-5 . 15-11 -- outfile.pdf@2@option@2@
1720 1720 </programlisting>
1721 1721 If, for some reason, you wanted to take the first page of an
1722   - encrypted file called <filename>encrypted.pdf</filename> with
  1722 + encrypted file called @1@filename@1@encrypted.pdf@2@filename@2@ with
1723 1723 password <literal>pass</literal> and repeat it twice in an output
1724 1724 file, and if you wanted to drop document-level metadata but
1725 1725 preserve encryption, you would use
1726 1726  
1727   - <programlisting><command>qpdf</command> <option>--empty --copy-encryption=encrypted.pdf --encryption-file-password=pass
  1727 + <programlisting>@1@command@1@qpdf@2@command@2@ @1@option@1@--empty --copy-encryption=encrypted.pdf --encryption-file-password=pass
1728 1728 --pages encrypted.pdf --password=pass 1 ./encrypted.pdf --password=pass 1 --
1729   -outfile.pdf</option>
  1729 +outfile.pdf@2@option@2@
1730 1730 </programlisting>
1731 1731 Note that we had to specify the password all three times because
1732   - giving a password as <option>--encryption-file-password</option>
  1732 + giving a password as @1@option@1@--encryption-file-password@2@option@2@
1733 1733 doesn't count for page selection, and as far as qpdf is concerned,
1734   - <filename>encrypted.pdf</filename> and
1735   - <filename>./encrypted.pdf</filename> are separated files. These
  1734 + @1@filename@1@encrypted.pdf@2@filename@2@ and
  1735 + @1@filename@1@./encrypted.pdf@2@filename@2@ are separated files. These
1736 1736 are all corner cases that most users should hopefully never have
1737 1737 to be bothered with.
1738 1738 </para>
... ... @@ -1746,7 +1746,7 @@ outfile.pdf&lt;/option&gt;
1746 1746 going to do further manipulation on the file and need the two
1747 1747 instances of the same original page to be deep copies, then you
1748 1748 can specify the file in two different ways. For example
1749   - <command>qpdf in.pdf --pages . 1 ./in.pdf 1 -- out.pdf</command>
  1749 + @1@command@1@qpdf in.pdf --pages . 1 ./in.pdf 1 -- out.pdf@2@command@2@
1750 1750 would create a file with two copies of the first page of the
1751 1751 input, and the two copies would share any objects in common. This
1752 1752 includes fonts, images, and anything else the page references.
... ... @@ -1759,12 +1759,12 @@ outfile.pdf&lt;/option&gt;
1759 1759 pages from other files onto the output generated by qpdf. Specify
1760 1760 overlay or underlay as follows:
1761 1761  
1762   - <programlisting>{ <option>--overlay</option> | <option>--underlay</option> } <replaceable>file</replaceable> [ <option>options</option> ] <option>--</option>
  1762 + <programlisting>{ @1@option@1@--overlay@2@option@2@ | @1@option@1@--underlay@2@option@2@ } @1@replaceable@1@file@2@replaceable@2@ [ @1@option@1@options@2@option@2@ ] @1@option@1@--@2@option@2@
1763 1763 </programlisting>
1764 1764 Overlay and underlay options are processed late, so they can be
1765 1765 combined with other like merging and will apply to the final
1766   - output. The <option>--overlay</option> and
1767   - <option>--underlay</option> options work the same way, except
  1766 + output. The @1@option@1@--overlay@2@option@2@ and
  1767 + @1@option@1@--underlay@2@option@2@ options work the same way, except
1768 1768 underlay pages are drawn underneath the page to which they are
1769 1769 applied, possibly obscured by the original page, and overlay files
1770 1770 are drawn on top of the page to which they are applied, possibly
... ... @@ -1777,19 +1777,19 @@ outfile.pdf&lt;/option&gt;
1777 1777 pages. If the overlay or underlay file runs out of pages,
1778 1778 remaining output pages are left alone. This behavior can be
1779 1779 modified by options, which are provided between the
1780   - <option>--overlay</option> or <option>--underlay</option> flag and
1781   - the <option>--</option> option. The following options are
  1780 + @1@option@1@--overlay@2@option@2@ or @1@option@1@--underlay@2@option@2@ flag and
  1781 + the @1@option@1@--@2@option@2@ option. The following options are
1782 1782 supported:
1783 1783 <itemizedlist>
1784 1784 <listitem>
1785 1785 <para>
1786   - <option>--password=password</option>: supply a password if the
  1786 + @1@option@1@--password=password@2@option@2@: supply a password if the
1787 1787 overlay/underlay file is encrypted.
1788 1788 </para>
1789 1789 </listitem>
1790 1790 <listitem>
1791 1791 <para>
1792   - <option>--to=page-range</option>: a range of pages in the same
  1792 + @1@option@1@--to=page-range@2@option@2@: a range of pages in the same
1793 1793 form at described in <xref linkend="ref.page-selection"/>
1794 1794 indicates which pages in the output should have the
1795 1795 overlay/underlay applied. If not specified, overlay/underlay
... ... @@ -1798,20 +1798,20 @@ outfile.pdf&lt;/option&gt;
1798 1798 </listitem>
1799 1799 <listitem>
1800 1800 <para>
1801   - <option>--from=[page-range]</option>: a range of pages that
  1801 + @1@option@1@--from=[page-range]@2@option@2@: a range of pages that
1802 1802 specifies which pages in the overlay/underlay file will be used
1803 1803 for overlay or underlay. If not specified, all pages will be
1804 1804 used. This can be explicitly specified to be empty if
1805   - <option>--repeat</option> is used.
  1805 + @1@option@1@--repeat@2@option@2@ is used.
1806 1806 </para>
1807 1807 </listitem>
1808 1808 <listitem>
1809 1809 <para>
1810   - <option>--repeat=page-range</option>: an optional range of
  1810 + @1@option@1@--repeat=page-range@2@option@2@: an optional range of
1811 1811 pages that specifies which pages in the overlay/underlay file
1812 1812 will be repeated after the &ldquo;from&rdquo; pages are used
1813 1813 up. If you want to repeat a range of pages starting at the
1814   - beginning, you can explicitly use <option>--from=</option>.
  1814 + beginning, you can explicitly use @1@option@1@--from=@2@option@2@.
1815 1815 </para>
1816 1816 </listitem>
1817 1817 </itemizedlist>
... ... @@ -1821,20 +1821,20 @@ outfile.pdf&lt;/option&gt;
1821 1821 <itemizedlist>
1822 1822 <listitem>
1823 1823 <para>
1824   - <command>--overlay o.pdf --to=1-5 --from=1-3
1825   - --repeat=4 --</command>: overlay the first three pages from file
1826   - <filename>o.pdf</filename> onto the first three pages of the
1827   - output, then overlay page 4 from <filename>o.pdf</filename>
  1824 + @1@command@1@--overlay o.pdf --to=1-5 --from=1-3
  1825 + --repeat=4 --@2@command@2@: overlay the first three pages from file
  1826 + @1@filename@1@o.pdf@2@filename@2@ onto the first three pages of the
  1827 + output, then overlay page 4 from @1@filename@1@o.pdf@2@filename@2@
1828 1828 onto pages 4 and 5 of the output. Leave remaining output pages
1829 1829 untouched.
1830 1830 </para>
1831 1831 </listitem>
1832 1832 <listitem>
1833 1833 <para>
1834   - <command>--underlay footer.pdf --from= --repeat=1,2 --</command>:
1835   - Underlay page 1 of <filename>footer.pdf</filename> on all odd
  1834 + @1@command@1@--underlay footer.pdf --from= --repeat=1,2 --@2@command@2@:
  1835 + Underlay page 1 of @1@filename@1@footer.pdf@2@filename@2@ on all odd
1836 1836 output pages, and underlay page 2 of
1837   - <filename>footer.pdf</filename> on all even output pages.
  1837 + @1@filename@1@footer.pdf@2@filename@2@ on all even output pages.
1838 1838 </para>
1839 1839 </listitem>
1840 1840 </itemizedlist>
... ... @@ -1847,11 +1847,11 @@ outfile.pdf&lt;/option&gt;
1847 1847 files from the command line. The following options are available:
1848 1848 <variablelist>
1849 1849 <varlistentry>
1850   - <term><option>--list-attachments</option></term>
  1850 + <term>@1@option@1@--list-attachments@2@option@2@</term>
1851 1851 <listitem>
1852 1852 <para>
1853 1853 Show the &ldquo;key&rdquo; and stream number for embedded
1854   - files. With <option>--verbose</option>, additional
  1854 + files. With @1@option@1@--verbose@2@option@2@, additional
1855 1855 information, including preferred file name, description,
1856 1856 dates, and more are also displayed. The key is usually but not
1857 1857 always equal to the file name, and is needed by some of the
... ... @@ -1860,48 +1860,48 @@ outfile.pdf&lt;/option&gt;
1860 1860 </listitem>
1861 1861 </varlistentry>
1862 1862 <varlistentry>
1863   - <term><option>--show-attachment=<replaceable>key</replaceable></option></term>
  1863 + <term>@1@option@1@--show-attachment=@1@replaceable@1@key@2@replaceable@2@@2@option@2@</term>
1864 1864 <listitem>
1865 1865 <para>
1866 1866 Write the contents of the specified attachment to standard
1867 1867 output as binary data. The key should match one of the keys
1868   - shown by <option>--list-attachments</option>. If specified
  1868 + shown by @1@option@1@--list-attachments@2@option@2@. If specified
1869 1869 multiple times, only the last attachment will be shown.
1870 1870 </para>
1871 1871 </listitem>
1872 1872 </varlistentry>
1873 1873 <varlistentry>
1874   - <term><option>--add-attachment <replaceable>file</replaceable> <replaceable>options</replaceable> --</option></term>
  1874 + <term>@1@option@1@--add-attachment @1@replaceable@1@file@2@replaceable@2@ @1@replaceable@1@options@2@replaceable@2@ --@2@option@2@</term>
1875 1875 <listitem>
1876 1876 <para>
1877 1877 Add or replace an attachment with the contents of
1878   - <replaceable>file</replaceable>. This may be specified more
  1878 + @1@replaceable@1@file@2@replaceable@2@. This may be specified more
1879 1879 than once. The following additional options may appear before
1880 1880 the <literal>--</literal> that ends this option:
1881 1881 <variablelist>
1882 1882 <varlistentry>
1883   - <term><option>--key=<replaceable>key</replaceable></option></term>
  1883 + <term>@1@option@1@--key=@1@replaceable@1@key@2@replaceable@2@@2@option@2@</term>
1884 1884 <listitem>
1885 1885 <para>
1886 1886 The key to use to register the attachment in the embedded
1887 1887 files table. Defaults to the last path element of
1888   - <replaceable>file</replaceable>.
  1888 + @1@replaceable@1@file@2@replaceable@2@.
1889 1889 </para>
1890 1890 </listitem>
1891 1891 </varlistentry>
1892 1892 <varlistentry>
1893   - <term><option>--filename=<replaceable>name</replaceable></option></term>
  1893 + <term>@1@option@1@--filename=@1@replaceable@1@name@2@replaceable@2@@2@option@2@</term>
1894 1894 <listitem>
1895 1895 <para>
1896 1896 The file name to be used for the attachment. This is what is usually
1897 1897 displayed to the user and is the name most graphical PDF
1898 1898 viewers will use when saving a file. It defaults to the
1899   - last path element of <replaceable>file</replaceable>.
  1899 + last path element of @1@replaceable@1@file@2@replaceable@2@.
1900 1900 </para>
1901 1901 </listitem>
1902 1902 </varlistentry>
1903 1903 <varlistentry>
1904   - <term><option>--creationdate=<replaceable>date</replaceable></option></term>
  1904 + <term>@1@option@1@--creationdate=@1@replaceable@1@date@2@replaceable@2@@2@option@2@</term>
1905 1905 <listitem>
1906 1906 <para>
1907 1907 The attachment's creation date in PDF format; defaults to
... ... @@ -1910,7 +1910,7 @@ outfile.pdf&lt;/option&gt;
1910 1910 </listitem>
1911 1911 </varlistentry>
1912 1912 <varlistentry>
1913   - <term><option>--moddate=<replaceable>date</replaceable></option></term>
  1913 + <term>@1@option@1@--moddate=@1@replaceable@1@date@2@replaceable@2@@2@option@2@</term>
1914 1914 <listitem>
1915 1915 <para>
1916 1916 The attachment's modification date in PDF format; defaults
... ... @@ -1919,7 +1919,7 @@ outfile.pdf&lt;/option&gt;
1919 1919 </listitem>
1920 1920 </varlistentry>
1921 1921 <varlistentry>
1922   - <term><option>--mimetype=<replaceable>type/subtype</replaceable></option></term>
  1922 + <term>@1@option@1@--mimetype=@1@replaceable@1@type/subtype@2@replaceable@2@@2@option@2@</term>
1923 1923 <listitem>
1924 1924 <para>
1925 1925 The mime type for the attachment, e.g.
... ... @@ -1932,7 +1932,7 @@ outfile.pdf&lt;/option&gt;
1932 1932 </listitem>
1933 1933 </varlistentry>
1934 1934 <varlistentry>
1935   - <term><option>--description=<replaceable>&quot;text&quot;</replaceable></option></term>
  1935 + <term>@1@option@1@--description=@1@replaceable@1@&quot;text&quot;@2@replaceable@2@@2@option@2@</term>
1936 1936 <listitem>
1937 1937 <para>
1938 1938 Descriptive text for the attachment, displayed by some PDF
... ... @@ -1941,12 +1941,12 @@ outfile.pdf&lt;/option&gt;
1941 1941 </listitem>
1942 1942 </varlistentry>
1943 1943 <varlistentry>
1944   - <term><option>--replace</option></term>
  1944 + <term>@1@option@1@--replace@2@option@2@</term>
1945 1945 <listitem>
1946 1946 <para>
1947 1947 Indicates that any existing attachment with the same key
1948 1948 should be replaced by the new attachment. Otherwise,
1949   - <command>qpdf</command> gives an error if an attachment
  1949 + @1@command@1@qpdf@2@command@2@ gives an error if an attachment
1950 1950 with that key is already present.
1951 1951 </para>
1952 1952 </listitem>
... ... @@ -1956,20 +1956,20 @@ outfile.pdf&lt;/option&gt;
1956 1956 </listitem>
1957 1957 </varlistentry>
1958 1958 <varlistentry>
1959   - <term><option>--remove-attachment=<replaceable>key</replaceable></option></term>
  1959 + <term>@1@option@1@--remove-attachment=@1@replaceable@1@key@2@replaceable@2@@2@option@2@</term>
1960 1960 <listitem>
1961 1961 <para>
1962 1962 Remove the specified attachment. This doesn't only remove the
1963 1963 attachment from the embedded files table but also clears out
1964 1964 the file specification. That means that any potential internal
1965 1965 links to the attachment will be broken. This option may be
1966   - specified multiple times. Run with <option>--verbose</option>
  1966 + specified multiple times. Run with @1@option@1@--verbose@2@option@2@
1967 1967 to see status of the removal.
1968 1968 </para>
1969 1969 </listitem>
1970 1970 </varlistentry>
1971 1971 <varlistentry>
1972   - <term><option>--copy-attachments-from <replaceable>file</replaceable> <replaceable>options</replaceable> --</option></term>
  1972 + <term>@1@option@1@--copy-attachments-from @1@replaceable@1@file@2@replaceable@2@ @1@replaceable@1@options@2@replaceable@2@ --@2@option@2@</term>
1973 1973 <listitem>
1974 1974 <para>
1975 1975 Copy attachments from another file. This may be specified more
... ... @@ -1977,16 +1977,16 @@ outfile.pdf&lt;/option&gt;
1977 1977 the <literal>--</literal> that ends this option:
1978 1978 <variablelist>
1979 1979 <varlistentry>
1980   - <term><option>--password=<replaceable>password</replaceable></option></term>
  1980 + <term>@1@option@1@--password=@1@replaceable@1@password@2@replaceable@2@@2@option@2@</term>
1981 1981 <listitem>
1982 1982 <para>
1983 1983 If required, the password needed to open
1984   - <replaceable>file</replaceable>
  1984 + @1@replaceable@1@file@2@replaceable@2@
1985 1985 </para>
1986 1986 </listitem>
1987 1987 </varlistentry>
1988 1988 <varlistentry>
1989   - <term><option>--prefix=<replaceable>prefix</replaceable></option></term>
  1989 + <term>@1@option@1@--prefix=@1@replaceable@1@prefix@2@replaceable@2@@2@option@2@</term>
1990 1990 <listitem>
1991 1991 <para>
1992 1992 Only required if the file from which attachments are being
... ... @@ -2006,11 +2006,11 @@ outfile.pdf&lt;/option&gt;
2006 2006 </variablelist>
2007 2007 When a date is required, the date should conform to the PDF date
2008 2008 format specification, which is
2009   - <literal>D:</literal><replaceable>yyyymmddhhmmss&lt;z&gt;</replaceable>,
2010   - where <replaceable>&lt;z&gt;</replaceable> is either
  2009 + <literal>D:</literal>@1@replaceable@1@yyyymmddhhmmss&lt;z&gt;@2@replaceable@2@,
  2010 + where @1@replaceable@1@&lt;z&gt;@2@replaceable@2@ is either
2011 2011 <literal>Z</literal> for UTC or a timezone offset in the form
2012   - <replaceable>-hh'mm'</replaceable> or
2013   - <replaceable>+hh'mm'</replaceable>. Examples:
  2012 + @1@replaceable@1@-hh'mm'@2@replaceable@2@ or
  2013 + @1@replaceable@1@+hh'mm'@2@replaceable@2@. Examples:
2014 2014 <literal>D:20210207161528-05'00'</literal>,
2015 2015 <literal>D:20210207211528Z</literal>.
2016 2016 </para>
... ... @@ -2024,7 +2024,7 @@ outfile.pdf&lt;/option&gt;
2024 2024 to solve specific problems. The following options are available:
2025 2025 <variablelist>
2026 2026 <varlistentry>
2027   - <term><option>--suppress-recovery</option></term>
  2027 + <term>@1@option@1@--suppress-recovery@2@option@2@</term>
2028 2028 <listitem>
2029 2029 <para>
2030 2030 Prevents qpdf from attempting to recover damaged files.
... ... @@ -2032,7 +2032,7 @@ outfile.pdf&lt;/option&gt;
2032 2032 </listitem>
2033 2033 </varlistentry>
2034 2034 <varlistentry>
2035   - <term><option>--ignore-xref-streams</option></term>
  2035 + <term>@1@option@1@--ignore-xref-streams@2@option@2@</term>
2036 2036 <listitem>
2037 2037 <para>
2038 2038 Tells qpdf to ignore any cross-reference streams.
... ... @@ -2048,13 +2048,13 @@ outfile.pdf&lt;/option&gt;
2048 2048 of stream length errors. Sometimes, qpdf may think it has
2049 2049 recovered but may not have actually recovered, so care should be
2050 2050 taken when using this option as some data loss is possible. The
2051   - <option>--suppress-recovery</option> option will prevent qpdf from
  2051 + @1@option@1@--suppress-recovery@2@option@2@ option will prevent qpdf from
2052 2052 attempting recovery. In this case, it will fail on the first
2053 2053 error that it encounters.
2054 2054 </para>
2055 2055 <para>
2056 2056 Ordinarily, qpdf reads cross-reference streams when they are
2057   - present in a PDF file. If <option>--ignore-xref-streams</option>
  2057 + present in a PDF file. If @1@option@1@--ignore-xref-streams@2@option@2@
2058 2058 is specified, qpdf will ignore any cross-reference streams for
2059 2059 hybrid PDF files. The purpose of hybrid files is to make some
2060 2060 content available to viewers that are not aware of cross-reference
... ... @@ -2074,34 +2074,34 @@ outfile.pdf&lt;/option&gt;
2074 2074 developers. The following options are available:
2075 2075 <variablelist>
2076 2076 <varlistentry>
2077   - <term><option>--compress-streams=<replaceable>[yn]</replaceable></option></term>
  2077 + <term>@1@option@1@--compress-streams=@1@replaceable@1@[yn]@2@replaceable@2@@2@option@2@</term>
2078 2078 <listitem>
2079 2079 <para>
2080   - By default, or with <option>--compress-streams=y</option>,
  2080 + By default, or with @1@option@1@--compress-streams=y@2@option@2@,
2081 2081 qpdf will compress any stream with no other filters applied to
2082 2082 it with the <literal>/FlateDecode</literal> filter when it
2083 2083 writes it. To suppress this behavior and preserve uncompressed
2084 2084 streams as uncompressed, use
2085   - <option>--compress-streams=n</option>.
  2085 + @1@option@1@--compress-streams=n@2@option@2@.
2086 2086 </para>
2087 2087 </listitem>
2088 2088 </varlistentry>
2089 2089 <varlistentry>
2090   - <term><option>--decode-level=<replaceable>option</replaceable></option></term>
  2090 + <term>@1@option@1@--decode-level=@1@replaceable@1@option@2@replaceable@2@@2@option@2@</term>
2091 2091 <listitem>
2092 2092 <para>
2093 2093 Controls which streams qpdf tries to decode. The default is
2094   - <option>generalized</option>. The following options are
  2094 + @1@option@1@generalized@2@option@2@. The following options are
2095 2095 available:
2096 2096 <itemizedlist>
2097 2097 <listitem>
2098 2098 <para>
2099   - <option>none</option>: do not attempt to decode any streams
  2099 + @1@option@1@none@2@option@2@: do not attempt to decode any streams
2100 2100 </para>
2101 2101 </listitem>
2102 2102 <listitem>
2103 2103 <para>
2104   - <option>generalized</option>: decode streams filtered with
  2104 + @1@option@1@generalized@2@option@2@: decode streams filtered with
2105 2105 supported generalized filters:
2106 2106 <literal>/LZWDecode</literal>,
2107 2107 <literal>/FlateDecode</literal>,
... ... @@ -2112,12 +2112,12 @@ outfile.pdf&lt;/option&gt;
2112 2112 for image data. Note that, by default, streams already
2113 2113 compressed with <literal>/FlateDecode</literal> are not
2114 2114 uncompressed and recompressed unless you also specify
2115   - <option>--recompress-flate</option>.
  2115 + @1@option@1@--recompress-flate@2@option@2@.
2116 2116 </para>
2117 2117 </listitem>
2118 2118 <listitem>
2119 2119 <para>
2120   - <option>specialized</option>: in addition to generalized,
  2120 + @1@option@1@specialized@2@option@2@: in addition to generalized,
2121 2121 decode streams with supported non-lossy specialized
2122 2122 filters; currently this is just
2123 2123 <literal>/RunLengthDecode</literal>
... ... @@ -2125,7 +2125,7 @@ outfile.pdf&lt;/option&gt;
2125 2125 </listitem>
2126 2126 <listitem>
2127 2127 <para>
2128   - <option>all</option>: in addition to generalized and
  2128 + @1@option@1@all@2@option@2@: in addition to generalized and
2129 2129 specialized, decode streams with supported lossy filters;
2130 2130 currently this is just <literal>/DCTDecode</literal> (JPEG)
2131 2131 </para>
... ... @@ -2135,40 +2135,40 @@ outfile.pdf&lt;/option&gt;
2135 2135 </listitem>
2136 2136 </varlistentry>
2137 2137 <varlistentry>
2138   - <term><option>--stream-data=<replaceable>option</replaceable></option></term>
  2138 + <term>@1@option@1@--stream-data=@1@replaceable@1@option@2@replaceable@2@@2@option@2@</term>
2139 2139 <listitem>
2140 2140 <para>
2141 2141 Controls transformation of stream data. This option predates
2142   - the <option>--compress-streams</option> and
2143   - <option>--decode-level</option> options. Those options can be
  2142 + the @1@option@1@--compress-streams@2@option@2@ and
  2143 + @1@option@1@--decode-level@2@option@2@ options. Those options can be
2144 2144 used to achieve the same affect with more control. The value
2145   - of <option><replaceable>option</replaceable></option> may be
  2145 + of @1@option@1@@1@replaceable@1@option@2@replaceable@2@@2@option@2@ may be
2146 2146 one of the following:
2147 2147 <itemizedlist>
2148 2148 <listitem>
2149 2149 <para>
2150   - <option>compress</option>: recompress stream data when
  2150 + @1@option@1@compress@2@option@2@: recompress stream data when
2151 2151 possible (default); equivalent to
2152   - <option>--compress-streams=y</option>
2153   - <option>--decode-level=generalized</option>. Does not
  2152 + @1@option@1@--compress-streams=y@2@option@2@
  2153 + @1@option@1@--decode-level=generalized@2@option@2@. Does not
2154 2154 recompress streams already compressed with
2155 2155 <literal>/FlateDecode</literal> unless
2156   - <option>--recompress-flate</option> is also specified.
  2156 + @1@option@1@--recompress-flate@2@option@2@ is also specified.
2157 2157 </para>
2158 2158 </listitem>
2159 2159 <listitem>
2160 2160 <para>
2161   - <option>preserve</option>: leave all stream data as is;
2162   - equivalent to <option>--compress-streams=n</option>
2163   - <option>--decode-level=none</option>
  2161 + @1@option@1@preserve@2@option@2@: leave all stream data as is;
  2162 + equivalent to @1@option@1@--compress-streams=n@2@option@2@
  2163 + @1@option@1@--decode-level=none@2@option@2@
2164 2164 </para>
2165 2165 </listitem>
2166 2166 <listitem>
2167 2167 <para>
2168   - <option>uncompress</option>: uncompress stream data
  2168 + @1@option@1@uncompress@2@option@2@: uncompress stream data
2169 2169 compressed with generalized filters when possible;
2170   - equivalent to <option>--compress-streams=n</option>
2171   - <option>--decode-level=generalized</option>
  2170 + equivalent to @1@option@1@--compress-streams=n@2@option@2@
  2171 + @1@option@1@--decode-level=generalized@2@option@2@
2172 2172 </para>
2173 2173 </listitem>
2174 2174 </itemizedlist>
... ... @@ -2176,7 +2176,7 @@ outfile.pdf&lt;/option&gt;
2176 2176 </listitem>
2177 2177 </varlistentry>
2178 2178 <varlistentry>
2179   - <term><option>--recompress-flate</option></term>
  2179 + <term>@1@option@1@--recompress-flate@2@option@2@</term>
2180 2180 <listitem>
2181 2181 <para>
2182 2182 By default, streams already compressed with
... ... @@ -2185,29 +2185,29 @@ outfile.pdf&lt;/option&gt;
2185 2185 to uncompress and recompress the streams. There is a
2186 2186 significant performance cost to using this option, but you
2187 2187 probably want to use it if you specify
2188   - <option>--compression-level</option>.
  2188 + @1@option@1@--compression-level@2@option@2@.
2189 2189 </para>
2190 2190 </listitem>
2191 2191 </varlistentry>
2192 2192 <varlistentry>
2193   - <term><option>--compression-level=<replaceable>level</replaceable></option></term>
  2193 + <term>@1@option@1@--compression-level=@1@replaceable@1@level@2@replaceable@2@@2@option@2@</term>
2194 2194 <listitem>
2195 2195 <para>
2196 2196 When writing new streams that are compressed with
2197 2197 <literal>/FlateDecode</literal>, use the specified compression
2198   - level. The value of <option>level</option> should be a number
  2198 + level. The value of @1@option@1@level@2@option@2@ should be a number
2199 2199 from 1 to 9 and is passed directly to zlib, which implements
2200 2200 deflate compression. Note that qpdf doesn't uncompress and
2201 2201 recompress streams by default. To have this option apply to
2202 2202 already compressed streams, you should also specify
2203   - <option>--recompress-flate</option>. If your goal is to shrink
  2203 + @1@option@1@--recompress-flate@2@option@2@. If your goal is to shrink
2204 2204 the size of PDF files, you should also use
2205   - <option>--object-streams=generate</option>.
  2205 + @1@option@1@--object-streams=generate@2@option@2@.
2206 2206 </para>
2207 2207 </listitem>
2208 2208 </varlistentry>
2209 2209 <varlistentry>
2210   - <term><option>--normalize-content=[yn]</option></term>
  2210 + <term>@1@option@1@--normalize-content=[yn]@2@option@2@</term>
2211 2211 <listitem>
2212 2212 <para>
2213 2213 Enables or disables normalization of content streams. Content
... ... @@ -2218,27 +2218,27 @@ outfile.pdf&lt;/option&gt;
2218 2218 </listitem>
2219 2219 </varlistentry>
2220 2220 <varlistentry>
2221   - <term><option>--object-streams=<replaceable>mode</replaceable></option></term>
  2221 + <term>@1@option@1@--object-streams=@1@replaceable@1@mode@2@replaceable@2@@2@option@2@</term>
2222 2222 <listitem>
2223 2223 <para>
2224 2224 Controls handling of object streams. The value of
2225   - <option><replaceable>mode</replaceable></option> may be one of
  2225 + @1@option@1@@1@replaceable@1@mode@2@replaceable@2@@2@option@2@ may be one of
2226 2226 the following:
2227 2227 <itemizedlist>
2228 2228 <listitem>
2229 2229 <para>
2230   - <option>preserve</option>: preserve original object streams
  2230 + @1@option@1@preserve@2@option@2@: preserve original object streams
2231 2231 (default)
2232 2232 </para>
2233 2233 </listitem>
2234 2234 <listitem>
2235 2235 <para>
2236   - <option>disable</option>: don't write any object streams
  2236 + @1@option@1@disable@2@option@2@: don't write any object streams
2237 2237 </para>
2238 2238 </listitem>
2239 2239 <listitem>
2240 2240 <para>
2241   - <option>generate</option>: use object streams wherever
  2241 + @1@option@1@generate@2@option@2@: use object streams wherever
2242 2242 possible
2243 2243 </para>
2244 2244 </listitem>
... ... @@ -2247,7 +2247,7 @@ outfile.pdf&lt;/option&gt;
2247 2247 </listitem>
2248 2248 </varlistentry>
2249 2249 <varlistentry>
2250   - <term><option>--preserve-unreferenced</option></term>
  2250 + <term>@1@option@1@--preserve-unreferenced@2@option@2@</term>
2251 2251 <listitem>
2252 2252 <para>
2253 2253 Tells qpdf to preserve objects that are not referenced when
... ... @@ -2266,16 +2266,16 @@ outfile.pdf&lt;/option&gt;
2266 2266 file, and the original file may have gaps in its numbering.
2267 2267 </para>
2268 2268 <para>
2269   - See also <option>--preserve-unreferenced-resources</option>,
  2269 + See also @1@option@1@--preserve-unreferenced-resources@2@option@2@,
2270 2270 which does something completely different.
2271 2271 </para>
2272 2272 </listitem>
2273 2273 </varlistentry>
2274 2274 <varlistentry>
2275   - <term><option>--remove-unreferenced-resources=<replaceable>option</replaceable></option></term>
  2275 + <term>@1@option@1@--remove-unreferenced-resources=@1@replaceable@1@option@2@replaceable@2@@2@option@2@</term>
2276 2276 <listitem>
2277 2277 <para>
2278   - The <replaceable>option</replaceable> may be
  2278 + The @1@replaceable@1@option@2@replaceable@2@ may be
2279 2279 <literal>auto</literal>, <literal>yes</literal>, or
2280 2280 <literal>no</literal>. The default is <literal>auto</literal>.
2281 2281 </para>
... ... @@ -2311,20 +2311,20 @@ outfile.pdf&lt;/option&gt;
2311 2311 </listitem>
2312 2312 </varlistentry>
2313 2313 <varlistentry>
2314   - <term><option>--preserve-unreferenced-resources</option></term>
  2314 + <term>@1@option@1@--preserve-unreferenced-resources@2@option@2@</term>
2315 2315 <listitem>
2316 2316 <para>
2317 2317 This is a synonym for
2318   - <option>--remove-unreferenced-resources=no</option>.
  2318 + @1@option@1@--remove-unreferenced-resources=no@2@option@2@.
2319 2319 </para>
2320 2320 <para>
2321   - See also <option>--preserve-unreferenced</option>, which does
  2321 + See also @1@option@1@--preserve-unreferenced@2@option@2@, which does
2322 2322 something completely different.
2323 2323 </para>
2324 2324 </listitem>
2325 2325 </varlistentry>
2326 2326 <varlistentry>
2327   - <term><option>--newline-before-endstream</option></term>
  2327 + <term>@1@option@1@--newline-before-endstream@2@option@2@</term>
2328 2328 <listitem>
2329 2329 <para>
2330 2330 Tells qpdf to insert a newline before the
... ... @@ -2339,7 +2339,7 @@ outfile.pdf&lt;/option&gt;
2339 2339 </listitem>
2340 2340 </varlistentry>
2341 2341 <varlistentry>
2342   - <term><option>--linearize-pass1=<replaceable>file</replaceable></option></term>
  2342 + <term>@1@option@1@--linearize-pass1=@1@replaceable@1@file@2@replaceable@2@@2@option@2@</term>
2343 2343 <listitem>
2344 2344 <para>
2345 2345 Write the first pass of linearization to the named file. The
... ... @@ -2354,7 +2354,7 @@ outfile.pdf&lt;/option&gt;
2354 2354 </listitem>
2355 2355 </varlistentry>
2356 2356 <varlistentry>
2357   - <term><option>--coalesce-contents</option></term>
  2357 + <term>@1@option@1@--coalesce-contents@2@option@2@</term>
2358 2358 <listitem>
2359 2359 <para>
2360 2360 When a page's contents are split across multiple streams, this
... ... @@ -2368,7 +2368,7 @@ outfile.pdf&lt;/option&gt;
2368 2368 </listitem>
2369 2369 </varlistentry>
2370 2370 <varlistentry>
2371   - <term><option>--flatten-annotations=<replaceable>option</replaceable></option></term>
  2371 + <term>@1@option@1@--flatten-annotations=@1@replaceable@1@option@2@replaceable@2@@2@option@2@</term>
2372 2372 <listitem>
2373 2373 <para>
2374 2374 This option collapses annotations into the pages' contents
... ... @@ -2380,24 +2380,24 @@ outfile.pdf&lt;/option&gt;
2380 2380 functionality backing this option was added for the benefit of
2381 2381 programs that want to create <emphasis>n-up</emphasis> page
2382 2382 layouts and other similar things that don't work well with
2383   - annotations. The <replaceable>option</replaceable> parameter
  2383 + annotations. The @1@replaceable@1@option@2@replaceable@2@ parameter
2384 2384 may be any of the following:
2385 2385 <itemizedlist>
2386 2386 <listitem>
2387 2387 <para>
2388   - <option>all</option>: include all annotations that are not
  2388 + @1@option@1@all@2@option@2@: include all annotations that are not
2389 2389 marked invisible or hidden
2390 2390 </para>
2391 2391 </listitem>
2392 2392 <listitem>
2393 2393 <para>
2394   - <option>print</option>: only include annotations that
  2394 + @1@option@1@print@2@option@2@: only include annotations that
2395 2395 indicate that they should appear when the page is printed
2396 2396 </para>
2397 2397 </listitem>
2398 2398 <listitem>
2399 2399 <para>
2400   - <option>screen</option>: omit annotations that indicate
  2400 + @1@option@1@screen@2@option@2@: omit annotations that indicate
2401 2401 they should not appear on the screen
2402 2402 </para>
2403 2403 </listitem>
... ... @@ -2413,13 +2413,13 @@ outfile.pdf&lt;/option&gt;
2413 2413 the form field to be lost. This gives you a chance to go back
2414 2414 and resave the form with a program that knows how to generate
2415 2415 appearances. QPDF itself can generate appearances with some
2416   - limitations. See the <option>--generate-appearances</option>
  2416 + limitations. See the @1@option@1@--generate-appearances@2@option@2@
2417 2417 option below.
2418 2418 </para>
2419 2419 </listitem>
2420 2420 </varlistentry>
2421 2421 <varlistentry>
2422   - <term><option>--generate-appearances</option></term>
  2422 + <term>@1@option@1@--generate-appearances@2@option@2@</term>
2423 2423 <listitem>
2424 2424 <para>
2425 2425 If a file contains interactive form fields and indicates that
... ... @@ -2427,7 +2427,7 @@ outfile.pdf&lt;/option&gt;
2427 2427 this flag will regenerate appearances, subject to a few
2428 2428 limitations. Note that there is not usually a reason to do
2429 2429 this, but it can be necessary before using the
2430   - <option>--flatten-annotations</option> option. Most of these
  2430 + @1@option@1@--flatten-annotations@2@option@2@ option. Most of these
2431 2431 are not a problem with well-behaved PDF files. The limitations
2432 2432 are as follows:
2433 2433 <itemizedlist>
... ... @@ -2485,7 +2485,7 @@ outfile.pdf&lt;/option&gt;
2485 2485 </listitem>
2486 2486 </varlistentry>
2487 2487 <varlistentry>
2488   - <term><option>--optimize-images</option></term>
  2488 + <term>@1@option@1@--optimize-images@2@option@2@</term>
2489 2489 <listitem>
2490 2490 <para>
2491 2491 This flag causes qpdf to recompress all images that are not
... ... @@ -2493,19 +2493,19 @@ outfile.pdf&lt;/option&gt;
2493 2493 doing so decreases the size in bytes of the image data and the
2494 2494 image does not fall below minimum specified dimensions. Useful
2495 2495 information is provided when used in combination with
2496   - <option>--verbose</option>. See also the
2497   - <option>--oi-min-width</option>,
2498   - <option>--oi-min-height</option>, and
2499   - <option>--oi-min-area</option> options. By default, starting
  2496 + @1@option@1@--verbose@2@option@2@. See also the
  2497 + @1@option@1@--oi-min-width@2@option@2@,
  2498 + @1@option@1@--oi-min-height@2@option@2@, and
  2499 + @1@option@1@--oi-min-area@2@option@2@ options. By default, starting
2500 2500 in qpdf 8.4, inline images are converted to regular images
2501 2501 and optimized as well. Use
2502   - <option>--keep-inline-images</option> to prevent inline images
  2502 + @1@option@1@--keep-inline-images@2@option@2@ to prevent inline images
2503 2503 from being included.
2504 2504 </para>
2505 2505 </listitem>
2506 2506 </varlistentry>
2507 2507 <varlistentry>
2508   - <term><option>--oi-min-width=<replaceable>width</replaceable></option></term>
  2508 + <term>@1@option@1@--oi-min-width=@1@replaceable@1@width@2@replaceable@2@@2@option@2@</term>
2509 2509 <listitem>
2510 2510 <para>
2511 2511 Avoid optimizing images whose width is below the specified
... ... @@ -2515,7 +2515,7 @@ outfile.pdf&lt;/option&gt;
2515 2515 </listitem>
2516 2516 </varlistentry>
2517 2517 <varlistentry>
2518   - <term><option>--oi-min-height=<replaceable>height</replaceable></option></term>
  2518 + <term>@1@option@1@--oi-min-height=@1@replaceable@1@height@2@replaceable@2@@2@option@2@</term>
2519 2519 <listitem>
2520 2520 <para>
2521 2521 Avoid optimizing images whose height is below the specified
... ... @@ -2525,7 +2525,7 @@ outfile.pdf&lt;/option&gt;
2525 2525 </listitem>
2526 2526 </varlistentry>
2527 2527 <varlistentry>
2528   - <term><option>--oi-min-area=<replaceable>area-in-pixels</replaceable></option></term>
  2528 + <term>@1@option@1@--oi-min-area=@1@replaceable@1@area-in-pixels@2@replaceable@2@@2@option@2@</term>
2529 2529 <listitem>
2530 2530 <para>
2531 2531 Avoid optimizing images whose pixel count
... ... @@ -2535,21 +2535,21 @@ outfile.pdf&lt;/option&gt;
2535 2535 </listitem>
2536 2536 </varlistentry>
2537 2537 <varlistentry>
2538   - <term><option>--externalize-inline-images</option></term>
  2538 + <term>@1@option@1@--externalize-inline-images@2@option@2@</term>
2539 2539 <listitem>
2540 2540 <para>
2541 2541 Convert inline images to regular images. By default, images
2542 2542 whose data is at least 1,024 bytes are converted when this
2543   - option is selected. Use <option>--ii-min-bytes</option> to
  2543 + option is selected. Use @1@option@1@--ii-min-bytes@2@option@2@ to
2544 2544 change the size threshold. This option is implicitly selected
2545   - when <option>--optimize-images</option> is selected. Use
2546   - <option>--keep-inline-images</option> to exclude inline images
  2545 + when @1@option@1@--optimize-images@2@option@2@ is selected. Use
  2546 + @1@option@1@--keep-inline-images@2@option@2@ to exclude inline images
2547 2547 from image optimization.
2548 2548 </para>
2549 2549 </listitem>
2550 2550 </varlistentry>
2551 2551 <varlistentry>
2552   - <term><option>--ii-min-bytes=<replaceable>bytes</replaceable></option></term>
  2552 + <term>@1@option@1@--ii-min-bytes=@1@replaceable@1@bytes@2@replaceable@2@@2@option@2@</term>
2553 2553 <listitem>
2554 2554 <para>
2555 2555 Avoid converting inline images whose size is below the
... ... @@ -2559,17 +2559,17 @@ outfile.pdf&lt;/option&gt;
2559 2559 </listitem>
2560 2560 </varlistentry>
2561 2561 <varlistentry>
2562   - <term><option>--keep-inline-images</option></term>
  2562 + <term>@1@option@1@--keep-inline-images@2@option@2@</term>
2563 2563 <listitem>
2564 2564 <para>
2565 2565 Prevent inline images from being included in image
2566 2566 optimization. This option has no affect when
2567   - <option>--optimize-images</option> is not specified.
  2567 + @1@option@1@--optimize-images@2@option@2@ is not specified.
2568 2568 </para>
2569 2569 </listitem>
2570 2570 </varlistentry>
2571 2571 <varlistentry>
2572   - <term><option>--remove-page-labels</option></term>
  2572 + <term>@1@option@1@--remove-page-labels@2@option@2@</term>
2573 2573 <listitem>
2574 2574 <para>
2575 2575 Remove page labels from the output file.
... ... @@ -2577,21 +2577,21 @@ outfile.pdf&lt;/option&gt;
2577 2577 </listitem>
2578 2578 </varlistentry>
2579 2579 <varlistentry>
2580   - <term><option>--qdf</option></term>
  2580 + <term>@1@option@1@--qdf@2@option@2@</term>
2581 2581 <listitem>
2582 2582 <para>
2583 2583 Turns on QDF mode. For additional information on QDF, please
2584 2584 see <xref linkend="ref.qdf"/>. Note that
2585   - <option>--linearize</option> disables QDF mode.
  2585 + @1@option@1@--linearize@2@option@2@ disables QDF mode.
2586 2586 </para>
2587 2587 </listitem>
2588 2588 </varlistentry>
2589 2589 <varlistentry>
2590   - <term><option>--min-version=<replaceable>version</replaceable></option></term>
  2590 + <term>@1@option@1@--min-version=@1@replaceable@1@version@2@replaceable@2@@2@option@2@</term>
2591 2591 <listitem>
2592 2592 <para>
2593 2593 Forces the PDF version of the output file to be at least
2594   - <replaceable>version</replaceable>. In other words, if the
  2594 + @1@replaceable@1@version@2@replaceable@2@. In other words, if the
2595 2595 input file has a lower version than the specified version, the
2596 2596 specified version will be used. If the input file has a
2597 2597 higher version, the input file's original version will be
... ... @@ -2601,10 +2601,10 @@ outfile.pdf&lt;/option&gt;
2601 2601 </para>
2602 2602 <para>
2603 2603 The version number may be expressed in the form
2604   - <replaceable>major.minor.extension-level</replaceable>, in
  2604 + @1@replaceable@1@major.minor.extension-level@2@replaceable@2@, in
2605 2605 which case the version is interpreted as
2606   - <replaceable>major.minor</replaceable> at extension level
2607   - <replaceable>extension-level</replaceable>. For example,
  2606 + @1@replaceable@1@major.minor@2@replaceable@2@ at extension level
  2607 + @1@replaceable@1@extension-level@2@replaceable@2@. For example,
2608 2608 version <literal>1.7.8</literal> represents version 1.7 at
2609 2609 extension level 8. Note that minimal syntax checking is done
2610 2610 on the command line.
... ... @@ -2612,14 +2612,14 @@ outfile.pdf&lt;/option&gt;
2612 2612 </listitem>
2613 2613 </varlistentry>
2614 2614 <varlistentry>
2615   - <term><option>--force-version=<replaceable>version</replaceable></option></term>
  2615 + <term>@1@option@1@--force-version=@1@replaceable@1@version@2@replaceable@2@@2@option@2@</term>
2616 2616 <listitem>
2617 2617 <para>
2618 2618 This option forces the PDF version to be the exact version
2619 2619 specified <emphasis>even when the file may have content that
2620 2620 is not supported in that version</emphasis>. The version
2621 2621 number is interpreted in the same way as with
2622   - <option>--min-version</option> so that extension levels can be
  2622 + @1@option@1@--min-version@2@option@2@ so that extension levels can be
2623 2623 set. In some cases, forcing the output file's PDF version to
2624 2624 be lower than that of the input file will cause qpdf to
2625 2625 disable certain features of the document. Specifically,
... ... @@ -2653,10 +2653,10 @@ outfile.pdf&lt;/option&gt;
2653 2653 compression scheme, qpdf will uncompress and recompress streams.
2654 2654 Assuming proper filter implements, this is safe and generally
2655 2655 results in smaller files. This behavior may also be explicitly
2656   - requested with <option>--stream-data=compress</option>.
  2656 + requested with @1@option@1@--stream-data=compress@2@option@2@.
2657 2657 </para>
2658 2658 <para>
2659   - When <option>--normalize-content=y</option> is specified, qpdf
  2659 + When @1@option@1@--normalize-content=y@2@option@2@ is specified, qpdf
2660 2660 will attempt to normalize whitespace and newlines in page content
2661 2661 streams. This is generally safe but could, in some cases, cause
2662 2662 damage to the content streams. This option is intended for people
... ... @@ -2673,10 +2673,10 @@ outfile.pdf&lt;/option&gt;
2673 2673 that do this are invalid since the PDF specification states that
2674 2674 content streams are not to be split in the middle of a token. If
2675 2675 you want to inspect the original content streams in an
2676   - uncompressed format, you can always run with <option>--qdf
2677   - --normalize-content=n</option> for a QDF file without content
  2676 + uncompressed format, you can always run with @1@option@1@--qdf
  2677 + --normalize-content=n@2@option@2@ for a QDF file without content
2678 2678 normalization, or alternatively
2679   - <option>--stream-data=uncompress</option> for a regular non-QDF
  2679 + @1@option@1@--stream-data=uncompress@2@option@2@ for a regular non-QDF
2680 2680 mode file with uncompressed streams. These will both uncompress
2681 2681 all the streams but will not attempt to normalize content. Please
2682 2682 note that if you are using content normalization or QDF mode for
... ... @@ -2690,25 +2690,25 @@ outfile.pdf&lt;/option&gt;
2690 2690 object streams. qpdf can be used to transform files with object
2691 2691 streams to files without object streams or vice versa. As
2692 2692 mentioned above, there are three object stream modes:
2693   - <option>preserve</option>, <option>disable</option>, and
2694   - <option>generate</option>.
  2693 + @1@option@1@preserve@2@option@2@, @1@option@1@disable@2@option@2@, and
  2694 + @1@option@1@generate@2@option@2@.
2695 2695 </para>
2696 2696 <para>
2697   - In <option>preserve</option> mode, the relationship to objects and
  2697 + In @1@option@1@preserve@2@option@2@ mode, the relationship to objects and
2698 2698 the streams that contain them is preserved from the original file.
2699   - In <option>disable</option> mode, all objects are written as
  2699 + In @1@option@1@disable@2@option@2@ mode, all objects are written as
2700 2700 regular, uncompressed objects. The resulting file should be
2701 2701 readable by older PDF viewers. (Of course, the content of the
2702 2702 files may include features not supported by older viewers, but at
2703 2703 least the structure will be supported.) In
2704   - <option>generate</option> mode, qpdf will create its own object
  2704 + @1@option@1@generate@2@option@2@ mode, qpdf will create its own object
2705 2705 streams. This will usually result in more compact PDF files,
2706 2706 though they may not be readable by older viewers. In this mode,
2707 2707 qpdf will also make sure the PDF version number in the header is
2708 2708 at least 1.5.
2709 2709 </para>
2710 2710 <para>
2711   - The <option>--qdf</option> flag turns on QDF mode, which changes
  2711 + The @1@option@1@--qdf@2@option@2@ flag turns on QDF mode, which changes
2712 2712 some of the defaults described above. Specifically, in QDF mode,
2713 2713 by default, stream data is uncompressed, content streams are
2714 2714 normalized, and encryption is removed. These defaults can still
... ... @@ -2717,7 +2717,7 @@ outfile.pdf&lt;/option&gt;
2717 2717 indirect objects, objects are laid out in a less efficient but
2718 2718 more readable fashion, and the documents are interspersed with
2719 2719 comments that make it easier for the user to find things and also
2720   - make it possible for <command>fix-qdf</command> to work properly.
  2720 + make it possible for @1@command@1@fix-qdf@2@command@2@ to work properly.
2721 2721 QDF mode is intended for people, mostly developers, who wish to
2722 2722 inspect or modify PDF files in a text editor. For details, please
2723 2723 see <xref linkend="ref.qdf"/>.
... ... @@ -2732,7 +2732,7 @@ outfile.pdf&lt;/option&gt;
2732 2732 file should be given. The following options are available:
2733 2733 <variablelist>
2734 2734 <varlistentry>
2735   - <term><option>--deterministic-id</option></term>
  2735 + <term>@1@option@1@--deterministic-id@2@option@2@</term>
2736 2736 <listitem>
2737 2737 <para>
2738 2738 Causes generation of a deterministic value for /ID. This
... ... @@ -2748,19 +2748,19 @@ outfile.pdf&lt;/option&gt;
2748 2748 </listitem>
2749 2749 </varlistentry>
2750 2750 <varlistentry>
2751   - <term><option>--static-id</option></term>
  2751 + <term>@1@option@1@--static-id@2@option@2@</term>
2752 2752 <listitem>
2753 2753 <para>
2754 2754 Causes generation of a fixed value for /ID. This is intended
2755 2755 for testing only. Never use it for production files. If you
2756 2756 are trying to get the same /ID each time for a given file and
2757 2757 you are not generating encrypted files, consider using the
2758   - <option>--deterministic-id</option> option.
  2758 + @1@option@1@--deterministic-id@2@option@2@ option.
2759 2759 </para>
2760 2760 </listitem>
2761 2761 </varlistentry>
2762 2762 <varlistentry>
2763   - <term><option>--static-aes-iv</option></term>
  2763 + <term>@1@option@1@--static-aes-iv@2@option@2@</term>
2764 2764 <listitem>
2765 2765 <para>
2766 2766 Causes use of a static initialization vector for AES-CBC.
... ... @@ -2772,7 +2772,7 @@ outfile.pdf&lt;/option&gt;
2772 2772 </listitem>
2773 2773 </varlistentry>
2774 2774 <varlistentry>
2775   - <term><option>--no-original-object-ids</option></term>
  2775 + <term>@1@option@1@--no-original-object-ids@2@option@2@</term>
2776 2776 <listitem>
2777 2777 <para>
2778 2778 Suppresses inclusion of original object ID comments in QDF
... ... @@ -2783,7 +2783,7 @@ outfile.pdf&lt;/option&gt;
2783 2783 </listitem>
2784 2784 </varlistentry>
2785 2785 <varlistentry>
2786   - <term><option>--show-encryption</option></term>
  2786 + <term>@1@option@1@--show-encryption@2@option@2@</term>
2787 2787 <listitem>
2788 2788 <para>
2789 2789 Shows document encryption parameters. Also shows the
... ... @@ -2792,16 +2792,16 @@ outfile.pdf&lt;/option&gt;
2792 2792 </listitem>
2793 2793 </varlistentry>
2794 2794 <varlistentry>
2795   - <term><option>--show-encryption-key</option></term>
  2795 + <term>@1@option@1@--show-encryption-key@2@option@2@</term>
2796 2796 <listitem>
2797 2797 <para>
2798 2798 When encryption information is being displayed, as when
2799   - <option>--check</option> or <option>--show-encryption</option>
  2799 + @1@option@1@--check@2@option@2@ or @1@option@1@--show-encryption@2@option@2@
2800 2800 is given, display the computed or retrieved encryption key as
2801 2801 a hexadecimal string. This value is not ordinarily useful to
2802 2802 users, but it can be used as the argument to
2803   - <option>--password</option> if the
2804   - <option>--password-is-hex-key</option> is specified. Note
  2803 + @1@option@1@--password@2@option@2@ if the
  2804 + @1@option@1@--password-is-hex-key@2@option@2@ is specified. Note
2805 2805 that, when PDF files are encrypted, passwords and other
2806 2806 metadata are used only to compute an encryption key, and the
2807 2807 encryption key is what is actually used for encryption. This
... ... @@ -2810,7 +2810,7 @@ outfile.pdf&lt;/option&gt;
2810 2810 </listitem>
2811 2811 </varlistentry>
2812 2812 <varlistentry>
2813   - <term><option>--check-linearization</option></term>
  2813 + <term>@1@option@1@--check-linearization@2@option@2@</term>
2814 2814 <listitem>
2815 2815 <para>
2816 2816 Checks file integrity and linearization status.
... ... @@ -2818,7 +2818,7 @@ outfile.pdf&lt;/option&gt;
2818 2818 </listitem>
2819 2819 </varlistentry>
2820 2820 <varlistentry>
2821   - <term><option>--show-linearization</option></term>
  2821 + <term>@1@option@1@--show-linearization@2@option@2@</term>
2822 2822 <listitem>
2823 2823 <para>
2824 2824 Checks and displays all data in the linearization hint tables.
... ... @@ -2826,7 +2826,7 @@ outfile.pdf&lt;/option&gt;
2826 2826 </listitem>
2827 2827 </varlistentry>
2828 2828 <varlistentry>
2829   - <term><option>--show-xref</option></term>
  2829 + <term>@1@option@1@--show-xref@2@option@2@</term>
2830 2830 <listitem>
2831 2831 <para>
2832 2832 Shows the contents of the cross-reference table in a
... ... @@ -2836,7 +2836,7 @@ outfile.pdf&lt;/option&gt;
2836 2836 </listitem>
2837 2837 </varlistentry>
2838 2838 <varlistentry>
2839   - <term><option>--show-object=trailer|obj[,gen]</option></term>
  2839 + <term>@1@option@1@--show-object=trailer|obj[,gen]@2@option@2@</term>
2840 2840 <listitem>
2841 2841 <para>
2842 2842 Show the contents of the given object. This is especially
... ... @@ -2846,20 +2846,20 @@ outfile.pdf&lt;/option&gt;
2846 2846 </listitem>
2847 2847 </varlistentry>
2848 2848 <varlistentry>
2849   - <term><option>--raw-stream-data</option></term>
  2849 + <term>@1@option@1@--raw-stream-data@2@option@2@</term>
2850 2850 <listitem>
2851 2851 <para>
2852   - When used along with the <option>--show-object</option>
  2852 + When used along with the @1@option@1@--show-object@2@option@2@
2853 2853 option, if the object is a stream, shows the raw stream data
2854 2854 instead of object's contents.
2855 2855 </para>
2856 2856 </listitem>
2857 2857 </varlistentry>
2858 2858 <varlistentry>
2859   - <term><option>--filtered-stream-data</option></term>
  2859 + <term>@1@option@1@--filtered-stream-data@2@option@2@</term>
2860 2860 <listitem>
2861 2861 <para>
2862   - When used along with the <option>--show-object</option>
  2862 + When used along with the @1@option@1@--show-object@2@option@2@
2863 2863 option, if the object is a stream, shows the filtered stream
2864 2864 data instead of object's contents. If the stream is filtered
2865 2865 using filters that qpdf does not support, an error will be
... ... @@ -2868,7 +2868,7 @@ outfile.pdf&lt;/option&gt;
2868 2868 </listitem>
2869 2869 </varlistentry>
2870 2870 <varlistentry>
2871   - <term><option>--show-npages</option></term>
  2871 + <term>@1@option@1@--show-npages@2@option@2@</term>
2872 2872 <listitem>
2873 2873 <para>
2874 2874 Prints the number of pages in the input file on a line by
... ... @@ -2879,7 +2879,7 @@ outfile.pdf&lt;/option&gt;
2879 2879 </listitem>
2880 2880 </varlistentry>
2881 2881 <varlistentry>
2882   - <term><option>--show-pages</option></term>
  2882 + <term>@1@option@1@--show-pages@2@option@2@</term>
2883 2883 <listitem>
2884 2884 <para>
2885 2885 Shows the object and generation number for each page
... ... @@ -2890,10 +2890,10 @@ outfile.pdf&lt;/option&gt;
2890 2890 </listitem>
2891 2891 </varlistentry>
2892 2892 <varlistentry>
2893   - <term><option>--with-images</option></term>
  2893 + <term>@1@option@1@--with-images@2@option@2@</term>
2894 2894 <listitem>
2895 2895 <para>
2896   - When used along with <option>--show-pages</option>, also shows
  2896 + When used along with @1@option@1@--show-pages@2@option@2@, also shows
2897 2897 the object and generation numbers for the image objects on
2898 2898 each page. (At present, information about images in shared
2899 2899 resource dictionaries are not output by this command. This is
... ... @@ -2902,7 +2902,7 @@ outfile.pdf&lt;/option&gt;
2902 2902 </listitem>
2903 2903 </varlistentry>
2904 2904 <varlistentry>
2905   - <term><option>--json</option></term>
  2905 + <term>@1@option@1@--json@2@option@2@</term>
2906 2906 <listitem>
2907 2907 <para>
2908 2908 Generate a JSON representation of the file. This is described
... ... @@ -2911,7 +2911,7 @@ outfile.pdf&lt;/option&gt;
2911 2911 </listitem>
2912 2912 </varlistentry>
2913 2913 <varlistentry>
2914   - <term><option>--json-help</option></term>
  2914 + <term>@1@option@1@--json-help@2@option@2@</term>
2915 2915 <listitem>
2916 2916 <para>
2917 2917 Describe the format of the JSON output.
... ... @@ -2919,7 +2919,7 @@ outfile.pdf&lt;/option&gt;
2919 2919 </listitem>
2920 2920 </varlistentry>
2921 2921 <varlistentry>
2922   - <term><option>--json-key=key</option></term>
  2922 + <term>@1@option@1@--json-key=key@2@option@2@</term>
2923 2923 <listitem>
2924 2924 <para>
2925 2925 This option is repeatable. If specified, only top-level keys
... ... @@ -2929,7 +2929,7 @@ outfile.pdf&lt;/option&gt;
2929 2929 </listitem>
2930 2930 </varlistentry>
2931 2931 <varlistentry>
2932   - <term><option>--json-object=trailer|obj[,gen]</option></term>
  2932 + <term>@1@option@1@--json-object=trailer|obj[,gen]@2@option@2@</term>
2933 2933 <listitem>
2934 2934 <para>
2935 2935 This option is repeatable. If specified, only specified
... ... @@ -2940,30 +2940,30 @@ outfile.pdf&lt;/option&gt;
2940 2940 </listitem>
2941 2941 </varlistentry>
2942 2942 <varlistentry>
2943   - <term><option>--check</option></term>
  2943 + <term>@1@option@1@--check@2@option@2@</term>
2944 2944 <listitem>
2945 2945 <para>
2946 2946 Checks file structure and well as encryption, linearization,
2947 2947 and encoding of stream data. A file for which
2948   - <option>--check</option> reports no errors may still have
  2948 + @1@option@1@--check@2@option@2@ reports no errors may still have
2949 2949 errors in stream data content but should otherwise be
2950   - structurally sound. If <option>--check</option> any errors,
  2950 + structurally sound. If @1@option@1@--check@2@option@2@ any errors,
2951 2951 qpdf will exit with a status of 2. There are some recoverable
2952   - conditions that <option>--check</option> detects. These are
  2952 + conditions that @1@option@1@--check@2@option@2@ detects. These are
2953 2953 issued as warnings instead of errors. If qpdf finds no errors
2954 2954 but finds warnings, it will exit with a status of 3 (as of
2955   - version&nbsp;2.0.4). When <option>--check</option> is combined
  2955 + version&nbsp;2.0.4). When @1@option@1@--check@2@option@2@ is combined
2956 2956 with other options, checks are always performed before any
2957 2957 other options are processed. For erroneous files,
2958   - <option>--check</option> will cause qpdf to attempt to
  2958 + @1@option@1@--check@2@option@2@ will cause qpdf to attempt to
2959 2959 recover, after which other options are effectively operating
2960   - on the recovered file. Combining <option>--check</option> with
  2960 + on the recovered file. Combining @1@option@1@--check@2@option@2@ with
2961 2961 other options in this way can be useful for manually
2962 2962 recovering severely damaged files. Note that
2963   - <option>--check</option> produces no output to standard output
  2963 + @1@option@1@--check@2@option@2@ produces no output to standard output
2964 2964 when everything is valid, so if you are using this to
2965 2965 programmatically validate files in bulk, it is safe to run
2966   - without output redirected to <filename>/dev/null</filename>
  2966 + without output redirected to @1@filename@1@/dev/null@2@filename@2@
2967 2967 and just check for a 0 exit code.
2968 2968 </para>
2969 2969 </listitem>
... ... @@ -2971,17 +2971,17 @@ outfile.pdf&lt;/option&gt;
2971 2971 </variablelist>
2972 2972 </para>
2973 2973 <para>
2974   - The <option>--raw-stream-data</option> and
2975   - <option>--filtered-stream-data</option> options are ignored unless
2976   - <option>--show-object</option> is given. Either of these options
  2974 + The @1@option@1@--raw-stream-data@2@option@2@ and
  2975 + @1@option@1@--filtered-stream-data@2@option@2@ options are ignored unless
  2976 + @1@option@1@--show-object@2@option@2@ is given. Either of these options
2977 2977 will cause the stream data to be written to standard output. In
2978 2978 order to avoid commingling of stream data with other output, it is
2979 2979 recommend that these objects not be combined with other
2980 2980 test/inspection options.
2981 2981 </para>
2982 2982 <para>
2983   - If <option>--filtered-stream-data</option> is given and
2984   - <option>--normalize-content=y</option> is also given, qpdf will
  2983 + If @1@option@1@--filtered-stream-data@2@option@2@ is given and
  2984 + @1@option@1@--normalize-content=y@2@option@2@ is also given, qpdf will
2985 2985 attempt to normalize the stream data as if it is a page content
2986 2986 stream. This attempt will be made even if it is not a page
2987 2987 content stream, in which case it will produce unusable results.
... ... @@ -3029,7 +3029,7 @@ outfile.pdf&lt;/option&gt;
3029 3029 the supplied password is not a valid UTF-8 string, qpdf will fall
3030 3030 back to the behavior of interpreting the password as a string of
3031 3031 bytes. If you have old scripts that encrypt files by passing the
3032   - output of <command>iconv</command> to qpdf, you no longer need to
  3032 + output of @1@command@1@iconv@2@command@2@ to qpdf, you no longer need to
3033 3033 do that, but if you do, qpdf should still work. The only exception
3034 3034 would be for the extremely unlikely case of a password that is
3035 3035 encoded with a single-byte encoding but also happens to be valid
... ... @@ -3037,24 +3037,24 @@ outfile.pdf&lt;/option&gt;
3037 3037 characters that alternate between accented letters and symbols. In
3038 3038 the extremely unlikely event that you are intentionally using such
3039 3039 passwords and qpdf is thwarting you by interpreting them as UTF-8,
3040   - you can use <option>--password-mode=bytes</option> to suppress
  3040 + you can use @1@option@1@--password-mode=bytes@2@option@2@ to suppress
3041 3041 qpdf's automatic behavior.
3042 3042 </para>
3043 3043 <para>
3044   - The <option>--password-mode</option> option, as described earlier
  3044 + The @1@option@1@--password-mode@2@option@2@ option, as described earlier
3045 3045 in this chapter, can be used to change qpdf's interpretation of
3046 3046 supplied passwords. There are very few reasons to use this option.
3047 3047 One would be the unlikely case described in the previous paragraph
3048 3048 in which the supplied password happens to be valid UTF-8 but isn't
3049 3049 supposed to be UTF-8. Your best bet would be just to provide the
3050 3050 password as a valid UTF-8 string, but you could also use
3051   - <option>--password-mode=bytes</option>. Another reason to use
3052   - <option>--password-mode=bytes</option> would be to intentionally
  3051 + @1@option@1@--password-mode=bytes@2@option@2@. Another reason to use
  3052 + @1@option@1@--password-mode=bytes@2@option@2@ would be to intentionally
3053 3053 generate PDF files encrypted with passwords that are not properly
3054 3054 encoded. The qpdf test suite does this to generate invalid files
3055 3055 for the purpose of testing its password recovery capability. If
3056 3056 you were trying to create intentionally incorrect files for a
3057   - similar purposes, the <option>bytes</option> password mode can
  3057 + similar purposes, the @1@option@1@bytes@2@option@2@ password mode can
3058 3058 enable you to do this.
3059 3059 </para>
3060 3060 <para>
... ... @@ -3064,7 +3064,7 @@ outfile.pdf&lt;/option&gt;
3064 3064 handful of different coding systems and then transcode them to the
3065 3065 required format. This helps to compensate for the supplied
3066 3066 password being given in the wrong coding system, such as would
3067   - happen if you used the <command>iconv</command> workaround that
  3067 + happen if you used the @1@command@1@iconv@2@command@2@ workaround that
3068 3068 was previously needed. It also generates passwords by doing the
3069 3069 reverse operation: translating from correct in incorrect encoding
3070 3070 of the password. This would enable qpdf to decrypt files using
... ... @@ -3075,7 +3075,7 @@ outfile.pdf&lt;/option&gt;
3075 3075 encrypted files with the password supplied correctly but in the
3076 3076 wrong coding system. There are no real downsides to this behavior,
3077 3077 but if you don't want qpdf to do this, you can use the
3078   - <option>--suppress-password-recovery</option> option. One reason
  3078 + @1@option@1@--suppress-password-recovery@2@option@2@ option. One reason
3079 3079 to do that is to ensure that you know the exact password that was
3080 3080 used to encrypt the file.
3081 3081 </para>
... ... @@ -3094,7 +3094,7 @@ outfile.pdf&lt;/option&gt;
3094 3094 bytes.
3095 3095 </para>
3096 3096 <para>
3097   - Please note that the <option>--password-is-hex-key</option> option
  3097 + Please note that the @1@option@1@--password-is-hex-key@2@option@2@ option
3098 3098 is unrelated to all this. This flag bypasses the normal process of
3099 3099 going from password to encryption string entirely, allowing the
3100 3100 raw encryption key to be specified directly. This is useful for
... ... @@ -3106,8 +3106,8 @@ outfile.pdf&lt;/option&gt;
3106 3106 <chapter id="ref.qdf">
3107 3107 <title>QDF Mode</title>
3108 3108 <para>
3109   - In QDF mode, qpdf creates PDF files in what we call <firstterm>QDF
3110   - form</firstterm>. A PDF file in QDF form, sometimes called a QDF
  3109 + In QDF mode, qpdf creates PDF files in what we call @1@firstterm@1@QDF
  3110 + form@2@firstterm@2@. A PDF file in QDF form, sometimes called a QDF
3111 3111 file, is a completely valid PDF file that has
3112 3112 <literal>%QDF-1.0</literal> as its third line (after the pdf header
3113 3113 and binary characters) and has certain other characteristics. The
... ... @@ -3125,9 +3125,9 @@ outfile.pdf&lt;/option&gt;
3125 3125 and PDF files are full of offset and length information that makes
3126 3126 it hard to add or remove data. A QDF file is organized in a manner
3127 3127 such that, if edits are kept within certain constraints, the
3128   - <command>fix-qdf</command> program, distributed with qpdf, is able
  3128 + @1@command@1@fix-qdf@2@command@2@ program, distributed with qpdf, is able
3129 3129 to restore edited files to a correct state. The
3130   - <command>fix-qdf</command> program takes no command-line
  3130 + @1@command@1@fix-qdf@2@command@2@ program takes no command-line
3131 3131 arguments. It reads a possibly edited QDF file from standard input
3132 3132 and writes a repaired file to standard output.
3133 3133 </para>
... ... @@ -3218,11 +3218,11 @@ outfile.pdf&lt;/option&gt;
3218 3218 It is not generally practical to remove objects from QDF files
3219 3219 without messing up object numbering, but if you remove all
3220 3220 references to an object, you can run qpdf on the file (after
3221   - running <command>fix-qdf</command>), and qpdf will omit the
  3221 + running @1@command@1@fix-qdf@2@command@2@), and qpdf will omit the
3222 3222 now-orphaned object.
3223 3223 </para>
3224 3224 <para>
3225   - When <command>fix-qdf</command> is run, it goes through the file
  3225 + When @1@command@1@fix-qdf@2@command@2@ is run, it goes through the file
3226 3226 and recomputes the following parts of the file:
3227 3227 <itemizedlist>
3228 3228 <listitem>
... ... @@ -3262,26 +3262,26 @@ outfile.pdf&lt;/option&gt;
3262 3262 <title>Using QPDF from C++</title>
3263 3263 <para>
3264 3264 The source tree for the qpdf package has an
3265   - <filename>examples</filename> directory that contains a few
3266   - example programs. The <filename>qpdf/qpdf.cc</filename> source
  3265 + @1@filename@1@examples@2@filename@2@ directory that contains a few
  3266 + example programs. The @1@filename@1@qpdf/qpdf.cc@2@filename@2@ source
3267 3267 file also serves as a useful example since it exercises almost all
3268 3268 of the qpdf library's public interface. The best source of
3269 3269 documentation on the library itself is reading comments in
3270   - <filename>include/qpdf/QPDF.hh</filename>,
3271   - <filename>include/qpdf/QPDFWriter.hh</filename>, and
3272   - <filename>include/qpdf/QPDFObjectHandle.hh</filename>.
  3270 + @1@filename@1@include/qpdf/QPDF.hh@2@filename@2@,
  3271 + @1@filename@1@include/qpdf/QPDFWriter.hh@2@filename@2@, and
  3272 + @1@filename@1@include/qpdf/QPDFObjectHandle.hh@2@filename@2@.
3273 3273 </para>
3274 3274 <para>
3275   - All header files are installed in the <filename>include/qpdf</filename> directory. It
  3275 + All header files are installed in the @1@filename@1@include/qpdf@2@filename@2@ directory. It
3276 3276 is recommend that you use <literal>#include
3277 3277 &lt;qpdf/QPDF.hh&gt;</literal> rather than adding
3278   - <filename>include/qpdf</filename> to your include path.
  3278 + @1@filename@1@include/qpdf@2@filename@2@ to your include path.
3279 3279 </para>
3280 3280 <para>
3281 3281 When linking against the qpdf static library, you may also need to
3282 3282 specify <literal>-lz -ljpeg</literal> on your link command. If
3283 3283 your system understands how to read libtool
3284   - <filename>.la</filename> files, this may not be necessary.
  3284 + @1@filename@1@.la@2@filename@2@ files, this may not be necessary.
3285 3285 </para>
3286 3286 <para>
3287 3287 The qpdf library is safe to use in a multithreaded program, but no
... ... @@ -3305,7 +3305,7 @@ outfile.pdf&lt;/option&gt;
3305 3305 <para>
3306 3306 The qpdf library includes a &ldquo;C&rdquo; language interface
3307 3307 that provides a subset of the overall capabilities. The header
3308   - file <filename>qpdf/qpdf-c.h</filename> includes information
  3308 + file @1@filename@1@qpdf/qpdf-c.h@2@filename@2@ includes information
3309 3309 about its use. As long as you use a C++ linker, you can link C
3310 3310 programs with qpdf and use the C API. For languages that can
3311 3311 directly load methods from a shared library, the C API can also
... ... @@ -3333,7 +3333,7 @@ outfile.pdf&lt;/option&gt;
3333 3333 <term>Other Languages</term>
3334 3334 <listitem>
3335 3335 <para>
3336   - Starting with version 8.3.0, the <command>qpdf</command>
  3336 + Starting with version 8.3.0, the @1@command@1@qpdf@2@command@2@
3337 3337 command-line tool can produce a JSON representation of the PDF
3338 3338 file's non-content data. This can facilitate interacting
3339 3339 programmatically with PDF files through qpdf's command line
... ... @@ -3384,13 +3384,13 @@ outfile.pdf&lt;/option&gt;
3384 3384 In version 10.4, qpdf generates warnings for some (but not all)
3385 3385 cases of writing files with weak cryptography when invoked from the
3386 3386 command-line. These warnings can be suppressed using the
3387   - <option>--allow-weak-crypto</option> option.
  3387 + @1@option@1@--allow-weak-crypto@2@option@2@ option.
3388 3388 </para>
3389 3389 <para>
3390 3390 It is planned for qpdf version 11 to be stricter, making it an
3391 3391 error to write files with insecure cryptography from the
3392 3392 command-line tool in most cases without specifying the
3393   - <option>--allow-weak-crypto</option> flag and also to require
  3393 + @1@option@1@--allow-weak-crypto@2@option@2@ flag and also to require
3394 3394 explicit steps when using the C++ library to enable use of insecure
3395 3395 cryptography.
3396 3396 </para>
... ... @@ -3412,7 +3412,7 @@ outfile.pdf&lt;/option&gt;
3412 3412 <sect1 id="ref.json-overview">
3413 3413 <title>Overview</title>
3414 3414 <para>
3415   - Beginning with qpdf version 8.3.0, the <command>qpdf</command>
  3415 + Beginning with qpdf version 8.3.0, the @1@command@1@qpdf@2@command@2@
3416 3416 command-line program can produce a JSON representation of the
3417 3417 non-content data in a PDF file. It includes a dump in JSON format
3418 3418 of all objects in the PDF file excluding the content of streams.
... ... @@ -3466,8 +3466,8 @@ outfile.pdf&lt;/option&gt;
3466 3466 <term>Documentation</term>
3467 3467 <listitem>
3468 3468 <para>
3469   - The <command>qpdf</command> command can be invoked with the
3470   - <option>--json-help</option> option. This will output a JSON
  3469 + The @1@command@1@qpdf@2@command@2@ command can be invoked with the
  3470 + @1@option@1@--json-help@2@option@2@ option. This will output a JSON
3471 3471 structure that has the same structure as the JSON output that
3472 3472 qpdf generates, except that each field in the help output is a
3473 3473 description of the corresponding field in the JSON output. The
... ... @@ -3585,7 +3585,7 @@ outfile.pdf&lt;/option&gt;
3585 3585 encoding. In other words, it's best if you don't try to use the
3586 3586 JSON format to extract binary strings from the PDF file, but if
3587 3587 you really had to, it could be done. Note that qpdf's
3588   - <option>--show-object</option> option does not have this
  3588 + @1@option@1@--show-object@2@option@2@ option does not have this
3589 3589 limitation and will reveal the string as encoded in the original
3590 3590 file.
3591 3591 </para>
... ... @@ -3605,9 +3605,9 @@ outfile.pdf&lt;/option&gt;
3605 3605 While qpdf guarantees that keys present in the help will be
3606 3606 present in the output, those fields may be null or empty if the
3607 3607 information is not known or absent in the file. Also, if you
3608   - specify <option>--json-keys</option>, the keys that are not
  3608 + specify @1@option@1@--json-keys@2@option@2@, the keys that are not
3609 3609 listed will be excluded entirely except for those that
3610   - <option>--json-help</option> says are always present.
  3610 + @1@option@1@--json-help@2@option@2@ says are always present.
3611 3611 </para>
3612 3612 </listitem>
3613 3613 <listitem>
... ... @@ -3633,13 +3633,13 @@ outfile.pdf&lt;/option&gt;
3633 3633 section of the JSON output includes the key
3634 3634 &ldquo;<literal>filterable</literal>&rdquo;. Note that the
3635 3635 value of this field may depend on the
3636   - <option>--decode-level</option> that you invoke qpdf with. The
  3636 + @1@option@1@--decode-level@2@option@2@ that you invoke qpdf with. The
3637 3637 JSON output includes a top-level key
3638 3638 &ldquo;<literal>parameters</literal>&rdquo; that indicates the
3639 3639 decode level used for computing whether a stream was
3640 3640 filterable. For example, jpeg images will be shown as not
3641 3641 filterable by default, but they will be shown as filterable if
3642   - you run <command>qpdf --json --decode-level=all</command>.
  3642 + you run @1@command@1@qpdf --json --decode-level=all@2@command@2@.
3643 3643 </para>
3644 3644 </listitem>
3645 3645 </itemizedlist>
... ... @@ -3748,7 +3748,7 @@ outfile.pdf&lt;/option&gt;
3748 3748 object from a string representation of the object. Existing
3749 3749 instances of <classname>QPDFObjectHandle</classname> can also be
3750 3750 modified in several ways. See comments in
3751   - <filename>QPDFObjectHandle.hh</filename> for details.
  3751 + @1@filename@1@QPDFObjectHandle.hh@2@filename@2@ for details.
3752 3752 </para>
3753 3753 <para>
3754 3754 An instance of <classname>QPDF</classname> is constructed by using
... ... @@ -3785,8 +3785,8 @@ outfile.pdf&lt;/option&gt;
3785 3785 There are some convenience routines for very common operations
3786 3786 such as walking the page tree and returning a vector of all page
3787 3787 objects. For full details, please see the header files
3788   - <filename>QPDF.hh</filename> and
3789   - <filename>QPDFObjectHandle.hh</filename>. There are also some
  3788 + @1@filename@1@QPDF.hh@2@filename@2@ and
  3789 + @1@filename@1@QPDFObjectHandle.hh@2@filename@2@. There are also some
3790 3790 additional helper classes that provide higher level API functions
3791 3791 for certain document constructions. These are discussed in <xref
3792 3792 linkend="ref.helper-classes"/>.
... ... @@ -3868,8 +3868,8 @@ outfile.pdf&lt;/option&gt;
3868 3868 are derived from <classname>QPDFObjectHelper</classname>. For
3869 3869 details on specific helpers, please see their header files. You
3870 3870 can find them by looking at
3871   - <filename>include/qpdf/QPDF*DocumentHelper.hh</filename> and
3872   - <filename>include/qpdf/QPDF*ObjectHelper.hh</filename>.
  3871 + @1@filename@1@include/qpdf/QPDF*DocumentHelper.hh@2@filename@2@ and
  3872 + @1@filename@1@include/qpdf/QPDF*ObjectHelper.hh@2@filename@2@.
3873 3873 </para>
3874 3874 <para>
3875 3875 In order to avoid creation of circular dependencies, the following
... ... @@ -3999,7 +3999,7 @@ outfile.pdf&lt;/option&gt;
3999 3999 <listitem>
4000 4000 <para>
4001 4001 The <classname>QPDF</classname> class checks the beginning of
4002   - <filename>a.pdf</filename> for a PDF header. It then reads the
  4002 + @1@filename@1@a.pdf@2@filename@2@ for a PDF header. It then reads the
4003 4003 cross reference table mentioned at the end of the file,
4004 4004 ensuring that it is looking before the last
4005 4005 <literal>%%EOF</literal>. After getting to
... ... @@ -4107,7 +4107,7 @@ outfile.pdf&lt;/option&gt;
4107 4107 </para>
4108 4108 <para>
4109 4109 The <classname>QIntC</classname> namespace, provided by
4110   - <filename>include/qpdf/QIntC.hh</filename>, implements safe
  4110 + @1@filename@1@include/qpdf/QIntC.hh@2@filename@2@, implements safe
4111 4111 functions for converting between integer types. These functions do
4112 4112 range checking and throw a <type>std::range_error</type>, which is
4113 4113 subclass of <type>std::runtime_error</type>, if conversion from one
... ... @@ -4263,7 +4263,7 @@ outfile.pdf&lt;/option&gt;
4263 4263 dependency on Microsoft's cryptography API. You can also supply
4264 4264 your own random data provider. For details on how to do this,
4265 4265 please refer to the top-level README.md file in the source
4266   - distribution and to comments in <filename>QUtil.hh</filename>.
  4266 + distribution and to comments in @1@filename@1@QUtil.hh@2@filename@2@.
4267 4267 </para>
4268 4268 </sect1>
4269 4269 <sect1 id="ref.adding-and-remove-pages">
... ... @@ -4276,7 +4276,7 @@ outfile.pdf&lt;/option&gt;
4276 4276 <literal>/Pages</literal> tree down to individual pages and
4277 4277 manipulation of the <literal>/Pages</literal> tree itself. For
4278 4278 details, see <function>addPage</function> and surrounding methods
4279   - in <filename>QPDF.hh</filename>.
  4279 + in @1@filename@1@QPDF.hh@2@filename@2@.
4280 4280 </para>
4281 4281 </sect1>
4282 4282 <sect1 id="ref.reserved-objects">
... ... @@ -4294,7 +4294,7 @@ outfile.pdf&lt;/option&gt;
4294 4294 <classname>QPDF</classname> object prior to version 3.0 would be
4295 4295 to add the new objects first and then make them refer to each
4296 4296 other after adding them. Now it is possible to create a
4297   - <firstterm>reserved object</firstterm> using
  4297 + @1@firstterm@1@reserved object@2@firstterm@2@ using
4298 4298 <function>QPDFObjectHandle::newReserved</function>. This is an
4299 4299 indirect object that stays &ldquo;unresolved&rdquo; even if it is
4300 4300 queried for its type. So now, if you want to create a set of
... ... @@ -4307,7 +4307,7 @@ outfile.pdf&lt;/option&gt;
4307 4307 when copying objects from other PDF files, as discussed in <xref
4308 4308 linkend="ref.foreign-objects"/>. For an example of how to use
4309 4309 reserved objects, search for <function>newReserved</function> in
4310   - <filename>test_driver.cc</filename> in qpdf's sources.
  4310 + @1@filename@1@test_driver.cc@2@filename@2@ in qpdf's sources.
4311 4311 </para>
4312 4312 </sect1>
4313 4313 <sect1 id="ref.foreign-objects">
... ... @@ -4316,10 +4316,10 @@ outfile.pdf&lt;/option&gt;
4316 4316 Version 3.0 of qpdf introduced the ability to copy objects into a
4317 4317 <classname>QPDF</classname> object from a different
4318 4318 <classname>QPDF</classname> object, which we refer to as
4319   - <firstterm>foreign objects</firstterm>. This allows arbitrary
  4319 + @1@firstterm@1@foreign objects@2@firstterm@2@. This allows arbitrary
4320 4320 merging of PDF files. The &ldquo;from&rdquo;
4321 4321 <classname>QPDF</classname> object must remain valid after the
4322   - copy as discussed in the note below. The <command>qpdf</command>
  4322 + copy as discussed in the note below. The @1@command@1@qpdf@2@command@2@
4323 4323 command-line tool provides limited support for basic page
4324 4324 selection, including merging in pages from other files, but the
4325 4325 library's API makes it possible to implement arbitrarily complex
... ... @@ -4447,7 +4447,7 @@ outfile.pdf&lt;/option&gt;
4447 4447 </listitem>
4448 4448 <listitem>
4449 4449 <para>
4450   - Write <literal><replaceable>n</replaceable> 0 obj</literal>.
  4450 + Write <literal>@1@replaceable@1@n@2@replaceable@2@ 0 obj</literal>.
4451 4451 </para>
4452 4452 </listitem>
4453 4453 <listitem>
... ... @@ -4540,7 +4540,7 @@ outfile.pdf&lt;/option&gt;
4540 4540 pipeline may be an end-of-the-line pipeline that does something
4541 4541 like store its output to a file or a memory buffer ignoring a
4542 4542 successor. For additional details, look at
4543   - <filename>Pipeline.hh</filename>.
  4543 + @1@filename@1@Pipeline.hh@2@filename@2@.
4544 4544 </para>
4545 4545 <para>
4546 4546 <classname>QPDF</classname> can read raw or filtered streams.
... ... @@ -4558,7 +4558,7 @@ outfile.pdf&lt;/option&gt;
4558 4558 <para>
4559 4559 For general information about how to access instances of
4560 4560 <classname>QPDFObjectHandle</classname>, please see the comments
4561   - in <filename>QPDFObjectHandle.hh</filename>. Search for
  4561 + in @1@filename@1@QPDFObjectHandle.hh@2@filename@2@. Search for
4562 4562 &ldquo;Accessor methods&rdquo;. This section provides a more
4563 4563 in-depth discussion of the behavior and the rationale for the
4564 4564 behavior.
... ... @@ -4655,9 +4655,9 @@ outfile.pdf&lt;/option&gt;
4655 4655 <para>
4656 4656 To avoid the incestuous problem of having the qpdf library
4657 4657 validate its own linearized files, we have a special linearized
4658   - file checking mode which can be invoked via <command>qpdf
4659   - --check-linearization</command> (or <command>qpdf
4660   - --check</command>). This mode reads the linearization parameter
  4658 + file checking mode which can be invoked via @1@command@1@qpdf
  4659 + --check-linearization@2@command@2@ (or @1@command@1@qpdf
  4660 + --check@2@command@2@). This mode reads the linearization parameter
4661 4661 dictionary and the hint streams and validates that object
4662 4662 ordering, parameters, and hint stream contents are correct. The
4663 4663 validation code was first tested against linearized files created
... ... @@ -4674,10 +4674,10 @@ outfile.pdf&lt;/option&gt;
4674 4674 in the <literal>/Pages</literal> tree). We also have to know
4675 4675 which objects refer to which other objects, being concerned with
4676 4676 page boundaries and a few other cases. We refer to this part of
4677   - preparing the PDF file as <firstterm>optimization</firstterm>,
  4677 + preparing the PDF file as @1@firstterm@1@optimization@2@firstterm@2@,
4678 4678 discussed in <xref linkend="ref.optimization"/>. Note the, in
4679   - this context, the term <firstterm>optimization</firstterm> is a
4680   - qpdf term, and the term <firstterm>linearization</firstterm> is a
  4679 + this context, the term @1@firstterm@1@optimization@2@firstterm@2@ is a
  4680 + qpdf term, and the term @1@firstterm@1@linearization@2@firstterm@2@ is a
4681 4681 term from the PDF specification. Do not be confused by the fact
4682 4682 that many applications refer to linearization as optimization or
4683 4683 web optimization.
... ... @@ -4716,14 +4716,14 @@ outfile.pdf&lt;/option&gt;
4716 4716 </para>
4717 4717 <para>
4718 4718 We refer to the process of enforcing these constraints as
4719   - <firstterm>optimization</firstterm>. As mentioned above, note
  4719 + @1@firstterm@1@optimization@2@firstterm@2@. As mentioned above, note
4720 4720 that some applications refer to linearization as optimization.
4721 4721 Although this optimization was initially motivated by the need to
4722 4722 create linearized files, we are using these terms separately.
4723 4723 </para>
4724 4724 <para>
4725 4725 PDF file optimization is implemented in the
4726   - <filename>QPDF_optimization.cc</filename> source file. That file
  4726 + @1@filename@1@QPDF_optimization.cc@2@filename@2@ source file. That file
4727 4727 is richly commented and serves as the primary reference for the
4728 4728 optimization process.
4729 4729 </para>
... ... @@ -4857,11 +4857,11 @@ outfile.pdf&lt;/option&gt;
4857 4857 <sect1 id="ref.linearization-debugging">
4858 4858 <title>Debugging Note</title>
4859 4859 <para>
4860   - The <command>qpdf --show-linearization</command> command can show
  4860 + The @1@command@1@qpdf --show-linearization@2@command@2@ command can show
4861 4861 the complete contents of linearization hint streams. To look at
4862 4862 the raw data, you can extract the filtered contents of the
4863   - linearization hint tables using <command>qpdf --show-object=n
4864   - --filtered-stream-data</command>. Then, to convert this into a
  4863 + linearization hint tables using @1@command@1@qpdf --show-object=n
  4864 + --filtered-stream-data@2@command@2@. Then, to convert this into a
4865 4865 bit stream (since linearization tables are bit streams written
4866 4866 without regard to byte boundaries), you can pipe the resulting
4867 4867 data through the following perl code:
... ... @@ -5022,7 +5022,7 @@ print &quot;\n&quot;;
5022 5022 <listitem>
5023 5023 <para>
5024 5024 <literal>/Index</literal> (optional): value
5025   - <literal>[<replaceable>n count</replaceable> ...]</literal>
  5025 + <literal>[@1@replaceable@1@n count@2@replaceable@2@ ...]</literal>
5026 5026 used to determine which objects' information is stored in this
5027 5027 stream. The default is <literal>[0 /Size]</literal>.
5028 5028 </para>
... ... @@ -5030,7 +5030,7 @@ print &quot;\n&quot;;
5030 5030 <listitem>
5031 5031 <para>
5032 5032 <literal>/Prev</literal>: value
5033   - <replaceable>offset</replaceable>: byte offset of previous xref
  5033 + @1@replaceable@1@offset@2@replaceable@2@: byte offset of previous xref
5034 5034 stream (same as <literal>/Prev</literal> in the trailer
5035 5035 dictionary)
5036 5036 </para>
... ... @@ -5127,8 +5127,8 @@ print &quot;\n&quot;;
5127 5127 <title>Implementation Notes</title>
5128 5128 <para>
5129 5129 There are three modes for writing object streams:
5130   - <option>disable</option>, <option>preserve</option>, and
5131   - <option>generate</option>. In disable mode, we do not generate
  5130 + @1@option@1@disable@2@option@2@, @1@option@1@preserve@2@option@2@, and
  5131 + @1@option@1@generate@2@option@2@. In disable mode, we do not generate
5132 5132 any object streams, and we also generate an xref table rather than
5133 5133 xref streams. This can be used to generate PDF files that are
5134 5134 viewable with older readers. In preserve mode, we write object
... ... @@ -5139,7 +5139,7 @@ print &quot;\n&quot;;
5139 5139 objects that are allowed in object streams together in sets of no
5140 5140 more than 100 objects. We also ensure that the PDF version is at
5141 5141 least 1.5 in generate mode, but we preserve the version header in
5142   - the other modes. The default is <option>preserve</option>.
  5142 + the other modes. The default is @1@option@1@preserve@2@option@2@.
5143 5143 </para>
5144 5144 <para>
5145 5145 We do not support creation of hybrid files. When we write files,
... ... @@ -5152,7 +5152,7 @@ print &quot;\n&quot;;
5152 5152 <title>Release Notes</title>
5153 5153 <para>
5154 5154 For a detailed list of changes, please see the file
5155   - <filename>ChangeLog</filename> in the source distribution.
  5155 + @1@filename@1@ChangeLog@2@filename@2@ in the source distribution.
5156 5156 </para>
5157 5157 <variablelist>
5158 5158 <!--
... ... @@ -5215,7 +5215,7 @@ print &quot;\n&quot;;
5215 5215 These warnings now have an error code of
5216 5216 <literal>qpdf_e_object</literal> instead of
5217 5217 <literal>qpdf_e_damaged_pdf</literal>. Also, comments have
5218   - been added to <filename>QPDFObjectHandle.hh</filename> to
  5218 + been added to @1@filename@1@QPDFObjectHandle.hh@2@filename@2@ to
5219 5219 explain in more detail what the behavior is. See <xref
5220 5220 linkend="ref.object-accessors"/> for a more in-depth
5221 5221 discussion.
... ... @@ -5225,7 +5225,7 @@ print &quot;\n&quot;;
5225 5225 <para>
5226 5226 Overhaul error handling for the object handle functions in
5227 5227 the C API. See comments in the &ldquo;Object handling&rdquo;
5228   - section of <filename>include/qpdf/qpdf-c.h</filename> for
  5228 + section of @1@filename@1@include/qpdf/qpdf-c.h@2@filename@2@ for
5229 5229 details. In particular, exceptions thrown by the underlying
5230 5230 C++ code when calling object accessors are caught and
5231 5231 converted into errors. The errors can be trapped by
... ... @@ -5280,7 +5280,7 @@ print &quot;\n&quot;;
5280 5280 <itemizedlist>
5281 5281 <listitem>
5282 5282 <para>
5283   - From the qpdf CLI, the <option>--allow-weak-crypto</option>
  5283 + From the qpdf CLI, the @1@option@1@--allow-weak-crypto@2@option@2@
5284 5284 is now required to suppress a warning when explicitly
5285 5285 creating PDF files using RC4 encryption. While qpdf will
5286 5286 always retain the ability to read and write such files,
... ... @@ -5314,7 +5314,7 @@ print &quot;\n&quot;;
5314 5314 <listitem>
5315 5315 <para>
5316 5316 Fix crash that could occur under certain conditions when
5317   - using <option>--pages</option> with files that had form
  5317 + using @1@option@1@--pages@2@option@2@ with files that had form
5318 5318 fields.
5319 5319 </para>
5320 5320 </listitem>
... ... @@ -5355,7 +5355,7 @@ print &quot;\n&quot;;
5355 5355 <itemizedlist>
5356 5356 <listitem>
5357 5357 <para>
5358   - Improve diagnostics around parsing <option>--pages</option>
  5358 + Improve diagnostics around parsing @1@option@1@--pages@2@option@2@
5359 5359 command-line options
5360 5360 </para>
5361 5361 </listitem>
... ... @@ -5390,7 +5390,7 @@ print &quot;\n&quot;;
5390 5390 <para>
5391 5391 When generating a file while preserving object streams,
5392 5392 unreferenced objects are correctly removed unless
5393   - <option>--preserve-unreferenced</option> is specified.
  5393 + @1@option@1@--preserve-unreferenced@2@option@2@ is specified.
5394 5394 </para>
5395 5395 </listitem>
5396 5396 </itemizedlist>
... ... @@ -5405,7 +5405,7 @@ print &quot;\n&quot;;
5405 5405 When adding a page that already exists, make a shallow copy
5406 5406 instead of throwing an exception. This makes the library
5407 5407 behavior consistent with the CLI behavior. See
5408   - <filename>ChangeLog</filename> for additional notes.
  5408 + @1@filename@1@ChangeLog@2@filename@2@ for additional notes.
5409 5409 </para>
5410 5410 </listitem>
5411 5411 </itemizedlist>
... ... @@ -5495,7 +5495,7 @@ print &quot;\n&quot;;
5495 5495 are in methods most people would never call and that will
5496 5496 hopefully be superseded by higher-level interfaces for
5497 5497 handling page copies. Please see the
5498   - <filename>ChangeLog</filename> file for details.
  5498 + @1@filename@1@ChangeLog@2@filename@2@ file for details.
5499 5499 </para>
5500 5500 </listitem>
5501 5501 <listitem>
... ... @@ -5523,10 +5523,10 @@ print &quot;\n&quot;;
5523 5523 <para>
5524 5524 Operations that work on combining pages are much better
5525 5525 about protecting form fields. In particular,
5526   - <option>--split-pages</option> and <option>--pages</option>
  5526 + @1@option@1@--split-pages@2@option@2@ and @1@option@1@--pages@2@option@2@
5527 5527 now preserve interaction form functionality by copying the
5528 5528 relevant form field information from the original files.
5529   - Additionally, if you use <option>--pages</option> to select
  5529 + Additionally, if you use @1@option@1@--pages@2@option@2@ to select
5530 5530 only some pages from the original input file, unused form
5531 5531 fields are removed, which prevents lots of unused
5532 5532 annotations from being retained.
... ... @@ -5534,11 +5534,11 @@ print &quot;\n&quot;;
5534 5534 </listitem>
5535 5535 <listitem>
5536 5536 <para>
5537   - By default, <command>qpdf</command> no longer allows
  5537 + By default, @1@command@1@qpdf@2@command@2@ no longer allows
5538 5538 creation of encrypted PDF files whose user password is
5539 5539 non-empty and owner password is empty when a 256-bit key is
5540   - in use. The <option>--allow-insecure</option> option,
5541   - specified inside the <option>--encrypt</option> options,
  5540 + in use. The @1@option@1@--allow-insecure@2@option@2@ option,
  5541 + specified inside the @1@option@1@--encrypt@2@option@2@ options,
5542 5542 allows creation of such files. Behavior changes in the CLI
5543 5543 are avoided when possible, but an exception was made here
5544 5544 because this is security-related. qpdf must always allow
... ... @@ -5609,7 +5609,7 @@ print &quot;\n&quot;;
5609 5609 <listitem>
5610 5610 <para>
5611 5611 Page splitting and merging operations, as well as
5612   - <option>--flatten-rotation</option>, are better behaved
  5612 + @1@option@1@--flatten-rotation@2@option@2@, are better behaved
5613 5613 with respect to annotations and interactive form fields. In
5614 5614 most cases, interactive form field functionality and proper
5615 5615 formatting and functionality of annotations is preserved by
... ... @@ -5626,12 +5626,12 @@ print &quot;\n&quot;;
5626 5626 <listitem>
5627 5627 <para>
5628 5628 The option
5629   - <option>--password-file=<replaceable>filename</replaceable></option>
  5629 + @1@option@1@--password-file=@1@replaceable@1@filename@2@replaceable@2@@2@option@2@
5630 5630 can now be used to read the decryption password from a file.
5631 5631 You can use <literal>-</literal> as the file name to read
5632 5632 the password from standard input. This is an easier/more
5633 5633 obvious way to read passwords from files or standard input
5634   - than using <option>@file</option> for this purpose.
  5634 + than using @1@option@1@@file@2@option@2@ for this purpose.
5635 5635 </para>
5636 5636 </listitem>
5637 5637 <listitem>
... ... @@ -5649,15 +5649,15 @@ print &quot;\n&quot;;
5649 5649 </listitem>
5650 5650 <listitem>
5651 5651 <para>
5652   - Add numeric option to <option>--collate</option>. If
5653   - <option>--collate=<replaceable>n</replaceable></option> is
5654   - given, take pages in groups of <replaceable>n</replaceable>
  5652 + Add numeric option to @1@option@1@--collate@2@option@2@. If
  5653 + @1@option@1@--collate=@1@replaceable@1@n@2@replaceable@2@@2@option@2@ is
  5654 + given, take pages in groups of @1@replaceable@1@n@2@replaceable@2@
5655 5655 from the given files.
5656 5656 </para>
5657 5657 </listitem>
5658 5658 <listitem>
5659 5659 <para>
5660   - It is now valid to provide <option>--rotate=0</option> to
  5660 + It is now valid to provide @1@option@1@--rotate=0@2@option@2@ to
5661 5661 clear rotation from a page.
5662 5662 </para>
5663 5663 </listitem>
... ... @@ -5672,7 +5672,7 @@ print &quot;\n&quot;;
5672 5672 <para>
5673 5673 This release includes numerous additions to the API. Not all
5674 5674 changes are listed here. Please see the
5675   - <filename>ChangeLog</filename> file in the source
  5675 + @1@filename@1@ChangeLog@2@filename@2@ file in the source
5676 5676 distribution for a comprehensive list. Highlights appear
5677 5677 below.
5678 5678 </para>
... ... @@ -5683,8 +5683,8 @@ print &quot;\n&quot;;
5683 5683 <function>QPDFObjectHandle::aitems()</function> that enable
5684 5684 C++-style iteration, including range-for iteration, over
5685 5685 dictionary and array QPDFObjectHandles. See comments in
5686   - <filename>include/qpdf/QPDFObjectHandle.hh</filename> and
5687   - <filename>examples/pdf-name-number-tree.cc</filename> for
  5686 + @1@filename@1@include/qpdf/QPDFObjectHandle.hh@2@filename@2@ and
  5687 + @1@filename@1@examples/pdf-name-number-tree.cc@2@filename@2@ for
5688 5688 details.
5689 5689 </para>
5690 5690 </listitem>
... ... @@ -5703,7 +5703,7 @@ print &quot;\n&quot;;
5703 5703 <classname>QPDFFileSpecObjectHelper</classname>, and
5704 5704 <classname>QPDFEFStreamObjectHelper</classname>. See their
5705 5705 respective headers for details and
5706   - <filename>examples/pdf-attach-file.cc</filename> for an
  5706 + @1@filename@1@examples/pdf-attach-file.cc@2@filename@2@ for an
5707 5707 example.
5708 5708 </para>
5709 5709 </listitem>
... ... @@ -5714,7 +5714,7 @@ print &quot;\n&quot;;
5714 5714 <classname>QPDF</classname> pointer as context so that it
5715 5715 can parse strings containing indirect object references.
5716 5716 This is illustrated in
5717   - <filename>examples/pdf-attach-file.cc</filename>.
  5717 + @1@filename@1@examples/pdf-attach-file.cc@2@filename@2@.
5718 5718 </para>
5719 5719 </listitem>
5720 5720 <listitem>
... ... @@ -5742,13 +5742,13 @@ print &quot;\n&quot;;
5742 5742 <para>
5743 5743 The <classname>QPDFMatrix</classname> class, formerly a
5744 5744 private, internal class, has been added to the public API.
5745   - See <filename>include/qpdf/QPDFMatrix.hh</filename> for
  5745 + See @1@filename@1@include/qpdf/QPDFMatrix.hh@2@filename@2@ for
5746 5746 details. This class is for working with transformation
5747 5747 matrices. Some methods in
5748 5748 <classname>QPDFPageObjectHelper</classname> make use of this
5749 5749 to make information about transformation matrices available.
5750 5750 For an example, see
5751   - <filename>examples/pdf-overlay-page.cc</filename>.
  5751 + @1@filename@1@examples/pdf-overlay-page.cc@2@filename@2@.
5752 5752 </para>
5753 5753 </listitem>
5754 5754 <listitem>
... ... @@ -5799,7 +5799,7 @@ print &quot;\n&quot;;
5799 5799 <itemizedlist>
5800 5800 <listitem>
5801 5801 <para>
5802   - The <option>--flatten-rotation</option> option applies
  5802 + The @1@option@1@--flatten-rotation@2@option@2@ option applies
5803 5803 transformations to any annotations that may be on the page.
5804 5804 </para>
5805 5805 </listitem>
... ... @@ -5843,7 +5843,7 @@ print &quot;\n&quot;;
5843 5843 <itemizedlist>
5844 5844 <listitem>
5845 5845 <para>
5846   - Add <option>--flatten-rotation</option> command-line option,
  5846 + Add @1@option@1@--flatten-rotation@2@option@2@ command-line option,
5847 5847 which causes all pages that are rotated using parameters in
5848 5848 the page's dictionary to instead be identically rotated in
5849 5849 the page's contents. The change is not user-visible for
... ... @@ -5867,7 +5867,7 @@ print &quot;\n&quot;;
5867 5867 including those used by <classname>QPDFWriter</classname>,
5868 5868 can decode streams with filters not directly supported by
5869 5869 the library. The example
5870   - <filename>examples/pdf-custom-filter.cc</filename>
  5870 + @1@filename@1@examples/pdf-custom-filter.cc@2@filename@2@
5871 5871 illustrates how to use this capability.
5872 5872 </para>
5873 5873 </listitem>
... ... @@ -5886,7 +5886,7 @@ print &quot;\n&quot;;
5886 5886 Enhance several methods in
5887 5887 <classname>QPDFPageObjectHelper</classname> to work with
5888 5888 form XObjects as well as pages, as noted in comments. See
5889   - <filename>ChangeLog</filename> for a full list.
  5889 + @1@filename@1@ChangeLog@2@filename@2@ for a full list.
5890 5890 </para>
5891 5891 </listitem>
5892 5892 <listitem>
... ... @@ -6017,7 +6017,7 @@ print &quot;\n&quot;;
6017 6017 </listitem>
6018 6018 <listitem>
6019 6019 <para>
6020   - When extracting pages, the <command>qpdf</command> CLI only
  6020 + When extracting pages, the @1@command@1@qpdf@2@command@2@ CLI only
6021 6021 removes unreferenced resources from the pages that are being
6022 6022 kept, resulting in a significant performance improvement
6023 6023 when extracting small numbers of pages from large, complex
... ... @@ -6110,7 +6110,7 @@ print &quot;\n&quot;;
6110 6110 <listitem>
6111 6111 <para>
6112 6112 When concatenating content streams, as with
6113   - <option>--coalesce-contents</option>, there were cases in
  6113 + @1@option@1@--coalesce-contents@2@option@2@, there were cases in
6114 6114 which qpdf would merge two lexical tokens together, creating
6115 6115 invalid results. A newline is now inserted between
6116 6116 merged content streams if one is not already present.
... ... @@ -6137,7 +6137,7 @@ print &quot;\n&quot;;
6137 6137 <listitem>
6138 6138 <para>
6139 6139 Fix several instances in which warnings were not suppressed
6140   - in spite of <option>--no-warn</option> and/or errors or
  6140 + in spite of @1@option@1@--no-warn@2@option@2@ and/or errors or
6141 6141 warnings were written to standard output rather than
6142 6142 standard error.
6143 6143 </para>
... ... @@ -6146,7 +6146,7 @@ print &quot;\n&quot;;
6146 6146 <para>
6147 6147 Fixed a memory leak that could occur under specific
6148 6148 circumstances when
6149   - <option>--object-streams=generate</option> was used.
  6149 + @1@option@1@--object-streams=generate@2@option@2@ was used.
6150 6150 </para>
6151 6151 </listitem>
6152 6152 <listitem>
... ... @@ -6164,10 +6164,10 @@ print &quot;\n&quot;;
6164 6164 <itemizedlist>
6165 6165 <listitem>
6166 6166 <para>
6167   - New option <option>--warning-exit-0</option> causes qpdf to
  6167 + New option @1@option@1@--warning-exit-0@2@option@2@ causes qpdf to
6168 6168 exit with a status of <literal>0</literal> rather than
6169 6169 <literal>3</literal> if there are warnings but no errors.
6170   - Combine with <option>--no-warn</option> to completely ignore
  6170 + Combine with @1@option@1@--no-warn@2@option@2@ to completely ignore
6171 6171 warnings.
6172 6172 </para>
6173 6173 </listitem>
... ... @@ -6192,8 +6192,8 @@ print &quot;\n&quot;;
6192 6192 <itemizedlist>
6193 6193 <listitem>
6194 6194 <para>
6195   - The option <option>--disable-rpath</option> is now supported
6196   - by qpdf's <command>./configure</command> script. Some
  6195 + The option @1@option@1@--disable-rpath@2@option@2@ is now supported
  6196 + by qpdf's @1@command@1@./configure@2@command@2@ script. Some
6197 6197 distributions' packaging standards recommended the use of
6198 6198 this option.
6199 6199 </para>
... ... @@ -6205,7 +6205,7 @@ print &quot;\n&quot;;
6205 6205 an autoconf test. If you are using your own build system,
6206 6206 you will need to provide a value for
6207 6207 <literal>LL_FMT</literal> in
6208   - <filename>libqpdf/qpdf/qpdf-config.h</filename>, which would
  6208 + @1@filename@1@libqpdf/qpdf/qpdf-config.h@2@filename@2@, which would
6209 6209 typically be <literal>&quot;%lld&quot;</literal> or, for
6210 6210 some Windows compilers, <literal>&quot;%I64d&quot;</literal>.
6211 6211 </para>
... ... @@ -6295,7 +6295,7 @@ print &quot;\n&quot;;
6295 6295 <itemizedlist>
6296 6296 <listitem>
6297 6297 <para>
6298   - Improve the <filename>pdf-invert-images</filename> example
  6298 + Improve the @1@filename@1@pdf-invert-images@2@filename@2@ example
6299 6299 to avoid having to load all the images into RAM at the same
6300 6300 time.
6301 6301 </para>
... ... @@ -6386,14 +6386,14 @@ print &quot;\n&quot;;
6386 6386 object indicating whether it is a stream and, if so, what
6387 6387 its length and filters are. Without this, it was not
6388 6388 possible to tell conclusively from the JSON output alone
6389   - whether or not an object was a stream. Run <command>qpdf
6390   - --json-help</command> for details.
  6389 + whether or not an object was a stream. Run @1@command@1@qpdf
  6390 + --json-help@2@command@2@ for details.
6391 6391 </para>
6392 6392 </listitem>
6393 6393 <listitem>
6394 6394 <para>
6395 6395 Add new option
6396   - <option>--remove-unreferenced-resources</option> which takes
  6396 + @1@option@1@--remove-unreferenced-resources@2@option@2@ which takes
6397 6397 <literal>auto</literal>, <literal>yes</literal>, or
6398 6398 <literal>no</literal> as arguments. The new
6399 6399 <literal>auto</literal> mode, which is the default, performs
... ... @@ -6408,21 +6408,21 @@ print &quot;\n&quot;;
6408 6408 </listitem>
6409 6409 <listitem>
6410 6410 <para>
6411   - The <option>--preserve-unreferenced-resources</option> is
  6411 + The @1@option@1@--preserve-unreferenced-resources@2@option@2@ is
6412 6412 now just a synonym for
6413   - <option>--remove-unreferenced-resources=no</option>.
  6413 + @1@option@1@--remove-unreferenced-resources=no@2@option@2@.
6414 6414 </para>
6415 6415 </listitem>
6416 6416 <listitem>
6417 6417 <para>
6418 6418 If the <literal>QPDF_EXECUTABLE</literal> environment
6419   - variable is set when invoking <command>qpdf
6420   - --bash-completion</command> or <command>qpdf
6421   - --zsh-completion</command>, the completion command that it
  6419 + variable is set when invoking @1@command@1@qpdf
  6420 + --bash-completion@2@command@2@ or @1@command@1@qpdf
  6421 + --zsh-completion@2@command@2@, the completion command that it
6422 6422 outputs will refer to qpdf using the value of that variable
6423   - rather than what <command>qpdf</command> determines its
  6423 + rather than what @1@command@1@qpdf@2@command@2@ determines its
6424 6424 executable path to be. This can be useful when wrapping
6425   - <command>qpdf</command> with a script, working with a
  6425 + @1@command@1@qpdf@2@command@2@ with a script, working with a
6426 6426 version in the source tree, using an AppImage, or other
6427 6427 situations where there is some indirection.
6428 6428 </para>
... ... @@ -6582,8 +6582,8 @@ print &quot;\n&quot;;
6582 6582 <itemizedlist>
6583 6583 <listitem>
6584 6584 <para>
6585   - Added options <option>--is-encrypted</option> and
6586   - <option>--requires-password</option> for testing whether a
  6585 + Added options @1@option@1@--is-encrypted@2@option@2@ and
  6586 + @1@option@1@--requires-password@2@option@2@ for testing whether a
6587 6587 file is encrypted or requires a password other than the
6588 6588 supplied (or empty) password. These communicate via exit
6589 6589 status, making them useful for shell scripts. They also work
... ... @@ -6597,9 +6597,9 @@ print &quot;\n&quot;;
6597 6597 Added <literal>encrypt</literal> key to JSON options. With
6598 6598 the exception of the reconstructed user password for older
6599 6599 encryption formats, this provides the same information as
6600   - <option>--show-encryption</option> but in a consistent,
6601   - parseable format. See output of <command>qpdf
6602   - --json-help</command> for details.
  6600 + @1@option@1@--show-encryption@2@option@2@ but in a consistent,
  6601 + parseable format. See output of @1@command@1@qpdf
  6602 + --json-help@2@command@2@ for details.
6603 6603 </para>
6604 6604 </listitem>
6605 6605 </itemizedlist>
... ... @@ -6613,8 +6613,8 @@ print &quot;\n&quot;;
6613 6613 <para>
6614 6614 In QDF mode, be sure not to write more than one XRef stream
6615 6615 to a file, even when
6616   - <option>--preserve-unreferenced</option> is used.
6617   - <command>fix-qdf</command> assumes that there is only one
  6616 + @1@option@1@--preserve-unreferenced@2@option@2@ is used.
  6617 + @1@command@1@fix-qdf@2@command@2@ assumes that there is only one
6618 6618 XRef stream, and that it appears at the end of the file.
6619 6619 </para>
6620 6620 </listitem>
... ... @@ -6711,7 +6711,7 @@ print &quot;\n&quot;;
6711 6711 <itemizedlist>
6712 6712 <listitem>
6713 6713 <para>
6714   - Addition of the <option>--show-crypto</option> option in
  6714 + Addition of the @1@option@1@--show-crypto@2@option@2@ option in
6715 6715 support of selectable crypto providers, as described in
6716 6716 <xref linkend="ref.crypto"/>.
6717 6717 </para>
... ... @@ -6726,7 +6726,7 @@ print &quot;\n&quot;;
6726 6726 <listitem>
6727 6727 <para>
6728 6728 Fix shell wildcard expansion behavior (<literal>*</literal>
6729   - and <literal>?</literal>) of the <command>qpdf.exe</command>
  6729 + and <literal>?</literal>) of the @1@command@1@qpdf.exe@2@command@2@
6730 6730 as built my MSVC.
6731 6731 </para>
6732 6732 </listitem>
... ... @@ -6747,7 +6747,7 @@ print &quot;\n&quot;;
6747 6747 <listitem>
6748 6748 <para>
6749 6749 Fix the name of the temporary file used by
6750   - <option>--replace-input</option> so that it doesn't require
  6750 + @1@option@1@--replace-input@2@option@2@ so that it doesn't require
6751 6751 path splitting and works with paths include directories.
6752 6752 </para>
6753 6753 </listitem>
... ... @@ -6861,29 +6861,29 @@ print &quot;\n&quot;;
6861 6861 <itemizedlist>
6862 6862 <listitem>
6863 6863 <para>
6864   - The <option>--replace-input</option> option may be given in
  6864 + The @1@option@1@--replace-input@2@option@2@ option may be given in
6865 6865 place of an output file name. This causes qpdf to overwrite
6866 6866 the input file with the output. See the description of
6867   - <option>--replace-input</option> in <xref
  6867 + @1@option@1@--replace-input@2@option@2@ in <xref
6868 6868 linkend="ref.basic-options"/> for more details.
6869 6869 </para>
6870 6870 </listitem>
6871 6871 <listitem>
6872 6872 <para>
6873   - The <option>--recompress-flate</option> instructs
6874   - <command>qpdf</command> to recompress streams that are
  6873 + The @1@option@1@--recompress-flate@2@option@2@ instructs
  6874 + @1@command@1@qpdf@2@command@2@ to recompress streams that are
6875 6875 already compressed with <literal>/FlateDecode</literal>.
6876   - Useful with <option>--compression-level</option>.
  6876 + Useful with @1@option@1@--compression-level@2@option@2@.
6877 6877 </para>
6878 6878 </listitem>
6879 6879 <listitem>
6880 6880 <para>
6881 6881 The
6882   - <option>--compression-level=<replaceable>level</replaceable></option>
  6882 + @1@option@1@--compression-level=@1@replaceable@1@level@2@replaceable@2@@2@option@2@
6883 6883 sets the zlib compression level used for any streams
6884 6884 compressed by <literal>/FlateDecode</literal>. Most
6885 6885 effective when combined with
6886   - <option>--recompress-flate</option>.
  6886 + @1@option@1@--recompress-flate@2@option@2@.
6887 6887 </para>
6888 6888 </listitem>
6889 6889 </itemizedlist>
... ... @@ -6896,7 +6896,7 @@ print &quot;\n&quot;;
6896 6896 <listitem>
6897 6897 <para>
6898 6898 A new namespace <classname>QIntC</classname>, provided by
6899   - <filename>qpdf/QIntC.hh</filename>, provides safe conversion
  6899 + @1@filename@1@qpdf/QIntC.hh@2@filename@2@, provides safe conversion
6900 6900 methods between different integer types. These conversion
6901 6901 methods do range checking to ensure that the cast can be
6902 6902 performed with no loss of information. Every use of
... ... @@ -6969,9 +6969,9 @@ print &quot;\n&quot;;
6969 6969 and <function>QPDF::ownerPasswordMatched</function> have
6970 6970 been added to enable a caller to determine whether the
6971 6971 supplied password was the user password, the owner password,
6972   - or both. This information is also displayed by <command>qpdf
6973   - --show-encryption</command> and <command>qpdf
6974   - --check</command>.
  6972 + or both. This information is also displayed by @1@command@1@qpdf
  6973 + --show-encryption@2@command@2@ and @1@command@1@qpdf
  6974 + --check@2@command@2@.
6975 6975 </para>
6976 6976 </listitem>
6977 6977 <listitem>
... ... @@ -7026,7 +7026,7 @@ print &quot;\n&quot;;
7026 7026 PDF 1.2 and above, are properly handled by the library: a
7027 7027 warning is generated, and the name token is properly
7028 7028 preserved, even if invalid, in the output. See
7029   - <filename>ChangeLog</filename> for a more complete
  7029 + @1@filename@1@ChangeLog@2@filename@2@ for a more complete
7030 7030 description of this change.
7031 7031 </para>
7032 7032 </listitem>
... ... @@ -7047,16 +7047,16 @@ print &quot;\n&quot;;
7047 7047 </listitem>
7048 7048 <listitem>
7049 7049 <para>
7050   - When <command>qpdf --check</command> or <command>qpdf
7051   - --check-linearization</command> encounters a file with
  7050 + When @1@command@1@qpdf --check@2@command@2@ or @1@command@1@qpdf
  7051 + --check-linearization@2@command@2@ encounters a file with
7052 7052 linearization warnings but not errors, it now properly exits
7053 7053 with exit code 3 instead of 2.
7054 7054 </para>
7055 7055 </listitem>
7056 7056 <listitem>
7057 7057 <para>
7058   - The <option>--completion-bash</option> and
7059   - <option>--completion-zsh</option> options now work properly
  7058 + The @1@option@1@--completion-bash@2@option@2@ and
  7059 + @1@option@1@--completion-zsh@2@option@2@ options now work properly
7060 7060 when qpdf is invoked as an AppImage.
7061 7061 </para>
7062 7062 </listitem>
... ... @@ -7087,7 +7087,7 @@ print &quot;\n&quot;;
7087 7087 <listitem>
7088 7088 <para>
7089 7089 On platforms that support it, qpdf now builds with
7090   - <option>-fvisibility=hidden</option>. If you build qpdf with
  7090 + @1@option@1@-fvisibility=hidden@2@option@2@. If you build qpdf with
7091 7091 your own build system, this is now safe to use. This
7092 7092 prevents methods that are not part of the public API from
7093 7093 being exported by the shared library, and makes qpdf's ELF
... ... @@ -7112,7 +7112,7 @@ print &quot;\n&quot;;
7112 7112 </listitem>
7113 7113 <listitem>
7114 7114 <para>
7115   - QPDF's <command>make install</command> target explicitly
  7115 + QPDF's @1@command@1@make install@2@command@2@ target explicitly
7116 7116 specifies the mode to use when installing files instead of
7117 7117 relying the user's umask. It was previously doing this for
7118 7118 some files but not others.
... ... @@ -7120,9 +7120,9 @@ print &quot;\n&quot;;
7120 7120 </listitem>
7121 7121 <listitem>
7122 7122 <para>
7123   - If <command>pkg-config</command> is available, use it to
7124   - locate <filename>libjpeg</filename> and
7125   - <filename>zlib</filename> dependencies, falling back on old
  7123 + If @1@command@1@pkg-config@2@command@2@ is available, use it to
  7124 + locate @1@filename@1@libjpeg@2@filename@2@ and
  7125 + @1@filename@1@zlib@2@filename@2@ dependencies, falling back on old
7126 7126 behavior if unsuccessful.
7127 7127 </para>
7128 7128 </listitem>
... ... @@ -7170,7 +7170,7 @@ print &quot;\n&quot;;
7170 7170 <itemizedlist>
7171 7171 <listitem>
7172 7172 <para>
7173   - When <command>qpdf --version</command> is run, it will
  7173 + When @1@command@1@qpdf --version@2@command@2@ is run, it will
7174 7174 detect if the qpdf CLI was built with a different version of
7175 7175 qpdf than the library, which may indicate a problem with the
7176 7176 installation.
... ... @@ -7178,9 +7178,9 @@ print &quot;\n&quot;;
7178 7178 </listitem>
7179 7179 <listitem>
7180 7180 <para>
7181   - New option <option>--remove-page-labels</option> will remove page
  7181 + New option @1@option@1@--remove-page-labels@2@option@2@ will remove page
7182 7182 labels before generating output. This used to happen if you
7183   - ran <command>qpdf --empty --pages .. --</command>, but the
  7183 + ran @1@command@1@qpdf --empty --pages .. --@2@command@2@, but the
7184 7184 behavior changed in qpdf 8.3.0. This option enables people
7185 7185 who were relying on the old behavior to get it again.
7186 7186 </para>
... ... @@ -7188,7 +7188,7 @@ print &quot;\n&quot;;
7188 7188 <listitem>
7189 7189 <para>
7190 7190 New option
7191   - <option>--keep-files-open-threshold=<replaceable>count</replaceable></option>
  7191 + @1@option@1@--keep-files-open-threshold=@1@replaceable@1@count@2@replaceable@2@@2@option@2@
7192 7192 can be used to override number of files that qpdf will use
7193 7193 to trigger the behavior of not keeping all files open when
7194 7194 merging files. This may be necessary if your system allows
... ... @@ -7222,7 +7222,7 @@ print &quot;\n&quot;;
7222 7222 <listitem>
7223 7223 <para>
7224 7224 Revert change that included preservation of outlines
7225   - (bookmarks) in <option>--split-pages</option>. The way it
  7225 + (bookmarks) in @1@option@1@--split-pages@2@option@2@. The way it
7226 7226 was implemented in 8.3.0 and 8.4.0 caused a very significant
7227 7227 degradation of performance for splitting certain files. A
7228 7228 future release of qpdf may re-introduce the behavior in a
... ... @@ -7305,20 +7305,20 @@ print &quot;\n&quot;;
7305 7305 </listitem>
7306 7306 <listitem>
7307 7307 <para>
7308   - New options <option>--externalize-inline-images</option>,
7309   - <option>--ii-min-bytes</option>, and
7310   - <option>--keep-inline-images</option> control qpdf's
  7308 + New options @1@option@1@--externalize-inline-images@2@option@2@,
  7309 + @1@option@1@--ii-min-bytes@2@option@2@, and
  7310 + @1@option@1@--keep-inline-images@2@option@2@ control qpdf's
7311 7311 handling of inline images and possible conversion of them to
7312 7312 regular images. By default,
7313   - <option>--optimize-images</option> now also applies to
  7313 + @1@option@1@--optimize-images@2@option@2@ now also applies to
7314 7314 inline images. These options are discussed in <xref
7315 7315 linkend="ref.advanced-transformation"/>.
7316 7316 </para>
7317 7317 </listitem>
7318 7318 <listitem>
7319 7319 <para>
7320   - Add options <option>--overlay</option> and
7321   - <option>--underlay</option> for overlaying or underlaying
  7320 + Add options @1@option@1@--overlay@2@option@2@ and
  7321 + @1@option@1@--underlay@2@option@2@ for overlaying or underlaying
7322 7322 pages of other files onto output pages. See <xref
7323 7323 linkend="ref.overlay-underlay"/> for details.
7324 7324 </para>
... ... @@ -7330,14 +7330,14 @@ print &quot;\n&quot;;
7330 7330 any non-ASCII characters, qpdf will try a number of
7331 7331 alternative passwords to try to compensate for possible
7332 7332 character encoding errors. This behavior can be suppressed
7333   - with the <option>--suppress-password-recovery</option>
  7333 + with the @1@option@1@--suppress-password-recovery@2@option@2@
7334 7334 option. See <xref linkend="ref.unicode-passwords"/> for a
7335 7335 full discussion.
7336 7336 </para>
7337 7337 </listitem>
7338 7338 <listitem>
7339 7339 <para>
7340   - Add the <option>--password-mode</option> option to fine-tune
  7340 + Add the @1@option@1@--password-mode@2@option@2@ option to fine-tune
7341 7341 how qpdf interprets password arguments, especially when they
7342 7342 contain non-ASCII characters. See <xref
7343 7343 linkend="ref.unicode-passwords"/> for more information.
... ... @@ -7345,7 +7345,7 @@ print &quot;\n&quot;;
7345 7345 </listitem>
7346 7346 <listitem>
7347 7347 <para>
7348   - In the <option>--pages</option> option, it is now possible
  7348 + In the @1@option@1@--pages@2@option@2@ option, it is now possible
7349 7349 to copy the same page more than once from the same file
7350 7350 without using the previous workaround of specifying two
7351 7351 different paths to the same file.
... ... @@ -7353,21 +7353,21 @@ print &quot;\n&quot;;
7353 7353 </listitem>
7354 7354 <listitem>
7355 7355 <para>
7356   - In the <option>--pages</option> option, allow use of
  7356 + In the @1@option@1@--pages@2@option@2@ option, allow use of
7357 7357 &ldquo;.&rdquo; as a shortcut for the primary input file.
7358   - That way, you can do <command>qpdf in.pdf --pages . 1-2 --
7359   - out.pdf</command> instead of having to repeat
7360   - <filename>in.pdf</filename> in the command.
  7358 + That way, you can do @1@command@1@qpdf in.pdf --pages . 1-2 --
  7359 + out.pdf@2@command@2@ instead of having to repeat
  7360 + @1@filename@1@in.pdf@2@filename@2@ in the command.
7361 7361 </para>
7362 7362 </listitem>
7363 7363 <listitem>
7364 7364 <para>
7365 7365 When encrypting with 128-bit and 256-bit encryption, new
7366   - encryption options <option>--assemble</option>,
7367   - <option>--annotate</option>, <option>--form</option>, and
7368   - <option>--modify-other</option> allow more fine-grained
  7366 + encryption options @1@option@1@--assemble@2@option@2@,
  7367 + @1@option@1@--annotate@2@option@2@, @1@option@1@--form@2@option@2@, and
  7368 + @1@option@1@--modify-other@2@option@2@ allow more fine-grained
7369 7369 granularity in configuring options. Before, the
7370   - <option>--modify</option> option only configured certain
  7370 + @1@option@1@--modify@2@option@2@ option only configured certain
7371 7371 predefined groups of permissions.
7372 7372 </para>
7373 7373 </listitem>
... ... @@ -7387,7 +7387,7 @@ print &quot;\n&quot;;
7387 7387 resource lists across pages and if some but not all of the
7388 7388 pages in the output did not reference all the fonts and
7389 7389 images. Using the
7390   - <option>--preserve-unreferenced-resources</option> option
  7390 + @1@option@1@--preserve-unreferenced-resources@2@option@2@ option
7391 7391 would work around the incorrect behavior. This bug was the
7392 7392 result of a typo in the code and a deficiency in the test
7393 7393 suite. The case that triggered the error was known, just not
... ... @@ -7411,7 +7411,7 @@ print &quot;\n&quot;;
7411 7411 </listitem>
7412 7412 <listitem>
7413 7413 <para>
7414   - Using older option <option>--stream-data=compress</option>
  7414 + Using older option @1@option@1@--stream-data=compress@2@option@2@
7415 7415 with object streams, object streams and xref streams were
7416 7416 not compressed.
7417 7417 </para>
... ... @@ -7453,7 +7453,7 @@ print &quot;\n&quot;;
7453 7453 Add new versions of
7454 7454 <function>QPDFWriter::setR{3,4,5,6}EncryptionParameters</function>
7455 7455 that allow more granular setting of permissions bits. See
7456   - <filename>QPDFWriter.hh</filename> for details.
  7456 + @1@filename@1@QPDFWriter.hh@2@filename@2@ for details.
7457 7457 </para>
7458 7458 </listitem>
7459 7459 <listitem>
... ... @@ -7480,7 +7480,7 @@ print &quot;\n&quot;;
7480 7480 passed to
7481 7481 <function>QPDFPageDocumentHelper::addPage()</function> for
7482 7482 either the original <classname>QPDF</classname> object or a
7483   - different one. This is what the <command>qpdf</command>
  7483 + different one. This is what the @1@command@1@qpdf@2@command@2@
7484 7484 command-line tool uses to copy the same page multiple times
7485 7485 from the same file during splitting and merging operations.
7486 7486 </para>
... ... @@ -7506,7 +7506,7 @@ print &quot;\n&quot;;
7506 7506 immediately instead of lazily. This option uses more memory
7507 7507 but allows the source object to go out of scope before the
7508 7508 destination object is written in all cases. See comments in
7509   - <filename>QPDF.hh</filename> for details.
  7509 + @1@filename@1@QPDF.hh@2@filename@2@ for details.
7510 7510 </para>
7511 7511 </listitem>
7512 7512 <listitem>
... ... @@ -7568,7 +7568,7 @@ print &quot;\n&quot;;
7568 7568 <listitem>
7569 7569 <para>
7570 7570 Add new configure option
7571   - <option>--enable-avoid-windows-handle</option>, which causes
  7571 + @1@option@1@--enable-avoid-windows-handle@2@option@2@, which causes
7572 7572 the preprocessor symbol
7573 7573 <literal>AVOID_WINDOWS_HANDLE</literal> to be defined. When
7574 7574 defined, qpdf will avoid referencing the Windows
... ... @@ -7585,7 +7585,7 @@ print &quot;\n&quot;;
7585 7585 defined. If you do your own builds with other compilers, you
7586 7586 can define this symbol to cause <function>wmain</function>
7587 7587 to be used. This is needed to allow the Windows
7588   - <command>qpdf</command> command to receive Unicode
  7588 + @1@command@1@qpdf@2@command@2@ command to receive Unicode
7589 7589 command-line options.
7590 7590 </para>
7591 7591 </listitem>
... ... @@ -7605,9 +7605,9 @@ print &quot;\n&quot;;
7605 7605 <itemizedlist>
7606 7606 <listitem>
7607 7607 <para>
7608   - Shell completion: you can now use eval <command>$(qpdf
7609   - --completion-bash)</command> and eval <command>$(qpdf
7610   - --completion-zsh)</command> to enable shell completion for
  7608 + Shell completion: you can now use eval @1@command@1@$(qpdf
  7609 + --completion-bash)@2@command@2@ and eval @1@command@1@$(qpdf
  7610 + --completion-zsh)@2@command@2@ to enable shell completion for
7611 7611 bash and zsh.
7612 7612 </para>
7613 7613 </listitem>
... ... @@ -7615,14 +7615,14 @@ print &quot;\n&quot;;
7615 7615 <para>
7616 7616 Page numbers (also known as page labels) are now preserved
7617 7617 when merging and splitting files with the
7618   - <option>--pages</option> and <option>--split-pages</option>
  7618 + @1@option@1@--pages@2@option@2@ and @1@option@1@--split-pages@2@option@2@
7619 7619 options.
7620 7620 </para>
7621 7621 </listitem>
7622 7622 <listitem>
7623 7623 <para>
7624 7624 Bookmarks are partially preserved when splitting pages with
7625   - the <option>--split-pages</option> option. Specifically, the
  7625 + the @1@option@1@--split-pages@2@option@2@ option. Specifically, the
7626 7626 outlines dictionary and some supporting metadata are copied
7627 7627 into the split files. The result is that all bookmarks from
7628 7628 the original file appear, those that point to pages that are
... ... @@ -7634,8 +7634,8 @@ print &quot;\n&quot;;
7634 7634 </listitem>
7635 7635 <listitem>
7636 7636 <para>
7637   - Page collation: add new option <option>--collate</option>.
7638   - When specified, the semantics of <option>--pages</option>
  7637 + Page collation: add new option @1@option@1@--collate@2@option@2@.
  7638 + When specified, the semantics of @1@option@1@--pages@2@option@2@
7639 7639 change from concatenation to collation. See <xref
7640 7640 linkend="ref.page-selection"/> for examples and discussion.
7641 7641 </para>
... ... @@ -7644,17 +7644,17 @@ print &quot;\n&quot;;
7644 7644 <para>
7645 7645 Generation of information in JSON format, primarily to
7646 7646 facilitate use of qpdf from languages other than C++. Add
7647   - new options <option>--json</option>,
7648   - <option>--json-key</option>, and
7649   - <option>--json-object</option> to generate a JSON
7650   - representation of the PDF file. Run <command>qpdf
7651   - --json-help</command> to get a description of the JSON
  7647 + new options @1@option@1@--json@2@option@2@,
  7648 + @1@option@1@--json-key@2@option@2@, and
  7649 + @1@option@1@--json-object@2@option@2@ to generate a JSON
  7650 + representation of the PDF file. Run @1@command@1@qpdf
  7651 + --json-help@2@command@2@ to get a description of the JSON
7652 7652 format. For more information, see <xref linkend="ref.json"/>.
7653 7653 </para>
7654 7654 </listitem>
7655 7655 <listitem>
7656 7656 <para>
7657   - The <option>--generate-appearances</option> flag will cause
  7657 + The @1@option@1@--generate-appearances@2@option@2@ flag will cause
7658 7658 qpdf to generate appearances for form fields if the PDF file
7659 7659 indicates that form field appearances are out of date. This
7660 7660 can happen when PDF forms are filled in by a program that
... ... @@ -7664,14 +7664,14 @@ print &quot;\n&quot;;
7664 7664 </listitem>
7665 7665 <listitem>
7666 7666 <para>
7667   - The <option>--flatten-annotations</option> flag can be used
  7667 + The @1@option@1@--flatten-annotations@2@option@2@ flag can be used
7668 7668 to <emphasis>flatten</emphasis> annotations, including form
7669 7669 fields. Ordinarily, annotations are drawn separately from
7670 7670 the page. Flattening annotations is the process of combining
7671 7671 their appearances into the page's contents. You might want
7672 7672 to do this if you are going to rotate or combine pages using
7673 7673 a tool that doesn't understand about annotations. You may
7674   - also want to use <option>--generate-appearances</option>
  7674 + also want to use @1@option@1@--generate-appearances@2@option@2@
7675 7675 when using this flag since annotations for outdated form
7676 7676 fields are not flattened as that would cause loss of
7677 7677 information.
... ... @@ -7679,13 +7679,13 @@ print &quot;\n&quot;;
7679 7679 </listitem>
7680 7680 <listitem>
7681 7681 <para>
7682   - The <option>--optimize-images</option> flag tells qpdf to
  7682 + The @1@option@1@--optimize-images@2@option@2@ flag tells qpdf to
7683 7683 recompresses every image using DCT (JPEG) compression as
7684 7684 long as the image is not already compressed with lossy
7685 7685 compression and recompressing the image reduces its size.
7686   - The additional options <option>--oi-min-width</option>,
7687   - <option>--oi-min-height</option>, and
7688   - <option>--oi-min-area</option> prevent recompression of
  7686 + The additional options @1@option@1@--oi-min-width@2@option@2@,
  7687 + @1@option@1@--oi-min-height@2@option@2@, and
  7688 + @1@option@1@--oi-min-area@2@option@2@ prevent recompression of
7689 7689 images whose width, height, or pixel area
7690 7690 (width&nbsp;&#xd7;&nbsp;height) are below a specified
7691 7691 threshold.
... ... @@ -7693,8 +7693,8 @@ print &quot;\n&quot;;
7693 7693 </listitem>
7694 7694 <listitem>
7695 7695 <para>
7696   - The <option>--show-object</option> option can now be given
7697   - as <option>--show-object=trailer</option> to show the
  7696 + The @1@option@1@--show-object@2@option@2@ option can now be given
  7697 + as @1@option@1@--show-object=trailer@2@option@2@ to show the
7698 7698 trailer dictionary.
7699 7699 </para>
7700 7700 </listitem>
... ... @@ -7735,11 +7735,11 @@ print &quot;\n&quot;;
7735 7735 <listitem>
7736 7736 <para>
7737 7737 Ordinarily qpdf treats an argument of the form
7738   - <option>@file</option> to mean that command-line options
7739   - should be read from <filename>file</filename>. Now, if
7740   - <filename>file</filename> does not exist but
7741   - <filename>@file</filename> does, qpdf will treat
7742   - <filename>@file</filename> as a regular option. This makes
  7738 + @1@option@1@@file@2@option@2@ to mean that command-line options
  7739 + should be read from @1@filename@1@file@2@filename@2@. Now, if
  7740 + @1@filename@1@file@2@filename@2@ does not exist but
  7741 + @1@filename@1@@file@2@filename@2@ does, qpdf will treat
  7742 + @1@filename@1@@file@2@filename@2@ as a regular option. This makes
7743 7743 it possible to work more easily with PDF files whose names
7744 7744 happen to start with the <literal>@</literal> character.
7745 7745 </para>
... ... @@ -7761,7 +7761,7 @@ print &quot;\n&quot;;
7761 7761 using a QPDFObjectHandle::StreamDataProvider. For a more
7762 7762 in-depth discussion, see comments around
7763 7763 <function>copyForeignObject</function> in
7764   - <filename>QPDF.hh</filename>.
  7764 + @1@filename@1@QPDF.hh@2@filename@2@.
7765 7765 </para>
7766 7766 </listitem>
7767 7767 <listitem>
... ... @@ -7770,7 +7770,7 @@ print &quot;\n&quot;;
7770 7770 <function>QPDFWriter::getFinalVersion()</function>, which
7771 7771 returns the PDF version that will ultimately be written to
7772 7772 the final file. See comments in
7773   - <filename>QPDFWriter.hh</filename> for some restrictions on
  7773 + @1@filename@1@QPDFWriter.hh@2@filename@2@ for some restrictions on
7774 7774 its use.
7775 7775 </para>
7776 7776 </listitem>
... ... @@ -7793,7 +7793,7 @@ print &quot;\n&quot;;
7793 7793 <classname>QPDFAnnotationObjectHelper</classname> and
7794 7794 <classname>QPDFFormFieldObjectHelper</classname> for
7795 7795 querying flags and interpretation of different field types.
7796   - Define constants in <filename>qpdf/Constants.h</filename> to
  7796 + Define constants in @1@filename@1@qpdf/Constants.h@2@filename@2@ to
7797 7797 help with interpretation of flag values.
7798 7798 </para>
7799 7799 </listitem>
... ... @@ -7804,7 +7804,7 @@ print &quot;\n&quot;;
7804 7804 and
7805 7805 <function>QPDFFormFieldObjectHelper::generateAppearance</function>
7806 7806 for generating appearance streams. See discussion in
7807   - <filename>QPDFFormFieldObjectHelper.hh</filename> for
  7807 + @1@filename@1@QPDFFormFieldObjectHelper.hh@2@filename@2@ for
7808 7808 limitations.
7809 7809 </para>
7810 7810 </listitem>
... ... @@ -7885,11 +7885,11 @@ print &quot;\n&quot;;
7885 7885 <listitem>
7886 7886 <para>
7887 7887 It is no longer necessary to run
7888   - <command>autogen.sh</command> to build from a pristine
  7888 + @1@command@1@autogen.sh@2@command@2@ to build from a pristine
7889 7889 checkout. Automatically generated files are now committed so
7890 7890 that it is possible to build on platforms without autoconf
7891 7891 directly from a clean checkout of the repository. The
7892   - <command>configure</command> script detects if the files are
  7892 + @1@command@1@configure@2@command@2@ script detects if the files are
7893 7893 out of date when it also determines that the tools are
7894 7894 present to regenerate them.
7895 7895 </para>
... ... @@ -7924,8 +7924,8 @@ print &quot;\n&quot;;
7924 7924 If your packaging system automatically refreshes libtool or
7925 7925 autoconf files, it could cause this check to fail. To avoid
7926 7926 this problem, pass
7927   - <option>--disable-check-autofiles</option> to
7928   - <command>configure</command>.
  7927 + @1@option@1@--disable-check-autofiles@2@option@2@ to
  7928 + @1@command@1@configure@2@command@2@.
7929 7929 </para>
7930 7930 </listitem>
7931 7931 <listitem>
... ... @@ -7934,7 +7934,7 @@ print &quot;\n&quot;;
7934 7934 automatically, you can install completion files in the
7935 7935 distribution's default location. You can find sample
7936 7936 completion files to install in the
7937   - <filename>completions</filename> directory.
  7937 + @1@filename@1@completions@2@filename@2@ directory.
7938 7938 </para>
7939 7939 </listitem>
7940 7940 </itemizedlist>
... ... @@ -7954,10 +7954,10 @@ print &quot;\n&quot;;
7954 7954 <listitem>
7955 7955 <para>
7956 7956 Add
7957   - <option>--keep-files-open=<replaceable>[yn]</replaceable></option>
  7957 + @1@option@1@--keep-files-open=@1@replaceable@1@[yn]@2@replaceable@2@@2@option@2@
7958 7958 to override default determination of whether to keep files
7959 7959 open when merging. Please see the discussion of
7960   - <option>--keep-files-open</option> in <xref
  7960 + @1@option@1@--keep-files-open@2@option@2@ in <xref
7961 7961 linkend="ref.basic-options"/> for additional details.
7962 7962 </para>
7963 7963 </listitem>
... ... @@ -7977,7 +7977,7 @@ print &quot;\n&quot;;
7977 7977 <itemizedlist>
7978 7978 <listitem>
7979 7979 <para>
7980   - Add <option>--no-warn</option> option to suppress issuing
  7980 + Add @1@option@1@--no-warn@2@option@2@ option to suppress issuing
7981 7981 warning messages. If there are any conditions that would
7982 7982 have caused warnings to be issued, the exit status is still
7983 7983 3.
... ... @@ -8014,7 +8014,7 @@ print &quot;\n&quot;;
8014 8014 </listitem>
8015 8015 <listitem>
8016 8016 <para>
8017   - Bug fix: using <option>--progress</option> on very small
  8017 + Bug fix: using @1@option@1@--progress@2@option@2@ on very small
8018 8018 files could cause an infinite loop.
8019 8019 </para>
8020 8020 </listitem>
... ... @@ -8053,8 +8053,8 @@ print &quot;\n&quot;;
8053 8053 <listitem>
8054 8054 <para>
8055 8055 For the mingw builds, change the name of the DLL import
8056   - library from <filename>libqpdf.a</filename> to
8057   - <filename>libqpdf.dll.a</filename> to more accurately
  8056 + library from @1@filename@1@libqpdf.a@2@filename@2@ to
  8057 + @1@filename@1@libqpdf.dll.a@2@filename@2@ to more accurately
8058 8058 reflect that it is an import library rather than a static
8059 8059 library. This potentially clears the way for supporting a
8060 8060 static library in the future, though presently, the qpdf
... ... @@ -8089,7 +8089,7 @@ print &quot;\n&quot;;
8089 8089 unlikely event that the old behavior should be desired, or
8090 8090 if you have a case where page splitting is very slow, the
8091 8091 old behavior (and speed) can be enabled by specifying
8092   - <option>--preserve-unreferenced-resources</option>. For
  8092 + @1@option@1@--preserve-unreferenced-resources@2@option@2@. For
8093 8093 additional details, please see <xref
8094 8094 linkend="ref.advanced-transformation"/>.
8095 8095 </para>
... ... @@ -8104,9 +8104,9 @@ print &quot;\n&quot;;
8104 8104 </listitem>
8105 8105 <listitem>
8106 8106 <para>
8107   - The <option>--rotate</option> option's syntax has been
  8107 + The @1@option@1@--rotate@2@option@2@ option's syntax has been
8108 8108 extended to make the page range optional. If you specify
8109   - <option>--rotate=<replaceable>angle</replaceable></option>
  8109 + @1@option@1@--rotate=@1@replaceable@1@angle@2@replaceable@2@@2@option@2@
8110 8110 without specifying a page range, the rotation will be
8111 8111 applied to all pages. This can be especially useful for
8112 8112 adjusting a PDF created from a multi-page document that
... ... @@ -8115,14 +8115,14 @@ print &quot;\n&quot;;
8115 8115 </listitem>
8116 8116 <listitem>
8117 8117 <para>
8118   - When merging multiple files, the <option>--verbose</option>
  8118 + When merging multiple files, the @1@option@1@--verbose@2@option@2@
8119 8119 option now prints information about each file as it operates
8120 8120 on that file.
8121 8121 </para>
8122 8122 </listitem>
8123 8123 <listitem>
8124 8124 <para>
8125   - When the <option>--progress</option> option is specified,
  8125 + When the @1@option@1@--progress@2@option@2@ option is specified,
8126 8126 qpdf will print a running indicator of its best guess at how
8127 8127 far through the writing process it is. Note that, as with
8128 8128 all progress meters, it's an approximation. This option is
... ... @@ -8190,7 +8190,7 @@ print &quot;\n&quot;;
8190 8190 <classname>QPDFObjectHandle</classname> and
8191 8191 <classname>QPDF</classname> directly. Comments in the header
8192 8192 files direct you to the new interfaces. Please see the
8193   - header files and <filename>ChangeLog</filename> for
  8193 + header files and @1@filename@1@ChangeLog@2@filename@2@ for
8194 8194 additional details.
8195 8195 </para>
8196 8196 </listitem>
... ... @@ -8208,7 +8208,7 @@ print &quot;\n&quot;;
8208 8208 <listitem>
8209 8209 <para>
8210 8210 A new example program
8211   - <filename>examples/pdf-set-form-values.cc</filename> has
  8211 + @1@filename@1@examples/pdf-set-form-values.cc@2@filename@2@ has
8212 8212 been added that illustrates use of the new document and
8213 8213 object helpers.
8214 8214 </para>
... ... @@ -8222,8 +8222,8 @@ print &quot;\n&quot;;
8222 8222 to update your idea of the percentage it thinks it is
8223 8223 through writing its output. Client programs can use this to
8224 8224 implement reasonably accurate progress meters. The
8225   - <command>qpdf</command> command line tool uses this to
8226   - implement its <option>--progress</option> option.
  8225 + @1@command@1@qpdf@2@command@2@ command line tool uses this to
  8226 + implement its @1@option@1@--progress@2@option@2@ option.
8227 8227 </para>
8228 8228 </listitem>
8229 8229 <listitem>
... ... @@ -8344,7 +8344,7 @@ print &quot;\n&quot;;
8344 8344 </listitem>
8345 8345 <listitem>
8346 8346 <para>
8347   - Enhancements to the <command>qpdf</command> Command-line Tool.
  8347 + Enhancements to the @1@command@1@qpdf@2@command@2@ Command-line Tool.
8348 8348 All new options listed here are documented in more detail in
8349 8349 <xref linkend="ref.using"/>.
8350 8350 </para>
... ... @@ -8352,13 +8352,13 @@ print &quot;\n&quot;;
8352 8352 <listitem>
8353 8353 <para>
8354 8354 The option
8355   - <option>--linearize-pass1=<replaceable>file</replaceable></option>
  8355 + @1@option@1@--linearize-pass1=@1@replaceable@1@file@2@replaceable@2@@2@option@2@
8356 8356 has been added for debugging qpdf's linearization code.
8357 8357 </para>
8358 8358 </listitem>
8359 8359 <listitem>
8360 8360 <para>
8361   - The option <option>--coalesce-contents</option> can be used
  8361 + The option @1@option@1@--coalesce-contents@2@option@2@ can be used
8362 8362 to combine content streams of a page whose contents are an
8363 8363 array of streams into a single stream.
8364 8364 </para>
... ... @@ -8376,14 +8376,14 @@ print &quot;\n&quot;;
8376 8376 <para>
8377 8377 Add function <function>qpdf_check_pdf</function> to the C API.
8378 8378 This function does basic checking that is a subset of what
8379   - <command>qpdf --check</command> performs.
  8379 + @1@command@1@qpdf --check@2@command@2@ performs.
8380 8380 </para>
8381 8381 </listitem>
8382 8382 <listitem>
8383 8383 <para>
8384 8384 Major enhancements to the lexical layer of qpdf. For a
8385 8385 complete list of enhancements, please refer to the
8386   - <filename>ChangeLog</filename> file. Most of the changes
  8386 + @1@filename@1@ChangeLog@2@filename@2@ file. Most of the changes
8387 8387 result in improvements to qpdf's ability handle erroneous
8388 8388 files. It is also possible for programs to handle
8389 8389 whitespace, comments, and inline images as tokens.
... ... @@ -8398,9 +8398,9 @@ print &quot;\n&quot;;
8398 8398 used with several different methods in
8399 8399 <classname>QPDFObjectHandle</classname> as well as with a
8400 8400 lower-level interface. See comments in
8401   - <filename>QPDFObjectHandle.hh</filename> as well as the new
8402   - examples <filename>examples/pdf-filter-tokens.cc</filename>
8403   - and <filename>examples/pdf-count-strings.cc</filename> for
  8401 + @1@filename@1@QPDFObjectHandle.hh@2@filename@2@ as well as the new
  8402 + examples @1@filename@1@examples/pdf-filter-tokens.cc@2@filename@2@
  8403 + and @1@filename@1@examples/pdf-count-strings.cc@2@filename@2@ for
8404 8404 details.
8405 8405 </para>
8406 8406 </listitem>
... ... @@ -8449,10 +8449,10 @@ print &quot;\n&quot;;
8449 8449 optionally display the encryption key used by a file. This is
8450 8450 a non-standard operation, but it can be useful in certain
8451 8451 situations. Please see the discussion of
8452   - <option>--password-is-hex-key</option> in <xref
  8452 + @1@option@1@--password-is-hex-key@2@option@2@ in <xref
8453 8453 linkend="ref.basic-options"/> or the comments around
8454 8454 <function>QPDF::setPasswordIsHexKey</function> in
8455   - <filename>QPDF.hh</filename> for additional details.
  8455 + @1@filename@1@QPDF.hh@2@filename@2@ for additional details.
8456 8456 </para>
8457 8457 </listitem>
8458 8458 <listitem>
... ... @@ -8530,8 +8530,8 @@ print &quot;\n&quot;;
8530 8530 JPEG or RunLength encoding. Library API enhancements and
8531 8531 command-line options have been added to control this
8532 8532 behavior. See command-line options
8533   - <option>--compress-streams</option> and
8534   - <option>--decode-level</option> and methods
  8533 + @1@option@1@--compress-streams@2@option@2@ and
  8534 + @1@option@1@--decode-level@2@option@2@ and methods
8535 8535 <function>QPDFWriter::setCompressStreams</function> and
8536 8536 <function>QPDFWriter::setDecodeLevel</function>.
8537 8537 </para>
... ... @@ -8567,7 +8567,7 @@ print &quot;\n&quot;;
8567 8567 <itemizedlist>
8568 8568 <listitem>
8569 8569 <para>
8570   - Enhancements to the <command>qpdf</command> Command-line Tool.
  8570 + Enhancements to the @1@command@1@qpdf@2@command@2@ Command-line Tool.
8571 8571 All new options listed here are documented in more detail in
8572 8572 <xref linkend="ref.using"/>.
8573 8573 </para>
... ... @@ -8582,12 +8582,12 @@ print &quot;\n&quot;;
8582 8582 </listitem>
8583 8583 <listitem>
8584 8584 <para>
8585   - <option>--rotate</option>: request page rotation
  8585 + @1@option@1@--rotate@2@option@2@: request page rotation
8586 8586 </para>
8587 8587 </listitem>
8588 8588 <listitem>
8589 8589 <para>
8590   - <option>--newline-before-endstream</option>: ensure that a
  8590 + @1@option@1@--newline-before-endstream@2@option@2@: ensure that a
8591 8591 newline appears before every <literal>endstream</literal>
8592 8592 keyword in the file; used to prevent qpdf from breaking
8593 8593 PDF/A compliance on already compliant files.
... ... @@ -8595,35 +8595,35 @@ print &quot;\n&quot;;
8595 8595 </listitem>
8596 8596 <listitem>
8597 8597 <para>
8598   - <option>--preserve-unreferenced</option>: preserve
  8598 + @1@option@1@--preserve-unreferenced@2@option@2@: preserve
8599 8599 unreferenced objects in the input PDF
8600 8600 </para>
8601 8601 </listitem>
8602 8602 <listitem>
8603 8603 <para>
8604   - <option>--split-pages</option>: break output into chunks
  8604 + @1@option@1@--split-pages@2@option@2@: break output into chunks
8605 8605 with fixed numbers of pages
8606 8606 </para>
8607 8607 </listitem>
8608 8608 <listitem>
8609 8609 <para>
8610   - <option>--verbose</option>: print the name of each output
  8610 + @1@option@1@--verbose@2@option@2@: print the name of each output
8611 8611 file that is created
8612 8612 </para>
8613 8613 </listitem>
8614 8614 <listitem>
8615 8615 <para>
8616   - <option>--compress-streams</option> and
8617   - <option>--decode-level</option> replace
8618   - <option>--stream-data</option> for improving granularity of
  8616 + @1@option@1@--compress-streams@2@option@2@ and
  8617 + @1@option@1@--decode-level@2@option@2@ replace
  8618 + @1@option@1@--stream-data@2@option@2@ for improving granularity of
8619 8619 controlling compression and decompression of stream data.
8620   - The <option>--stream-data</option> option will remain
  8620 + The @1@option@1@--stream-data@2@option@2@ option will remain
8621 8621 available.
8622 8622 </para>
8623 8623 </listitem>
8624 8624 <listitem>
8625 8625 <para>
8626   - When running <command>qpdf --check</command> with other
  8626 + When running @1@command@1@qpdf --check@2@command@2@ with other
8627 8627 options, checks are always run first. This enables qpdf to
8628 8628 perform its full recovery logic before outputting other
8629 8629 information. This can be especially useful when manually
... ... @@ -8633,9 +8633,9 @@ print &quot;\n&quot;;
8633 8633 </listitem>
8634 8634 <listitem>
8635 8635 <para>
8636   - Process <command>--pages</command> earlier so that other
8637   - options like <option>--show-pages</option> or
8638   - <option>--split-pages</option> can operate on the file after
  8636 + Process @1@command@1@--pages@2@command@2@ earlier so that other
  8637 + options like @1@option@1@--show-pages@2@option@2@ or
  8638 + @1@option@1@--split-pages@2@option@2@ can operate on the file after
8639 8639 page splitting/merging has occurred.
8640 8640 </para>
8641 8641 </listitem>
... ... @@ -8674,7 +8674,7 @@ print &quot;\n&quot;;
8674 8674 <classname>Pl_RunLength</classname> and
8675 8675 <classname>Pl_DCT</classname> are available for developers
8676 8676 who wish to produce or consume RunLength or DCT stream data
8677   - directly. The <filename>examples/pdf-create.cc</filename>
  8677 + directly. The @1@filename@1@examples/pdf-create.cc@2@filename@2@
8678 8678 example illustrates their use.
8679 8679 </para>
8680 8680 </listitem>
... ... @@ -8707,7 +8707,7 @@ print &quot;\n&quot;;
8707 8707 <itemizedlist>
8708 8708 <listitem>
8709 8709 <para>
8710   - Implement <option>--deterministic-id</option> command-line
  8710 + Implement @1@option@1@--deterministic-id@2@option@2@ command-line
8711 8711 option and <function>QPDFWriter::setDeterministicID</function>
8712 8712 as well as C API function
8713 8713 <function>qpdf_set_deterministic_ID</function> for generating
... ... @@ -8787,10 +8787,10 @@ print &quot;\n&quot;;
8787 8787 </listitem>
8788 8788 <listitem>
8789 8789 <para>
8790   - New example program: <command>pdf-split-pages</command>:
  8790 + New example program: @1@command@1@pdf-split-pages@2@command@2@:
8791 8791 efficiently split PDF files into individual pages. The example
8792   - program does this more efficiently than using <command>qpdf
8793   - --pages</command> to do it.
  8792 + program does this more efficiently than using @1@command@1@qpdf
  8793 + --pages@2@command@2@ to do it.
8794 8794 </para>
8795 8795 </listitem>
8796 8796 <listitem>
... ... @@ -8876,14 +8876,14 @@ print &quot;\n&quot;;
8876 8876 For the Windows build, this results in an added dependency on
8877 8877 Microsoft's cryptography API. To disable the OS-specific
8878 8878 cryptography and use the old version, pass the
8879   - <option>--enable-insecure-random</option> option to
8880   - <command>./configure</command>.
  8879 + @1@option@1@--enable-insecure-random@2@option@2@ option to
  8880 + @1@command@1@./configure@2@command@2@.
8881 8881 </para>
8882 8882 </listitem>
8883 8883 <listitem>
8884 8884 <para>
8885   - The <command>qpdf</command> command-line tool now issues a
8886   - warning when <option>-accessibility=n</option> is specified
  8885 + The @1@command@1@qpdf@2@command@2@ command-line tool now issues a
  8886 + warning when @1@option@1@-accessibility=n@2@option@2@ is specified
8887 8887 for newer encryption versions stating that the option is
8888 8888 ignored. qpdf, per the spec, has always ignored this flag,
8889 8889 but it previously did so silently. This warning is issued
... ... @@ -8922,21 +8922,21 @@ print &quot;\n&quot;;
8922 8922 <function>QPDFObjectHandle::getGeneration()</function> as it
8923 8923 makes it less likely for people to accidentally write code
8924 8924 that ignores the generation number. See
8925   - <filename>QPDF.hh</filename> and
8926   - <filename>QPDFObjectHandle.hh</filename> for additional notes.
  8925 + @1@filename@1@QPDF.hh@2@filename@2@ and
  8926 + @1@filename@1@QPDFObjectHandle.hh@2@filename@2@ for additional notes.
8927 8927 </para>
8928 8928 </listitem>
8929 8929 <listitem>
8930 8930 <para>
8931   - Add <option>--show-npages</option> command-line option to the
8932   - <command>qpdf</command> command to show the number of pages in
  8931 + Add @1@option@1@--show-npages@2@option@2@ command-line option to the
  8932 + @1@command@1@qpdf@2@command@2@ command to show the number of pages in
8933 8933 a file.
8934 8934 </para>
8935 8935 </listitem>
8936 8936 <listitem>
8937 8937 <para>
8938 8938 Allow omission of the page range within
8939   - <option>--pages</option> for the <command>qpdf</command>
  8939 + @1@option@1@--pages@2@option@2@ for the @1@command@1@qpdf@2@command@2@
8940 8940 command. When omitted, the page range is implicitly taken to
8941 8941 be all the pages in the file.
8942 8942 </para>
... ... @@ -8945,7 +8945,7 @@ print &quot;\n&quot;;
8945 8945 <para>
8946 8946 Various enhancements were made to support different types of
8947 8947 broken files or broken readers. Details can be found in
8948   - <filename>ChangeLog</filename>.
  8948 + @1@filename@1@ChangeLog@2@filename@2@.
8949 8949 </para>
8950 8950 </listitem>
8951 8951 </itemizedlist>
... ... @@ -8958,10 +8958,10 @@ print &quot;\n&quot;;
8958 8958 <listitem>
8959 8959 <para>
8960 8960 Note to people including qpdf in distributions: the
8961   - <filename>.la</filename> files generated by libtool are now
8962   - installed by qpdf's <command>make install</command> target.
  8961 + @1@filename@1@.la@2@filename@2@ files generated by libtool are now
  8962 + installed by qpdf's @1@command@1@make install@2@command@2@ target.
8963 8963 Before, they were not installed. This means that if your
8964   - distribution does not want to include <filename>.la</filename>
  8964 + distribution does not want to include @1@filename@1@.la@2@filename@2@
8965 8965 files, you must remove them as part of your packaging process.
8966 8966 </para>
8967 8967 </listitem>
... ... @@ -8976,7 +8976,7 @@ print &quot;\n&quot;;
8976 8976 <function>QPDFObjectHandle::parseContentStream</function>
8977 8977 method parses objects in a content stream and calls
8978 8978 handlers in a callback class. The example
8979   - <filename>examples/pdf-parse-content.cc</filename>
  8979 + @1@filename@1@examples/pdf-parse-content.cc@2@filename@2@
8980 8980 illustrates how this may be used.
8981 8981 </para>
8982 8982 </listitem>
... ... @@ -9004,7 +9004,7 @@ print &quot;\n&quot;;
9004 9004 </listitem>
9005 9005 <listitem>
9006 9006 <para>
9007   - <command>qpdf --check</command> now parses all pages' content
  9007 + @1@command@1@qpdf --check@2@command@2@ now parses all pages' content
9008 9008 streams in addition to doing other checks. While there are
9009 9009 still many types of errors that cannot be detected, syntactic
9010 9010 errors in content streams will now be reported.
... ... @@ -9019,12 +9019,12 @@ print &quot;\n&quot;;
9019 9019 <listitem>
9020 9020 <para>
9021 9021 Warning flags have been moved into a separate variable in
9022   - <filename>autoconf.mk</filename>
  9022 + @1@filename@1@autoconf.mk@2@filename@2@
9023 9023 </para>
9024 9024 </listitem>
9025 9025 <listitem>
9026 9026 <para>
9027   - The configure flag <option>--enable-werror</option> work
  9027 + The configure flag @1@option@1@--enable-werror@2@option@2@ work
9028 9028 for Microsoft compilers
9029 9029 </para>
9030 9030 </listitem>
... ... @@ -9052,7 +9052,7 @@ print &quot;\n&quot;;
9052 9052 converts numbers to strings. This is largely invisible to
9053 9053 users, but it does trigger a bug in some older versions of
9054 9054 mingw-w64's C++ library. See
9055   - <filename>README-windows.md</filename> in the source
  9055 + @1@filename@1@README-windows.md@2@filename@2@ in the source
9056 9056 distribution if you think this may affect you. The copy of
9057 9057 the DLL distributed with qpdf's binary distribution is not
9058 9058 affected by this problem.
... ... @@ -9084,7 +9084,7 @@ print &quot;\n&quot;;
9084 9084 <listitem>
9085 9085 <para>
9086 9086 Installation no longer uses GNU/Linux-specific versions of
9087   - some commands, so <command>make install</command> works on
  9087 + some commands, so @1@command@1@make install@2@command@2@ works on
9088 9088 Solaris with native tools.
9089 9089 </para>
9090 9090 </listitem>
... ... @@ -9112,7 +9112,7 @@ print &quot;\n&quot;;
9112 9112 </listitem>
9113 9113 <listitem>
9114 9114 <para>
9115   - Add clarifying comment in <filename>QPDF.hh</filename> to
  9115 + Add clarifying comment in @1@filename@1@QPDF.hh@2@filename@2@ to
9116 9116 methods that return the user password explaining that it is no
9117 9117 longer possible with newer encryption formats to recover the
9118 9118 user password knowing the owner password. In earlier
... ... @@ -9252,12 +9252,12 @@ print &quot;\n&quot;;
9252 9252 <listitem>
9253 9253 <para>
9254 9254 Removed the method <function>decodeStreams</function>.
9255   - This method was used by the <option>--check</option> option
9256   - of the <command>qpdf</command> command-line tool to force
  9255 + This method was used by the @1@option@1@--check@2@option@2@ option
  9256 + of the @1@command@1@qpdf@2@command@2@ command-line tool to force
9257 9257 all streams in the file to be decoded, but it also suffered
9258 9258 from the problem of opening otherwise unreferenced streams
9259 9259 and thus could report false positive. The
9260   - <option>--check</option> option now causes qpdf to go
  9260 + @1@option@1@--check@2@option@2@ option now causes qpdf to go
9261 9261 through all the motions of writing a new file based on the
9262 9262 original one, so it will always reference and check exactly
9263 9263 those parts of a file that any ordinary viewer would check.
... ... @@ -9289,9 +9289,9 @@ print &quot;\n&quot;;
9289 9289 </listitem>
9290 9290 <listitem>
9291 9291 <para>
9292   - Fix the <command>pkg-config</command> files to list zlib and
  9292 + Fix the @1@command@1@pkg-config@2@command@2@ files to list zlib and
9293 9293 pcre in <function>Requires.private</function> to better
9294   - support static linking using <command>pkg-config</command>.
  9294 + support static linking using @1@command@1@pkg-config@2@command@2@.
9295 9295 </para>
9296 9296 </listitem>
9297 9297 </itemizedlist>
... ... @@ -9328,7 +9328,7 @@ print &quot;\n&quot;;
9328 9328 <listitem>
9329 9329 <para>
9330 9330 Version 3.0.0 included addition of files for
9331   - <command>pkg-config</command>, but this was not mentioned in
  9331 + @1@command@1@pkg-config@2@command@2@, but this was not mentioned in
9332 9332 the release notes. The release notes for 3.0.0 were updated
9333 9333 to mention this.
9334 9334 </para>
... ... @@ -9385,13 +9385,13 @@ print &quot;\n&quot;;
9385 9385 <listitem>
9386 9386 <para>
9387 9387 Support for page selection (splitting and merging PDF files)
9388   - has been added to the <command>qpdf</command> command-line
  9388 + has been added to the @1@command@1@qpdf@2@command@2@ command-line
9389 9389 tool. See <xref linkend="ref.page-selection"/>.
9390 9390 </para>
9391 9391 </listitem>
9392 9392 <listitem>
9393 9393 <para>
9394   - Options have been added to the <command>qpdf</command>
  9394 + Options have been added to the @1@command@1@qpdf@2@command@2@
9395 9395 command-line tool for copying encryption parameters from
9396 9396 another file. See <xref linkend="ref.basic-options"/>.
9397 9397 </para>
... ... @@ -9434,7 +9434,7 @@ print &quot;\n&quot;;
9434 9434 <para>
9435 9435 The <function>QPDF::emptyPDF</function> can be used to allow
9436 9436 creation of PDF files from scratch. The example
9437   - <filename>examples/pdf-create.cc</filename> illustrates how it
  9437 + @1@filename@1@examples/pdf-create.cc@2@filename@2@ illustrates how it
9438 9438 can be used.
9439 9439 </para>
9440 9440 </listitem>
... ... @@ -9449,7 +9449,7 @@ print &quot;\n&quot;;
9449 9449 <para>
9450 9450 Many new convenience methods have been added to the library,
9451 9451 most in <classname>QPDFObjectHandle</classname>. See
9452   - <filename>ChangeLog</filename> for a full list.
  9452 + @1@filename@1@ChangeLog@2@filename@2@ for a full list.
9453 9453 </para>
9454 9454 </listitem>
9455 9455 <listitem>
... ... @@ -9457,14 +9457,14 @@ print &quot;\n&quot;;
9457 9457 When building on a platform that supports ELF shared libraries
9458 9458 (such as Linux), symbol versions are enabled by default. They
9459 9459 can be disabled by passing
9460   - <option>--disable-ld-version-script</option> to
9461   - <command>./configure</command>.
  9460 + @1@option@1@--disable-ld-version-script@2@option@2@ to
  9461 + @1@command@1@./configure@2@command@2@.
9462 9462 </para>
9463 9463 </listitem>
9464 9464 <listitem>
9465 9465 <para>
9466   - The file <filename>libqpdf.pc</filename> is now installed to
9467   - support <command>pkg-config</command>.
  9466 + The file @1@filename@1@libqpdf.pc@2@filename@2@ is now installed to
  9467 + support @1@command@1@pkg-config@2@command@2@.
9468 9468 </para>
9469 9469 </listitem>
9470 9470 <listitem>
... ... @@ -9473,26 +9473,26 @@ print &quot;\n&quot;;
9473 9473 not needed to verify a correct build or port of qpdf. They
9474 9474 are needed only when changing the actual PDF output generated
9475 9475 by qpdf. You should enable them if you are making deep
9476   - changes to qpdf itself. See <filename>README.md</filename> for
  9476 + changes to qpdf itself. See @1@filename@1@README.md@2@filename@2@ for
9477 9477 details.
9478 9478 </para>
9479 9479 </listitem>
9480 9480 <listitem>
9481 9481 <para>
9482 9482 Large file tests are off by default but can be turned on with
9483   - <command>./configure</command> or by setting an environment
  9483 + @1@command@1@./configure@2@command@2@ or by setting an environment
9484 9484 variable before running the test suite. See
9485   - <filename>README.md</filename> for details.
  9485 + @1@filename@1@README.md@2@filename@2@ for details.
9486 9486 </para>
9487 9487 </listitem>
9488 9488 <listitem>
9489 9489 <para>
9490 9490 When qpdf's test suite fails, failures are not printed to the
9491 9491 terminal anymore by default. Instead, find them in
9492   - <filename>build/qtest.log</filename>. For packagers who are
  9492 + @1@filename@1@build/qtest.log@2@filename@2@. For packagers who are
9493 9493 building with an autobuilder, you can add the
9494   - <option>--enable-show-failed-test-output</option> option to
9495   - <command>./configure</command> to restore the old behavior.
  9494 + @1@option@1@--enable-show-failed-test-output@2@option@2@ option to
  9495 + @1@command@1@./configure@2@command@2@ to restore the old behavior.
9496 9496 </para>
9497 9497 </listitem>
9498 9498 </itemizedlist>
... ... @@ -9664,7 +9664,7 @@ print &quot;\n&quot;;
9664 9664 way. Note that QPDF does not write to
9665 9665 <varname>std::cout</varname> (or the specified output stream)
9666 9666 except where explicitly mentioned in
9667   - <filename>QPDF.hh</filename>, and that the only use of the
  9667 + @1@filename@1@QPDF.hh@2@filename@2@, and that the only use of the
9668 9668 error stream is for warnings. Note also that output of
9669 9669 warnings is suppressed when
9670 9670 <literal>setSuppressWarnings(true)</literal> is called.
... ... @@ -9751,8 +9751,8 @@ print &quot;\n&quot;;
9751 9751 <listitem>
9752 9752 <para>
9753 9753 Provide two new examples:
9754   - <command>pdf-double-page-size</command> and
9755   - <command>pdf-invert-images</command> that illustrate the newly
  9754 + @1@command@1@pdf-double-page-size@2@command@2@ and
  9755 + @1@command@1@pdf-invert-images@2@command@2@ that illustrate the newly
9756 9756 added interfaces.
9757 9757 </para>
9758 9758 </listitem>
... ... @@ -9794,7 +9794,7 @@ print &quot;\n&quot;;
9794 9794 </listitem>
9795 9795 <listitem>
9796 9796 <para>
9797   - Since <command>qpdf --check</command> only performs limited
  9797 + Since @1@command@1@qpdf --check@2@command@2@ only performs limited
9798 9798 checks, clarify the output to make it clear that there still
9799 9799 may be errors that qpdf can't check. This should make it less
9800 9800 surprising to people when another PDF reader is unable to read
... ... @@ -9870,8 +9870,8 @@ print &quot;\n&quot;;
9870 9870 </para>
9871 9871 <para>
9872 9872 For programming to the C interface, please see the header file
9873   - <filename>qpdf/qpdf-c.h</filename> and the example
9874   - <filename>examples/pdf-linearize.c</filename>.
  9873 + @1@filename@1@qpdf/qpdf-c.h@2@filename@2@ and the example
  9874 + @1@filename@1@examples/pdf-linearize.c@2@filename@2@.
9875 9875 </para>
9876 9876 </listitem>
9877 9877 <listitem>
... ... @@ -9880,7 +9880,7 @@ print &quot;\n&quot;;
9880 9880 be downloaded from qpdf's download side. Žarko's Delphi
9881 9881 wrapper is released with the same licensing terms as qpdf
9882 9882 itself and comes with this disclaimer: &ldquo;Delphi wrapper
9883   - unit <filename>qpdf.pas</filename> created by Žarko Gajić
  9883 + unit @1@filename@1@qpdf.pas@2@filename@2@ created by Žarko Gajić
9884 9884 (<ulink
9885 9885 url="http://zarko-gajic.iz.hr/">http://zarko-gajic.iz.hr/</ulink>).
9886 9886 Use at your own risk and for whatever purpose you want. No
... ... @@ -9931,7 +9931,7 @@ print &quot;\n&quot;;
9931 9931 </listitem>
9932 9932 <listitem>
9933 9933 <para>
9934   - The <option>--check</option> option to <command>qpdf</command>
  9934 + The @1@option@1@--check@2@option@2@ option to @1@command@1@qpdf@2@command@2@
9935 9935 has been extended to include some additional information.
9936 9936 </para>
9937 9937 </listitem>
... ... @@ -10017,7 +10017,7 @@ print &quot;\n&quot;;
10017 10017 <listitem>
10018 10018 <para>
10019 10019 Update test suite to work properly with a
10020   - non-<command>bash</command> <filename>/bin/sh</filename> and
  10020 + non-@1@command@1@bash@2@command@2@ @1@filename@1@/bin/sh@2@filename@2@ and
10021 10021 with Perl 5.10. No changes were made to the actual qpdf
10022 10022 source code itself for this release.
10023 10023 </para>
... ... @@ -10034,7 +10034,7 @@ print &quot;\n&quot;;
10034 10034 No changes in functionality or interface. This release
10035 10035 includes fixes to the source code so that qpdf compiles
10036 10036 properly and passes its test suite on a broader range of
10037   - platforms. See <filename>ChangeLog</filename> in the source
  10037 + platforms. See @1@filename@1@ChangeLog@2@filename@2@ in the source
10038 10038 distribution for details.
10039 10039 </para>
10040 10040 </listitem>
... ... @@ -10075,7 +10075,7 @@ print &quot;\n&quot;;
10075 10075 favor of the now removed <classname>QEXC</classname> classes used
10076 10076 in previous versions. The <classname>QEXC</classname> exception
10077 10077 classes predated the addition of the
10078   - <filename>&lt;stdexcept&gt;</filename> header file to the C++
  10078 + @1@filename@1@&lt;stdexcept&gt;@2@filename@2@ header file to the C++
10079 10079 standard library. Most of the exceptions thrown by the qpdf
10080 10080 library itself are still of type <classname>QPDFExc</classname>
10081 10081 which is now derived from
... ... @@ -10092,7 +10092,7 @@ print &quot;\n&quot;;
10092 10092 interfaces for querying them. Among the fields is a numeric
10093 10093 error code that can help applications act differently on (a small
10094 10094 number of) different error conditions. See
10095   - <filename>QPDFExc.hh</filename> for details.
  10095 + @1@filename@1@QPDFExc.hh@2@filename@2@ for details.
10096 10096 </para>
10097 10097 </listitem>
10098 10098 <listitem>
... ... @@ -10132,7 +10132,7 @@ print &quot;\n&quot;;
10132 10132 The enumerated types that used to be nested in
10133 10133 <classname>QPDFWriter</classname> have moved to top-level
10134 10134 enumerated types and are now defined in the file
10135   - <filename>qpdf/Constants.h</filename>. This enables them to be
  10135 + @1@filename@1@qpdf/Constants.h@2@filename@2@. This enables them to be
10136 10136 shared by both the C and C++ interfaces.
10137 10137 </para>
10138 10138 </listitem>
... ...