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>

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>
Jay Berkenbilt
1 parent f721fed9
Showing 1 changed file with 743 additions and 743 deletions
manual/qpdf-manual.xml
@@ -107,8 +107,8 @@
   <title>Building and Installing QPDF</title>
   <para>
    This chapter describes how to build and install qpdf.  Please see
-   also the <filename>README.md</filename> and
-   <filename>INSTALL</filename> files in the source distribution.
+   also the @1@filename@1@README.md@2@filename@2@ and
+   @1@filename@1@INSTALL@2@filename@2@ files in the source distribution.
   </para>
   <sect1 id="ref.prerequisites">
    <title>System Requirements</title>
@@ -162,8 +162,8 @@
        url="http://www.gnu.org/software/diffutils/">http://www.gnu.org/software/diffutils/</ulink>
        is required to run the test suite.  Note that this is the
        version of diff present on virtually all GNU/Linux systems.
-       This is required because the test suite uses <command>diff
-       -u</command>.
+       This is required because the test suite uses @1@command@1@diff
+       -u@2@command@2@.
       </para>
      </listitem>
     </itemizedlist>
@@ -182,8 +182,8 @@
     contents of PDF files.  If you are making deep changes to the
     library that cause changes in the contents of the files that qpdf
     generates, then you should enable the image comparison tests.
-    Enable them by running <command>configure</command> with the
-    <option>--enable-test-compare-images</option> flag.  If you enable
+    Enable them by running @1@command@1@configure@2@command@2@ with the
+    @1@option@1@--enable-test-compare-images@2@option@2@ flag.  If you enable
     this, the following additional requirements are required by the
     test suite.  Note that in no case are these items required to use
     qpdf.
@@ -223,23 +223,23 @@
     <programlisting>./configure
 make
 </programlisting>
-    You can also run <command>make check</command> to run the test
-    suite and <command>make install</command> to install.  Please run
-    <command>./configure --help</command> for options on what can be
+    You can also run @1@command@1@make check@2@command@2@ to run the test
+    suite and @1@command@1@make install@2@command@2@ to install.  Please run
+    @1@command@1@./configure --help@2@command@2@ for options on what can be
     configured.  You can also set the value of
     <varname>DESTDIR</varname> during installation to install to a
     temporary location, as is common with many open source packages.
-    Please see also the <filename>README.md</filename> and
-    <filename>INSTALL</filename> files in the source distribution.
+    Please see also the @1@filename@1@README.md@2@filename@2@ and
+    @1@filename@1@INSTALL@2@filename@2@ files in the source distribution.
    </para>
    <para>
     Building on Windows is a little bit more complicated.  For
-    details, please see <filename>README-windows.md</filename> in the
+    details, please see @1@filename@1@README-windows.md@2@filename@2@ in the
     source distribution.  You can also download a binary distribution
     for Windows.  There is a port of qpdf to Visual C++ version 6 in
-    the <filename>contrib</filename> area generously contributed by
+    the @1@filename@1@contrib@2@filename@2@ area generously contributed by
     Jian Ma.  This is also discussed in more detail in
-    <filename>README-windows.md</filename>.
+    @1@filename@1@README-windows.md@2@filename@2@.
    </para>
    <para>
     While <type>wchar_t</type> is part of the C++ standard, qpdf uses
@@ -253,11 +253,11 @@ make
    </para>
    <para>
     There are some other things you can do with the build.  Although
-    qpdf uses <application>autoconf</application>, it does not use
-    <application>automake</application> but instead uses a
+    qpdf uses @1@application@1@autoconf@2@application@2@, it does not use
+    @1@application@1@automake@2@application@2@ but instead uses a
     hand-crafted non-recursive Makefile that requires gnu make.  If
     you're really interested, please read the comments in the
-    top-level <filename>Makefile</filename>.
+    top-level @1@filename@1@Makefile@2@filename@2@.
    </para>
   </sect1>
   <sect1 id="ref.crypto">
@@ -284,41 +284,41 @@ make
     <para>
      When building with qpdf's build system, crypto providers can be
      enabled at build time using various
-     <command>./configure</command> options. The default behavior is
-     for <command>./configure</command> to discover which crypto
+     @1@command@1@./configure@2@command@2@ options. The default behavior is
+     for @1@command@1@./configure@2@command@2@ to discover which crypto
      providers can be supported based on available external libraries,
      to build all available crypto providers, and to use an external
      provider as the default over the native one. This behavior can be
      changed with the following flags to
-     <command>./configure</command>:
+     @1@command@1@./configure@2@command@2@:
      <itemizedlist>
       <listitem>
        <para>
-        <option>--enable-crypto-<replaceable>x</replaceable></option>
-        (where <replaceable>x</replaceable> is a supported crypto
-        provider): enable the <replaceable>x</replaceable> crypto
+        @1@option@1@--enable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@
+        (where @1@replaceable@1@x@2@replaceable@2@ is a supported crypto
+        provider): enable the @1@replaceable@1@x@2@replaceable@2@ crypto
         provider, requiring any external dependencies it needs
        </para>
       </listitem>
       <listitem>
        <para>
-        <option>--disable-crypto-<replaceable>x</replaceable></option>:
-        disable the <replaceable>x</replaceable> provider, and do not
+        @1@option@1@--disable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@:
+        disable the @1@replaceable@1@x@2@replaceable@2@ provider, and do not
         link against its dependencies even if they are available
        </para>
       </listitem>
       <listitem>
        <para>
-        <option>--with-default-crypto=<replaceable>x</replaceable></option>:
-        make <replaceable>x</replaceable> the default provider even if
+        @1@option@1@--with-default-crypto=@1@replaceable@1@x@2@replaceable@2@@2@option@2@:
+        make @1@replaceable@1@x@2@replaceable@2@ the default provider even if
         a higher priority one is available
        </para>
       </listitem>
       <listitem>
        <para>
-        <option>--disable-implicit-crypto</option>: only build crypto
+        @1@option@1@--disable-implicit-crypto@2@option@2@: only build crypto
         providers that are explicitly requested with an
-        <option>--enable-crypto-<replaceable>x</replaceable></option>
+        @1@option@1@--enable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@
         option
        </para>
       </listitem>
@@ -327,19 +327,19 @@ make
     <para>
      For example, if you want to guarantee that the gnutls crypto
      provider is used and that the native provider is not built, you
-     could run <command>./configure --enable-crypto-gnutls
-     --disable-implicit-crypto</command>.
+     could run @1@command@1@./configure --enable-crypto-gnutls
+     --disable-implicit-crypto@2@command@2@.
     </para>
     <para>
      If you build qpdf using your own build system, in order for qpdf
      to work at all, you need to enable at least one crypto provider.
-     The file <filename>libqpdf/qpdf/qpdf-config.h.in</filename>
+     The file @1@filename@1@libqpdf/qpdf/qpdf-config.h.in@2@filename@2@
      provides macros <literal>DEFAULT_CRYPTO</literal>, whose value
      must be a string naming the default crypto provider, and various
      symbols starting with <literal>USE_CRYPTO_</literal>, at least
      one of which has to be enabled. Additionally, you must compile
      the source files that implement a crypto provider. To get a list
-     of those files, look at <filename>libqpdf/build.mk</filename>. If
+     of those files, look at @1@filename@1@libqpdf/build.mk@2@filename@2@. If
      you want to omit a particular crypto provider, as long as its
      <literal>USE_CRYPTO_</literal> symbol is undefined, you can
      completely ignore the source files that belong to a particular
@@ -354,16 +354,16 @@ make
      <literal>"native"</literal>. Then you must include the source
      files used in the native implementation, some of which were added
      or renamed from earlier versions, to your build, and you can
-     ignore <filename>QPDFCrypto_gnutls.cc</filename>. Always consult
-     <filename>libqpdf/build.mk</filename> to get the list of source
+     ignore @1@filename@1@QPDFCrypto_gnutls.cc@2@filename@2@. Always consult
+     @1@filename@1@libqpdf/build.mk@2@filename@2@ to get the list of source
      files you need to build.
     </para>
    </sect2>
    <sect2 id="ref.crypto.runtime">
     <title>Runtime Crypto Provider Selection</title>
     <para>
-     You can use the <option>--show-crypto</option> option to
-     <command>qpdf</command> to get a list of available crypto
+     You can use the @1@option@1@--show-crypto@2@option@2@ option to
+     @1@command@1@qpdf@2@command@2@ to get a list of available crypto
      providers. The default provider is always listed first, and the
      rest are listed in lexical order. Each crypto provider is listed
      on a line by itself with no other text, enabling the output of
@@ -390,7 +390,7 @@ make
      class derived from <classname>QPDFCryptoImpl</classname> and
      register it with <classname>QPDFCryptoProvider</classname>. For
      additional information, see comments in
-     <filename>include/qpdf/QPDFCryptoImpl.hh</filename>.
+     @1@filename@1@include/qpdf/QPDFCryptoImpl.hh@2@filename@2@.
     </para>
    </sect2>
    <sect2 id="ref.crypto.design">
@@ -502,8 +502,8 @@ make
      </listitem>
      <listitem>
       <para>
-       Passing <option>--enable-show-failed-test-output</option> to
-       <command>./configure</command> will cause any failed test
+       Passing @1@option@1@--enable-show-failed-test-output@2@option@2@ to
+       @1@command@1@./configure@2@command@2@ will cause any failed test
        output to be written to the console. This can be very useful
        for seeing test failures generated by autobuilders where you
        can't access qtest.log after the fact.
@@ -519,25 +519,25 @@ make
        automatic files after modifying their sources. If your
        packaging environment automatically refreshes automatic files,
        it can cause this check to fail. Suppress qpdf's checks by
-       passing <option>--disable-check-autofiles</option> to
-       <command>/.configure</command>. This is safe since qpdf's
-       <command>autogen.sh</command> just runs autotools in the normal
+       passing @1@option@1@--disable-check-autofiles@2@option@2@ to
+       @1@command@1@/.configure@2@command@2@. This is safe since qpdf's
+       @1@command@1@autogen.sh@2@command@2@ just runs autotools in the normal
        way.
       </para>
      </listitem>
      <listitem>
       <para>
-       QPDF's <command>make install</command> does not install
+       QPDF's @1@command@1@make install@2@command@2@ does not install
        completion files by default, but as a packager, it's good if
        you install them wherever your distribution expects such files
        to go. You can find completion files to install in the
-       <filename>completions</filename> directory.
+       @1@filename@1@completions@2@filename@2@ directory.
       </para>
      </listitem>
      <listitem>
       <para>
        Packagers are encouraged to install the source files from the
-       <filename>examples</filename> directory along with qpdf
+       @1@filename@1@examples@2@filename@2@ directory along with qpdf
        development packages.
       </para>
      </listitem>
@@ -556,45 +556,45 @@ make
    <para>
     When running qpdf, the basic invocation is as follows:
-    <programlisting><command>qpdf</command><option> [ <replaceable>options</replaceable> ] { <replaceable>infilename</replaceable> | <option>--empty</option> } [ <replaceable>page_selection_options</replaceable> ] <replaceable>outfilename</replaceable></option>
+    <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@
 </programlisting>
-    This converts PDF file <option>infilename</option> to PDF file
-    <option>outfilename</option>.  The output file is functionally
+    This converts PDF file @1@option@1@infilename@2@option@2@ to PDF file
+    @1@option@1@outfilename@2@option@2@.  The output file is functionally
     identical to the input file but may have been structurally
     reorganized.  Also, orphaned objects will be removed from the
     file.  Many transformations are available as controlled by the
-    options below.  In place of <option>infilename</option>, the
-    parameter <option>--empty</option> may be specified.  This causes
+    options below.  In place of @1@option@1@infilename@2@option@2@, the
+    parameter @1@option@1@--empty@2@option@2@ may be specified.  This causes
     qpdf to use a dummy input file that contains zero pages.  The only
-    normal use case for using <option>--empty</option> would be if you
+    normal use case for using @1@option@1@--empty@2@option@2@ would be if you
     were going to add pages from another source, as discussed in <xref
     linkend="ref.page-selection"/>.
    </para>
    <para>
-    If <option>@filename</option> appears as a word anywhere in the
+    If @1@option@1@@filename@2@option@2@ appears as a word anywhere in the
     command-line, it will be read line by line, and each line will be
     treated as a command-line argument. Leading and trailing
     whitespace is intentionally not removed from lines, which makes it
     possible to handle arguments that start or end with spaces. The
-    <option>@-</option> option allows arguments to be read from
+    @1@option@1@@-@2@option@2@ option allows arguments to be read from
     standard input. This allows qpdf to be invoked with an arbitrary
     number of arbitrarily long arguments. It is also very useful for
     avoiding having to pass passwords on the command line. Note that
-    the <option>@filename</option> can't appear in the middle of an
-    argument, so constructs such as <option>--arg=@option</option>
+    the @1@option@1@@filename@2@option@2@ can't appear in the middle of an
+    argument, so constructs such as @1@option@1@--arg=@option@2@option@2@
     will not work. You would have to include the argument and its
     options together in the arguments file.
    </para>
    <para>
-    <option>outfilename</option> does not have to be seekable, even
+    @1@option@1@outfilename@2@option@2@ does not have to be seekable, even
     when generating linearized files.  Specifying
-    &ldquo;<option>-</option>&rdquo; as <option>outfilename</option>
+    &ldquo;@1@option@1@-@2@option@2@&rdquo; as @1@option@1@outfilename@2@option@2@
     means to write to standard output. If you want to overwrite the
     input file with the output, use the option
-    <option>--replace-input</option> and omit the output file name.
+    @1@option@1@--replace-input@2@option@2@ and omit the output file name.
     You can't specify the same file as both the input and the output.
     If you do this, qpdf will tell you about the
-    <option>--replace-input</option> option.
+    @1@option@1@--replace-input@2@option@2@ option.
    </para>
    <para>
     Most options require an output file, but some testing or
@@ -603,14 +603,14 @@ make
    <sect2 id="ref.exit-status">
     <title>Exit Status</title>
     <para>
-     The exit status of <command>qpdf</command> may be interpreted as
+     The exit status of @1@command@1@qpdf@2@command@2@ may be interpreted as
      follows:
      <itemizedlist>
       <listitem>
        <para>
         <literal>0</literal>: no errors or warnings were found. The
         file may still have problems qpdf can't detect. If
-        <option>--warning-exit-0</option> was specified, exit status 0
+        @1@option@1@--warning-exit-0@2@option@2@ was specified, exit status 0
         is used even if there are warnings.
        </para>
       </listitem>
@@ -626,16 +626,16 @@ make
         able to recover from. In some cases, the resulting file may
         still be damaged. Note that qpdf still exits with status
         <literal>3</literal> if it finds warnings even when
-        <option>--no-warn</option> is specified. With
-        <option>--warning-exit-0</option>, warnings without errors
+        @1@option@1@--no-warn@2@option@2@ is specified. With
+        @1@option@1@--warning-exit-0@2@option@2@, warnings without errors
         exit with status 0 instead of 3.
        </para>
       </listitem>
      </itemizedlist>
-     Note that <command>qpdf</command> never exists with status
+     Note that @1@command@1@qpdf@2@command@2@ never exists with status
      <literal>1</literal>. If you get an exit status of
      <literal>1</literal>, it was something else, like the shell not
-     being able to find or execute <command>qpdf</command>.
+     being able to find or execute @1@command@1@qpdf@2@command@2@.
     </para>
    </sect2>
   </sect1>
@@ -644,9 +644,9 @@ make
    <para>
     Starting in qpdf version 8.3.0, qpdf provides its own completion
     support for zsh and bash. You can enable bash completion with
-    <command>eval $(qpdf --completion-bash)</command> and zsh
-    completion with <command>eval $(qpdf --completion-zsh)</command>.
-    If <command>qpdf</command> is not in your path, you should invoke
+    @1@command@1@eval $(qpdf --completion-bash)@2@command@2@ and zsh
+    completion with @1@command@1@eval $(qpdf --completion-zsh)@2@command@2@.
+    If @1@command@1@qpdf@2@command@2@ is not in your path, you should invoke
     it above with an absolute path. If you invoke it with a relative
     path, it will warn you, and the completion won't work if you're in
     a different directory.
@@ -667,7 +667,7 @@ make
     commonly needed transformations.
     <variablelist>
      <varlistentry>
-      <term><option>--help</option></term>
+      <term>@1@option@1@--help@2@option@2@</term>
       <listitem>
        <para>
         Display command-line invocation help.
@@ -675,7 +675,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--version</option></term>
+      <term>@1@option@1@--version@2@option@2@</term>
       <listitem>
        <para>
         Display the current version of qpdf.
@@ -683,7 +683,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--copyright</option></term>
+      <term>@1@option@1@--copyright@2@option@2@</term>
       <listitem>
        <para>
         Show detailed copyright information.
@@ -691,7 +691,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--show-crypto</option></term>
+      <term>@1@option@1@--show-crypto@2@option@2@</term>
       <listitem>
        <para>
         Show a list of available crypto providers, each on a line by
@@ -702,7 +702,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--completion-bash</option></term>
+      <term>@1@option@1@--completion-bash@2@option@2@</term>
       <listitem>
        <para>
         Output a completion command you can eval to enable shell
@@ -711,7 +711,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--completion-zsh</option></term>
+      <term>@1@option@1@--completion-zsh@2@option@2@</term>
       <listitem>
        <para>
         Output a completion command you can eval to enable shell
@@ -720,31 +720,31 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--password=<replaceable>password</replaceable></option></term>
+      <term>@1@option@1@--password=@1@replaceable@1@password@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         Specifies a password for accessing encrypted files. To read
         the password from a file or standard input, you can use
-        <option>--password-file</option>, added in qpdf 10.2. Note
-        that you can also use <option>@filename</option> or
-        <option>@-</option> as described above to put the password in
+        @1@option@1@--password-file@2@option@2@, added in qpdf 10.2. Note
+        that you can also use @1@option@1@@filename@2@option@2@ or
+        @1@option@1@@-@2@option@2@ as described above to put the password in
         a file or pass it via standard input, but you would do so by
         specifying the entire
-        <option>--password=<replaceable>password</replaceable></option>
+        @1@option@1@--password=@1@replaceable@1@password@2@replaceable@2@@2@option@2@
         option in the file. Syntax such as
-        <option>--password=@filename</option> won't work since
-        <option>@filename</option> is not recognized in the middle of
+        @1@option@1@--password=@filename@2@option@2@ won't work since
+        @1@option@1@@filename@2@option@2@ is not recognized in the middle of
         an argument.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--password-file=<replaceable>filename</replaceable></option></term>
+      <term>@1@option@1@--password-file=@1@replaceable@1@filename@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         Reads the first line from the specified file and uses it as
         the password for accessing encrypted files.
-        <option><replaceable>filename</replaceable></option> may be
+        @1@option@1@@1@replaceable@1@filename@2@replaceable@2@@2@option@2@ may be
         <literal>-</literal> to read the password from standard input.
         Note that, in this case, the password is echoed and there is
         no prompt, so use with caution.
@@ -752,21 +752,21 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--is-encrypted</option></term>
+      <term>@1@option@1@--is-encrypted@2@option@2@</term>
       <listitem>
        <para>
         Silently exit with status 0 if the file is encrypted or status
         2 if the file is not encrypted. This is useful for shell
         scripts. Other options are ignored if this is given. This
         option is mutually exclusive with
-        <option>--requires-password</option>. Both this option and
-        <option>--requires-password</option> exit with status 2 for
+        @1@option@1@--requires-password@2@option@2@. Both this option and
+        @1@option@1@--requires-password@2@option@2@ exit with status 2 for
         non-encrypted files.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--requires-password</option></term>
+      <term>@1@option@1@--requires-password@2@option@2@</term>
       <listitem>
        <para>
         Silently exit with status 0 if a password (other than as
@@ -775,18 +775,18 @@ make
         requires no password or the correct password has been
         supplied. This is useful for shell scripts. Note that any
         supplied password is used when opening the file. When used
-        with a <option>--password</option> option, this option can be
+        with a @1@option@1@--password@2@option@2@ option, this option can be
         used to check the correctness of the password. In that case,
         an exit status of 3 means the file works with the supplied
         password. This option is mutually exclusive with
-        <option>--is-encrypted</option>. Both this option and
-        <option>--is-encrypted</option> exit with status 2 for
+        @1@option@1@--is-encrypted@2@option@2@. Both this option and
+        @1@option@1@--is-encrypted@2@option@2@ exit with status 2 for
         non-encrypted files.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--verbose</option></term>
+      <term>@1@option@1@--verbose@2@option@2@</term>
       <listitem>
        <para>
         Increase verbosity of output. For now, this just prints some
@@ -795,7 +795,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--progress</option></term>
+      <term>@1@option@1@--progress@2@option@2@</term>
       <listitem>
        <para>
         Indicate progress while writing files.
@@ -803,29 +803,29 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--no-warn</option></term>
+      <term>@1@option@1@--no-warn@2@option@2@</term>
       <listitem>
        <para>
         Suppress writing of warnings to stderr. If warnings were
-        detected and suppressed, <command>qpdf</command> will still
+        detected and suppressed, @1@command@1@qpdf@2@command@2@ will still
         exit with exit code 3. See also
-        <option>--warning-exit-0</option>.
+        @1@option@1@--warning-exit-0@2@option@2@.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--warning-exit-0</option></term>
+      <term>@1@option@1@--warning-exit-0@2@option@2@</term>
       <listitem>
        <para>
         If warnings are found but no errors, exit with exit code 0
-        instead 3. When combined with <option>--no-warn</option>, the
-        effect is for <command>qpdf</command> to completely ignore
+        instead 3. When combined with @1@option@1@--no-warn@2@option@2@, the
+        effect is for @1@command@1@qpdf@2@command@2@ to completely ignore
         warnings.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--linearize</option></term>
+      <term>@1@option@1@--linearize@2@option@2@</term>
       <listitem>
        <para>
         Causes generation of a linearized (web-optimized) output file.
@@ -833,27 +833,27 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--replace-input</option></term>
+      <term>@1@option@1@--replace-input@2@option@2@</term>
       <listitem>
        <para>
         If specified, the output file name should be omitted. This
         option tells qpdf to replace the input file with the output.
         It does this by writing to
-        <filename><replaceable>infilename</replaceable>.~qpdf-temp#</filename>
+        @1@filename@1@@1@replaceable@1@infilename@2@replaceable@2@.~qpdf-temp#@2@filename@2@
         and, when done, overwriting the input file with the temporary
         file. If there were any warnings, the original input is saved
         as
-        <filename><replaceable>infilename</replaceable>.~qpdf-orig</filename>.
+        @1@filename@1@@1@replaceable@1@infilename@2@replaceable@2@.~qpdf-orig@2@filename@2@.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--copy-encryption=file</option></term>
+      <term>@1@option@1@--copy-encryption=file@2@option@2@</term>
       <listitem>
        <para>
         Encrypt the file using the same encryption parameters,
         including user and owner password, as the specified file.  Use
-        <option>--encryption-file-password</option> to specify a password
+        @1@option@1@--encryption-file-password@2@option@2@ to specify a password
         if one is needed to open this file.  Note that copying the
         encryption parameters from a file also copies the first half
         of <literal>/ID</literal> from the file since this is part of
@@ -862,10 +862,10 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--encryption-file-password=password</option></term>
+      <term>@1@option@1@--encryption-file-password=password@2@option@2@</term>
       <listitem>
        <para>
-        If the file specified with <option>--copy-encryption</option>
+        If the file specified with @1@option@1@--copy-encryption@2@option@2@
         requires a password, specify the password using this option.
         Note that only one of the user or owner password is required.
         Both passwords will be preserved since QPDF does not
@@ -876,7 +876,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--allow-weak-crypto</option></term>
+      <term>@1@option@1@--allow-weak-crypto@2@option@2@</term>
       <listitem>
        <para>
         Starting with version 10.4, qpdf issues warnings when
@@ -889,7 +889,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--encrypt options --</option></term>
+      <term>@1@option@1@--encrypt options --@2@option@2@</term>
       <listitem>
        <para>
         Causes generation an encrypted output file.  Please see <xref
@@ -899,7 +899,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--decrypt</option></term>
+      <term>@1@option@1@--decrypt@2@option@2@</term>
       <listitem>
        <para>
         Removes any encryption on the file.  A password must be
@@ -908,17 +908,17 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--password-is-hex-key</option></term>
+      <term>@1@option@1@--password-is-hex-key@2@option@2@</term>
       <listitem>
        <para>
         Overrides the usual computation/retrieval of the PDF file's
         encryption key from user/owner password with an explicit
         specification of the encryption key. When this option is
-        specified, the argument to the <option>--password</option>
+        specified, the argument to the @1@option@1@--password@2@option@2@
         option is interpreted as a hexadecimal-encoded key value. This
         only applies to the password used to open the main input file.
         It does not apply to other files opened by
-        <option>--pages</option> or other options or to files being
+        @1@option@1@--pages@2@option@2@ or other options or to files being
         written.
        </para>
        <para>
@@ -931,13 +931,13 @@ make
         heavily damaged, it may be possible to derive the encryption
         key and recover parts of the file using it directly. To expose
         the encryption key used by an encrypted file that you can open
-        normally, use the <option>--show-encryption-key</option>
+        normally, use the @1@option@1@--show-encryption-key@2@option@2@
         option.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--suppress-password-recovery</option></term>
+      <term>@1@option@1@--suppress-password-recovery@2@option@2@</term>
       <listitem>
        <para>
         Ordinarily, qpdf attempts to automatically compensate for
@@ -949,14 +949,14 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--password-mode=<replaceable>mode</replaceable></option></term>
+      <term>@1@option@1@--password-mode=@1@replaceable@1@mode@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         This option can be used to fine-tune how qpdf interprets
         Unicode (non-ASCII) password strings passed on the command
-        line. With the exception of the <option>hex-bytes</option>
+        line. With the exception of the @1@option@1@hex-bytes@2@option@2@
         mode, these only apply to passwords provided when encrypting
-        files. The <option>hex-bytes</option> mode also applies to
+        files. The @1@option@1@hex-bytes@2@option@2@ mode also applies to
         passwords specified for reading files. For additional
         discussion of the supported password modes and when you might
         want to use them, see <xref linkend="ref.unicode-passwords"/>.
@@ -964,7 +964,7 @@ make
         <itemizedlist>
          <listitem>
           <para>
-           <option>auto</option>: Automatically determine whether the
+           @1@option@1@auto@2@option@2@: Automatically determine whether the
            specified password is a properly encoded Unicode (UTF-8)
            string, and transcode it as required by the PDF spec based
            on the type encryption being applied. On Windows starting
@@ -975,22 +975,22 @@ make
          </listitem>
          <listitem>
           <para>
-           <option>unicode</option>: Tells qpdf that the incoming
+           @1@option@1@unicode@2@option@2@: Tells qpdf that the incoming
            password is UTF-8, overriding whatever its automatic
            detection determines. The only difference between this mode
-           and <option>auto</option> is that qpdf will fail with an
+           and @1@option@1@auto@2@option@2@ is that qpdf will fail with an
            error message if the password is not valid UTF-8 instead of
-           falling back to <option>bytes</option> mode with a warning.
+           falling back to @1@option@1@bytes@2@option@2@ mode with a warning.
           </para>
          </listitem>
          <listitem>
           <para>
-           <option>bytes</option>: Interpret the password as a literal
+           @1@option@1@bytes@2@option@2@: Interpret the password as a literal
            byte string. For non-Windows platforms, this is what
            versions of qpdf prior to 8.4.0 did. For Windows platforms,
            there is no way to specify strings of binary data on the
            command line directly, but you can use the
-           <option>@filename</option> option to do it, in which case
+           @1@option@1@@filename@2@option@2@ option to do it, in which case
            this option forces qpdf to respect the string of bytes as
            provided. This option will allow you to encrypt PDF files
            with passwords that will not be usable by other readers.
@@ -998,10 +998,10 @@ make
          </listitem>
          <listitem>
           <para>
-           <option>hex-bytes</option>: Interpret the password as a
+           @1@option@1@hex-bytes@2@option@2@: Interpret the password as a
            hex-encoded string. This provides a way to pass binary data
            as a password on all platforms including Windows. As with
-           <option>bytes</option>, this option may allow creation of
+           @1@option@1@bytes@2@option@2@, this option may allow creation of
            files that can't be opened by other readers. This mode
            affects qpdf's interpretation of passwords specified for
            decrypting files as well as for encrypting them. It makes
@@ -1014,33 +1014,33 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--rotate=[+|-]angle[:page-range]</option></term>
+      <term>@1@option@1@--rotate=[+|-]angle[:page-range]@2@option@2@</term>
       <listitem>
        <para>
         Apply rotation to specified pages. The
-        <option>page-range</option> portion of the option value has
+        @1@option@1@page-range@2@option@2@ portion of the option value has
         the same format as page ranges in <xref
         linkend="ref.page-selection"/>. If the page range is omitted,
         the rotation is applied to all pages. The
-        <option>angle</option> portion of the parameter may be either
-        0, 90, 180, or 270. If preceded by <option>+</option> or
-        <option>-</option>, the angle is added to or subtracted from
+        @1@option@1@angle@2@option@2@ portion of the parameter may be either
+        0, 90, 180, or 270. If preceded by @1@option@1@+@2@option@2@ or
+        @1@option@1@-@2@option@2@, the angle is added to or subtracted from
         the specified pages' original rotations. This is almost always
         what you want. Otherwise the pages' rotations are set to the
         exact value, which may cause the appearances of the pages to
         be inconsistent, especially for scans. For example, the
-        command <command>qpdf in.pdf out.pdf --rotate=+90:2,4,6
-        --rotate=180:7-8</command> would rotate pages 2, 4, and 6 90
+        command @1@command@1@qpdf in.pdf out.pdf --rotate=+90:2,4,6
+        --rotate=180:7-8@2@command@2@ would rotate pages 2, 4, and 6 90
         degrees clockwise from their original rotation and force the
         rotation of pages 7 through 8 to 180 degrees regardless of
-        their original rotation, and the command <command>qpdf in.pdf
-        out.pdf --rotate=+180</command> would rotate all pages by 180
+        their original rotation, and the command @1@command@1@qpdf in.pdf
+        out.pdf --rotate=+180@2@command@2@ would rotate all pages by 180
         degrees.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--keep-files-open=<replaceable>[yn]</replaceable></option></term>
+      <term>@1@option@1@--keep-files-open=@1@replaceable@1@[yn]@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         This option controls whether qpdf keeps individual files open
@@ -1056,33 +1056,33 @@ make
         with version 8.2.1, the default behavior is that files are
         kept open if no more than 200 files are specified, but that
         the behavior can be explicitly overridden with the
-        <option>--keep-files-open</option> flag. If you are merging
+        @1@option@1@--keep-files-open@2@option@2@ flag. If you are merging
         more than 200 files but less than the operating system's max
         open files limit, you may want to use
-        <option>--keep-files-open=y</option>, especially if working
+        @1@option@1@--keep-files-open=y@2@option@2@, especially if working
         over a networked file system. If you are using a local file
         system where the overhead is low and you might sometimes merge
         more than the OS limit's number of files from a script and are
         not worried about a few seconds additional processing time,
-        you may want to specify <option>--keep-files-open=n</option>.
+        you may want to specify @1@option@1@--keep-files-open=n@2@option@2@.
         The threshold for switching may be changed from the default
-        200 with the <option>--keep-files-open-threshold</option>
+        200 with the @1@option@1@--keep-files-open-threshold@2@option@2@
         option.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--keep-files-open-threshold=<replaceable>count</replaceable></option></term>
+      <term>@1@option@1@--keep-files-open-threshold=@1@replaceable@1@count@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         If specified, overrides the default value of 200 used as the
         threshold for qpdf deciding whether or not to keep files open.
-        See <option>--keep-files-open</option> for details.
+        See @1@option@1@--keep-files-open@2@option@2@ for details.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--pages options --</option></term>
+      <term>@1@option@1@--pages options --@2@option@2@</term>
       <listitem>
        <para>
         Select specific pages from one or more input files.  See <xref
@@ -1092,19 +1092,19 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--collate=<replaceable>n</replaceable></option></term>
+      <term>@1@option@1@--collate=@1@replaceable@1@n@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         When specified, collate rather than concatenate pages from
-        files specified with <option>--pages</option>. With a numeric
-        argument, collate in groups of <replaceable>n</replaceable>.
+        files specified with @1@option@1@--pages@2@option@2@. With a numeric
+        argument, collate in groups of @1@replaceable@1@n@2@replaceable@2@.
         The default is 1. See <xref linkend="ref.page-selection"/> for
         additional details.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--flatten-rotation</option></term>
+      <term>@1@option@1@--flatten-rotation@2@option@2@</term>
       <listitem>
        <para>
         For each page that is rotated using the
@@ -1117,11 +1117,11 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--split-pages=[n]</option></term>
+      <term>@1@option@1@--split-pages=[n]@2@option@2@</term>
       <listitem>
        <para>
-        Write each group of <option>n</option> pages to a separate
-        output file. If <option>n</option> is not specified, create
+        Write each group of @1@option@1@n@2@option@2@ pages to a separate
+        output file. If @1@option@1@n@2@option@2@ is not specified, create
         single pages. Output file names are generated as follows:
         <itemizedlist>
          <listitem>
@@ -1134,7 +1134,7 @@ make
          <listitem>
           <para>
            Otherwise, if the output file name ends in
-           <filename>.pdf</filename> (case insensitive), a zero-padded
+           @1@filename@1@.pdf@2@filename@2@ (case insensitive), a zero-padded
            page range, preceded by a dash, is inserted before the file
            extension.
           </para>
@@ -1150,29 +1150,29 @@ make
        <para>
         Page ranges are a single number in the case of single-page
         groups or two numbers separated by a dash otherwise.
-        For example, if <filename>infile.pdf</filename> has 12 pages
+        For example, if @1@filename@1@infile.pdf@2@filename@2@ has 12 pages
         <itemizedlist>
          <listitem>
           <para>
-           <command>qpdf --split-pages infile.pdf %d-out</command>
-           would generate files <filename>01-out</filename> through
-           <filename>12-out</filename>
+           @1@command@1@qpdf --split-pages infile.pdf %d-out@2@command@2@
+           would generate files @1@filename@1@01-out@2@filename@2@ through
+           @1@filename@1@12-out@2@filename@2@
           </para>
          </listitem>
          <listitem>
           <para>
-           <command>qpdf --split-pages=2 infile.pdf
-           outfile.pdf</command> would generate files
-           <filename>outfile-01-02.pdf</filename> through
-           <filename>outfile-11-12.pdf</filename>
+           @1@command@1@qpdf --split-pages=2 infile.pdf
+           outfile.pdf@2@command@2@ would generate files
+           @1@filename@1@outfile-01-02.pdf@2@filename@2@ through
+           @1@filename@1@outfile-11-12.pdf@2@filename@2@
           </para>
          </listitem>
          <listitem>
           <para>
-           <command>qpdf --split-pages infile.pdf
-           something.else</command> would generate files
-           <filename>something.else-01</filename> through
-           <filename>something.else-12</filename>
+           @1@command@1@qpdf --split-pages infile.pdf
+           something.else@2@command@2@ would generate files
+           @1@filename@1@something.else-01@2@filename@2@ through
+           @1@filename@1@something.else-12@2@filename@2@
           </para>
          </listitem>
         </itemizedlist>
@@ -1182,15 +1182,15 @@ make
         original PDF file are not preserved. For each page of output,
         this option creates an empty PDF and copies a single page from
         the output into it. If you require the global data, you will
-        have to run <command>qpdf</command> with the
-        <option>--pages</option> option once for each file. Using
-        <option>--split-pages</option> is much faster if you don't
+        have to run @1@command@1@qpdf@2@command@2@ with the
+        @1@option@1@--pages@2@option@2@ option once for each file. Using
+        @1@option@1@--split-pages@2@option@2@ is much faster if you don't
         require the global data.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--overlay options --</option></term>
+      <term>@1@option@1@--overlay options --@2@option@2@</term>
       <listitem>
        <para>
         Overlay pages from another file onto the output pages. See
@@ -1200,7 +1200,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--underlay options --</option></term>
+      <term>@1@option@1@--underlay options --@2@option@2@</term>
       <listitem>
        <para>
         Overlay pages from another file onto the output pages. See
@@ -1214,9 +1214,9 @@ make
    <para>
     Password-protected files may be opened by specifying a password.
     By default, qpdf will preserve any encryption data associated with
-    a file.  If <option>--decrypt</option> is specified, qpdf will
+    a file.  If @1@option@1@--decrypt@2@option@2@ is specified, qpdf will
     attempt to remove any encryption information.  If
-    <option>--encrypt</option> is specified, qpdf will replace the
+    @1@option@1@--encrypt@2@option@2@ is specified, qpdf will replace the
     document's encryption parameters with whatever is specified.
    </para>
    <para>
@@ -1234,7 +1234,7 @@ make
     the user. Starting in qpdf 8.4.0, qpdf does this automatically in
     most cases. For an in-depth discussion, please see <xref
     linkend="ref.unicode-passwords"/>. Previous versions of this
-    manual described workarounds using the <command>iconv</command>
+    manual described workarounds using the @1@command@1@iconv@2@command@2@
     command. Such workarounds are no longer required or recommended
     with qpdf 8.4.0. However, for backward compatibility, qpdf
     attempts to detect those workarounds and do the right thing in
@@ -1247,9 +1247,9 @@ make
     To change the encryption parameters of a file, use the --encrypt
     flag.  The syntax is
-    <programlisting><option>--encrypt <replaceable>user-password</replaceable> <replaceable>owner-password</replaceable> <replaceable>key-length</replaceable> [ <replaceable>restrictions</replaceable> ] --</option>
+    <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@
 </programlisting>
-    Note that &ldquo;<option>--</option>&rdquo; terminates parsing of
+    Note that &ldquo;@1@option@1@--@2@option@2@&rdquo; terminates parsing of
     encryption flags and must be present even if no restrictions are
     present.
    </para>
@@ -1259,22 +1259,22 @@ make
     allowing creation of PDF files with a non-empty user password, an
     empty owner password, and a 256-bit key since such files can be
     opened with no password. If you want to create such files, specify
-    the encryption option <option>--allow-insecure</option>, as
+    the encryption option @1@option@1@--allow-insecure@2@option@2@, as
     described below.
    </para>
    <para>
     The value for
-    <option><replaceable>key-length</replaceable></option> may be 40,
+    @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@ may be 40,
     128, or 256.  The restriction flags are dependent upon key length.
     When no additional restrictions are given, the default is to be
     fully permissive.
    </para>
    <para>
-    If <option><replaceable>key-length</replaceable></option> is 40,
+    If @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@ is 40,
     the following restriction options are available:
     <variablelist>
      <varlistentry>
-      <term><option>--print=[yn]</option></term>
+      <term>@1@option@1@--print=[yn]@2@option@2@</term>
       <listitem>
        <para>
         Determines whether or not to allow printing.
@@ -1282,7 +1282,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--modify=[yn]</option></term>
+      <term>@1@option@1@--modify=[yn]@2@option@2@</term>
       <listitem>
        <para>
         Determines whether or not to allow document modification.
@@ -1290,7 +1290,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--extract=[yn]</option></term>
+      <term>@1@option@1@--extract=[yn]@2@option@2@</term>
       <listitem>
        <para>
         Determines whether or not to allow text/image extraction.
@@ -1298,7 +1298,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--annotate=[yn]</option></term>
+      <term>@1@option@1@--annotate=[yn]@2@option@2@</term>
       <listitem>
        <para>
         Determines whether or not to allow comments and form fill-in
@@ -1307,11 +1307,11 @@ make
       </listitem>
      </varlistentry>
     </variablelist>
-    If <option><replaceable>key-length</replaceable></option> is 128,
+    If @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@ is 128,
     the following restriction options are available:
     <variablelist>
      <varlistentry>
-      <term><option>--accessibility=[yn]</option></term>
+      <term>@1@option@1@--accessibility=[yn]@2@option@2@</term>
       <listitem>
        <para>
         Determines whether or not to allow accessibility to visually
@@ -1325,7 +1325,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--extract=[yn]</option></term>
+      <term>@1@option@1@--extract=[yn]@2@option@2@</term>
       <listitem>
        <para>
         Determines whether or not to allow text/graphic extraction.
@@ -1333,7 +1333,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--assemble=[yn]</option></term>
+      <term>@1@option@1@--assemble=[yn]@2@option@2@</term>
       <listitem>
        <para>
         Determines whether document assembly (rotation and reordering
@@ -1342,18 +1342,18 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--annotate=[yn]</option></term>
+      <term>@1@option@1@--annotate=[yn]@2@option@2@</term>
       <listitem>
        <para>
         Determines whether modifying annotations is allowed. This
         includes adding comments and filling in form fields. Also
         allows editing of form fields if
-        <option>--modify-other=y</option> is given.
+        @1@option@1@--modify-other=y@2@option@2@ is given.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--form=[yn]</option></term>
+      <term>@1@option@1@--form=[yn]@2@option@2@</term>
       <listitem>
        <para>
         Determines whether filling form fields is allowed.
@@ -1361,37 +1361,37 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--modify-other=[yn]</option></term>
+      <term>@1@option@1@--modify-other=[yn]@2@option@2@</term>
       <listitem>
        <para>
         Allow all document editing except those controlled separately
-        by the <option>--assemble</option>,
-        <option>--annotate</option>, and <option>--form</option>
+        by the @1@option@1@--assemble@2@option@2@,
+        @1@option@1@--annotate@2@option@2@, and @1@option@1@--form@2@option@2@
         options.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--print=<replaceable>print-opt</replaceable></option></term>
+      <term>@1@option@1@--print=@1@replaceable@1@print-opt@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         Controls printing access.
-        <option><replaceable>print-opt</replaceable></option> may be
+        @1@option@1@@1@replaceable@1@print-opt@2@replaceable@2@@2@option@2@ may be
         one of the following:
         <itemizedlist>
          <listitem>
           <para>
-           <option>full</option>: allow full printing
+           @1@option@1@full@2@option@2@: allow full printing
           </para>
          </listitem>
          <listitem>
           <para>
-           <option>low</option>: allow low-resolution printing only
+           @1@option@1@low@2@option@2@: allow low-resolution printing only
           </para>
          </listitem>
          <listitem>
           <para>
-           <option>none</option>: disallow printing
+           @1@option@1@none@2@option@2@: disallow printing
           </para>
          </listitem>
         </itemizedlist>
@@ -1399,53 +1399,53 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--modify=<replaceable>modify-opt</replaceable></option></term>
+      <term>@1@option@1@--modify=@1@replaceable@1@modify-opt@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         Controls modify access. This way of controlling modify access
         has less granularity than new options added in qpdf 8.4.
-        <option><replaceable>modify-opt</replaceable></option> may be
+        @1@option@1@@1@replaceable@1@modify-opt@2@replaceable@2@@2@option@2@ may be
         one of the following:
         <itemizedlist>
          <listitem>
           <para>
-           <option>all</option>: allow full document modification
+           @1@option@1@all@2@option@2@: allow full document modification
           </para>
          </listitem>
          <listitem>
           <para>
-           <option>annotate</option>: allow comment authoring, form
+           @1@option@1@annotate@2@option@2@: allow comment authoring, form
            operations, and document assembly
           </para>
          </listitem>
          <listitem>
           <para>
-           <option>form</option>: allow form field fill-in and signing
+           @1@option@1@form@2@option@2@: allow form field fill-in and signing
            and document assembly
           </para>
          </listitem>
          <listitem>
           <para>
-           <option>assembly</option>: allow document assembly only
+           @1@option@1@assembly@2@option@2@: allow document assembly only
           </para>
          </listitem>
          <listitem>
           <para>
-           <option>none</option>: allow no modifications
+           @1@option@1@none@2@option@2@: allow no modifications
           </para>
          </listitem>
         </itemizedlist>
-        Using the <option>--modify</option> option does not allow you
+        Using the @1@option@1@--modify@2@option@2@ option does not allow you
         to create certain combinations of permissions such as allowing
         form filling but not allowing document assembly. Starting with
         qpdf 8.4, you can either just use the other options to control
         fields individually, or you can use something like
-        <option>--modify=form --assembly=n</option> to fine tune.
+        @1@option@1@--modify=form --assembly=n@2@option@2@ to fine tune.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--cleartext-metadata</option></term>
+      <term>@1@option@1@--cleartext-metadata@2@option@2@</term>
       <listitem>
        <para>
         If specified, any metadata stream in the document will be left
@@ -1455,17 +1455,17 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--use-aes=[yn]</option></term>
+      <term>@1@option@1@--use-aes=[yn]@2@option@2@</term>
       <listitem>
        <para>
-        If <option>--use-aes=y</option> is specified, AES encryption
+        If @1@option@1@--use-aes=y@2@option@2@ is specified, AES encryption
         will be used instead of RC4 encryption.  This forces the PDF
         version to be at least 1.6.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--allow-insecure</option></term>
+      <term>@1@option@1@--allow-insecure@2@option@2@</term>
       <listitem>
        <para>
         From qpdf 10.2, qpdf defaults to not allowing creation of PDF
@@ -1480,7 +1480,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--force-V4</option></term>
+      <term>@1@option@1@--force-V4@2@option@2@</term>
       <listitem>
        <para>
         Use of this option forces the <literal>/V</literal> and
@@ -1494,14 +1494,14 @@ make
       </listitem>
      </varlistentry>
     </variablelist>
-    If <option><replaceable>key-length</replaceable></option> is 256,
+    If @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@ is 256,
     the minimum PDF version is 1.7 with extension level 8, and the
     AES-based encryption format used is the PDF 2.0 encryption method
     supported by Acrobat X.  the same options are available as with
     128 bits with the following exceptions:
     <variablelist>
      <varlistentry>
-      <term><option>--use-aes</option></term>
+      <term>@1@option@1@--use-aes@2@option@2@</term>
       <listitem>
        <para>
         This option is not available with 256-bit keys.  AES is always
@@ -1510,7 +1510,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--force-V4</option></term>
+      <term>@1@option@1@--force-V4@2@option@2@</term>
       <listitem>
        <para>
         This option is not available with 256 keys.
@@ -1518,7 +1518,7 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--force-R5</option></term>
+      <term>@1@option@1@--force-R5@2@option@2@</term>
       <listitem>
        <para>
         If specified, qpdf sets the minimum version to 1.7 at
@@ -1543,17 +1543,17 @@ make
     file is given as the primary input file is used as the starting
     point, but its pages are replaced with pages as specified.
-    <programlisting><option>--pages <replaceable>input-file</replaceable> [ <replaceable>--password=password</replaceable> ] [ <replaceable>page-range</replaceable> ] [ ... ] --</option>
+    <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@
 </programlisting>
     Multiple input files may be specified.  Each one is given as the
     name of the input file, an optional password (if required to open
     the file), and the range of pages.  Note that
-    &ldquo;<option>--</option>&rdquo; terminates parsing of page
+    &ldquo;@1@option@1@--@2@option@2@&rdquo; terminates parsing of page
     selection flags.
    </para>
    <para>
     Starting with qpf 8.4, the special input file name
-    &ldquo;<filename>.</filename>&rdquo; can be used as a shortcut for the
+    &ldquo;@1@filename@1@.@2@filename@2@&rdquo; can be used as a shortcut for the
     primary input filename.
    </para>
    <para>
@@ -1566,7 +1566,7 @@ make
     multiple times.  If a file that is repeated has a password, the
     password only has to be given the first time.  All non-page data
     (info, outlines, page numbers, etc.) are taken from the primary
-    input file.  To discard these, use <option>--empty</option> as the
+    input file.  To discard these, use @1@option@1@--empty@2@option@2@ as the
     primary input.
    </para>
    <para>
@@ -1576,7 +1576,7 @@ make
     will implicitly use the range <literal>1-z</literal>, meaning that
     it will include all pages in the file.  This makes it possible to
     easily combine all pages in a set of files with a command like
-    <command>qpdf --empty out.pdf --pages *.pdf --</command>.
+    @1@command@1@qpdf --empty out.pdf --pages *.pdf --@2@command@2@.
    </para>
    <para>
     The page range is a set of numbers separated by commas, ranges of
@@ -1634,22 +1634,22 @@ make
    </para>
    <para>
     Starting in qpdf version 8.3, you can specify the
-    <option>--collate</option> option. Note that this option is
-    specified outside of <option>--pages&nbsp;...&nbsp;--</option>.
-    When <option>--collate</option> is specified, it changes the
-    meaning of <option>--pages</option> so that the specified files,
+    @1@option@1@--collate@2@option@2@ option. Note that this option is
+    specified outside of @1@option@1@--pages&nbsp;...&nbsp;--@2@option@2@.
+    When @1@option@1@--collate@2@option@2@ is specified, it changes the
+    meaning of @1@option@1@--pages@2@option@2@ so that the specified files,
     as modified by page ranges, are collated rather than concatenated.
-    For example, if you add the files <filename>odd.pdf</filename> and
-    <filename>even.pdf</filename> containing odd and even pages of a
-    document respectively, you could run <command>qpdf --collate
-    odd.pdf --pages odd.pdf even.pdf -- all.pdf</command> to collate
+    For example, if you add the files @1@filename@1@odd.pdf@2@filename@2@ and
+    @1@filename@1@even.pdf@2@filename@2@ containing odd and even pages of a
+    document respectively, you could run @1@command@1@qpdf --collate
+    odd.pdf --pages odd.pdf even.pdf -- all.pdf@2@command@2@ to collate
     the pages. This would pick page 1 from odd, page 1 from even, page
     2 from odd, page 2 from even, etc. until all pages have been
     included. Any number of files and page ranges can be specified. If
     any file has fewer pages, that file is just skipped when its pages
-    have all been included. For example, if you ran <command>qpdf
+    have all been included. For example, if you ran @1@command@1@qpdf
     --collate --empty --pages a.pdf 1-5 b.pdf 6-4 c.pdf r1 --
-    out.pdf</command>, you would get the following pages in this
+    out.pdf@2@command@2@, you would get the following pages in this
     order:
     <itemizedlist>
      <listitem><para>a.pdf page 1</para></listitem>
@@ -1665,12 +1665,12 @@ make
    </para>
    <para>
     Starting in qpdf version 10.2, you may specify a numeric argument
-    to <option>--collate</option>. With
-    <option>--collate=<replaceable>n</replaceable></option>, pull
-    groups of <replaceable>n</replaceable> pages from each file,
+    to @1@option@1@--collate@2@option@2@. With
+    @1@option@1@--collate=@1@replaceable@1@n@2@replaceable@2@@2@option@2@, pull
+    groups of @1@replaceable@1@n@2@replaceable@2@ pages from each file,
     again, stopping when there are no more pages. For example, if you
-    ran <command>qpdf --collate=2 --empty --pages a.pdf 1-5 b.pdf 6-4
-    c.pdf r1 -- out.pdf</command>, you would get the following pages
+    ran @1@command@1@qpdf --collate=2 --empty --pages a.pdf 1-5 b.pdf 6-4
+    c.pdf r1 -- out.pdf@2@command@2@, you would get the following pages
     in this order:
     <itemizedlist>
      <listitem><para>a.pdf page 1</para></listitem>
@@ -1693,46 +1693,46 @@ make
     outlines (bookmarks) point to actual page objects, so if you
     select some pages and not others, bookmarks that point to pages
     that are in the output file will work, and remaining bookmarks
-    will not work. A future version of <command>qpdf</command> may do
+    will not work. A future version of @1@command@1@qpdf@2@command@2@ may do
     a better job at handling these issues. (Note that the qpdf library
     already contains all of the APIs required in order to implement
     this in your own application if you need it.) In the mean time,
-    you can always use <option>--empty</option> as the primary input
+    you can always use @1@option@1@--empty@2@option@2@ as the primary input
     file to avoid copying all of that from the first file. For
     example, to take pages 1 through 5 from a
-    <filename>infile.pdf</filename> while preserving all metadata
+    @1@filename@1@infile.pdf@2@filename@2@ while preserving all metadata
     associated with that file, you could use
-    <programlisting><command>qpdf</command> <option>infile.pdf --pages . 1-5 -- outfile.pdf</option>
+    <programlisting>@1@command@1@qpdf@2@command@2@ @1@option@1@infile.pdf --pages . 1-5 -- outfile.pdf@2@option@2@
 </programlisting>
     If you wanted pages 1 through 5 from
-    <filename>infile.pdf</filename> but you wanted the rest of the
+    @1@filename@1@infile.pdf@2@filename@2@ but you wanted the rest of the
     metadata to be dropped, you could instead run
-    <programlisting><command>qpdf</command> <option>--empty --pages infile.pdf 1-5 -- outfile.pdf</option>
+    <programlisting>@1@command@1@qpdf@2@command@2@ @1@option@1@--empty --pages infile.pdf 1-5 -- outfile.pdf@2@option@2@
 </programlisting>
     If you wanted to take pages 1&ndash;5 from
-    <filename>file1.pdf</filename> and pages 11&ndash;15 from
-    <filename>file2.pdf</filename> in reverse, taking document-level
-    metadata from <filename>file2.pdf</filename>, you would run
+    @1@filename@1@file1.pdf@2@filename@2@ and pages 11&ndash;15 from
+    @1@filename@1@file2.pdf@2@filename@2@ in reverse, taking document-level
+    metadata from @1@filename@1@file2.pdf@2@filename@2@, you would run
-    <programlisting><command>qpdf</command> <option>file2.pdf --pages file1.pdf 1-5 . 15-11 -- outfile.pdf</option>
+    <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@
 </programlisting>
     If, for some reason, you wanted to take the first page of an
-    encrypted file called <filename>encrypted.pdf</filename> with
+    encrypted file called @1@filename@1@encrypted.pdf@2@filename@2@ with
     password <literal>pass</literal> and repeat it twice in an output
     file, and if you wanted to drop document-level metadata but
     preserve encryption, you would use
-    <programlisting><command>qpdf</command> <option>--empty --copy-encryption=encrypted.pdf --encryption-file-password=pass
+    <programlisting>@1@command@1@qpdf@2@command@2@ @1@option@1@--empty --copy-encryption=encrypted.pdf --encryption-file-password=pass
 --pages encrypted.pdf --password=pass 1 ./encrypted.pdf --password=pass 1 --
-outfile.pdf</option>
+outfile.pdf@2@option@2@
 </programlisting>
     Note that we had to specify the password all three times because
-    giving a password as <option>--encryption-file-password</option>
+    giving a password as @1@option@1@--encryption-file-password@2@option@2@
     doesn't count for page selection, and as far as qpdf is concerned,
-    <filename>encrypted.pdf</filename> and
-    <filename>./encrypted.pdf</filename> are separated files.  These
+    @1@filename@1@encrypted.pdf@2@filename@2@ and
+    @1@filename@1@./encrypted.pdf@2@filename@2@ are separated files.  These
     are all corner cases that most users should hopefully never have
     to be bothered with.
    </para>
@@ -1746,7 +1746,7 @@ outfile.pdf&lt;/option&gt;
     going to do further manipulation on the file and need the two
     instances of the same original page to be deep copies, then you
     can specify the file in two different ways. For example
-    <command>qpdf in.pdf --pages . 1 ./in.pdf 1 -- out.pdf</command>
+    @1@command@1@qpdf in.pdf --pages . 1 ./in.pdf 1 -- out.pdf@2@command@2@
     would create a file with two copies of the first page of the
     input, and the two copies would share any objects in common. This
     includes fonts, images, and anything else the page references.
@@ -1759,12 +1759,12 @@ outfile.pdf&lt;/option&gt;
     pages from other files onto the output generated by qpdf. Specify
     overlay or underlay as follows:
-    <programlisting>{ <option>--overlay</option> | <option>--underlay</option> } <replaceable>file</replaceable> [ <option>options</option> ] <option>--</option>
+    <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@
 </programlisting>
     Overlay and underlay options are processed late, so they can be
     combined with other like merging and will apply to the final
-    output. The <option>--overlay</option> and
-    <option>--underlay</option> options work the same way, except
+    output. The @1@option@1@--overlay@2@option@2@ and
+    @1@option@1@--underlay@2@option@2@ options work the same way, except
     underlay pages are drawn underneath the page to which they are
     applied, possibly obscured by the original page, and overlay files
     are drawn on top of the page to which they are applied, possibly
@@ -1777,19 +1777,19 @@ outfile.pdf&lt;/option&gt;
     pages. If the overlay or underlay file runs out of pages,
     remaining output pages are left alone. This behavior can be
     modified by options, which are provided between the
-    <option>--overlay</option> or <option>--underlay</option> flag and
-    the <option>--</option> option. The following options are
+    @1@option@1@--overlay@2@option@2@ or @1@option@1@--underlay@2@option@2@ flag and
+    the @1@option@1@--@2@option@2@ option. The following options are
     supported:
     <itemizedlist>
      <listitem>
       <para>
-       <option>--password=password</option>: supply a password if the
+       @1@option@1@--password=password@2@option@2@: supply a password if the
        overlay/underlay file is encrypted.
       </para>
      </listitem>
      <listitem>
       <para>
-       <option>--to=page-range</option>: a range of pages in the same
+       @1@option@1@--to=page-range@2@option@2@: a range of pages in the same
        form at described in <xref linkend="ref.page-selection"/>
        indicates which pages in the output should have the
        overlay/underlay applied. If not specified, overlay/underlay
@@ -1798,20 +1798,20 @@ outfile.pdf&lt;/option&gt;
      </listitem>
      <listitem>
       <para>
-       <option>--from=[page-range]</option>: a range of pages that
+       @1@option@1@--from=[page-range]@2@option@2@: a range of pages that
        specifies which pages in the overlay/underlay file will be used
        for overlay or underlay. If not specified, all pages will be
        used. This can be explicitly specified to be empty if
-       <option>--repeat</option> is used.
+       @1@option@1@--repeat@2@option@2@ is used.
       </para>
      </listitem>
      <listitem>
       <para>
-       <option>--repeat=page-range</option>: an optional range of
+       @1@option@1@--repeat=page-range@2@option@2@: an optional range of
        pages that specifies which pages in the overlay/underlay file
        will be repeated after the &ldquo;from&rdquo; pages are used
        up. If you want to repeat a range of pages starting at the
-       beginning, you can explicitly use <option>--from=</option>.
+       beginning, you can explicitly use @1@option@1@--from=@2@option@2@.
       </para>
      </listitem>
     </itemizedlist>
@@ -1821,20 +1821,20 @@ outfile.pdf&lt;/option&gt;
     <itemizedlist>
      <listitem>
       <para>
-       <command>--overlay o.pdf --to=1-5 --from=1-3
-       --repeat=4 --</command>: overlay the first three pages from file
-       <filename>o.pdf</filename> onto the first three pages of the
-       output, then overlay page 4 from <filename>o.pdf</filename>
+       @1@command@1@--overlay o.pdf --to=1-5 --from=1-3
+       --repeat=4 --@2@command@2@: overlay the first three pages from file
+       @1@filename@1@o.pdf@2@filename@2@ onto the first three pages of the
+       output, then overlay page 4 from @1@filename@1@o.pdf@2@filename@2@
        onto pages 4 and 5 of the output. Leave remaining output pages
        untouched.
       </para>
      </listitem>
      <listitem>
       <para>
-       <command>--underlay footer.pdf --from= --repeat=1,2 --</command>:
-       Underlay page 1 of <filename>footer.pdf</filename> on all odd
+       @1@command@1@--underlay footer.pdf --from= --repeat=1,2 --@2@command@2@:
+       Underlay page 1 of @1@filename@1@footer.pdf@2@filename@2@ on all odd
        output pages, and underlay page 2 of
-       <filename>footer.pdf</filename> on all even output pages.
+       @1@filename@1@footer.pdf@2@filename@2@ on all even output pages.
       </para>
      </listitem>
     </itemizedlist>
@@ -1847,11 +1847,11 @@ outfile.pdf&lt;/option&gt;
     files from the command line. The following options are available:
     <variablelist>
      <varlistentry>
-      <term><option>--list-attachments</option></term>
+      <term>@1@option@1@--list-attachments@2@option@2@</term>
       <listitem>
        <para>
         Show the &ldquo;key&rdquo; and stream number for embedded
-        files. With <option>--verbose</option>, additional
+        files. With @1@option@1@--verbose@2@option@2@, additional
         information, including preferred file name, description,
         dates, and more are also displayed. The key is usually but not
         always equal to the file name, and is needed by some of the
@@ -1860,48 +1860,48 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--show-attachment=<replaceable>key</replaceable></option></term>
+      <term>@1@option@1@--show-attachment=@1@replaceable@1@key@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         Write the contents of the specified attachment to standard
         output as binary data. The key should match one of the keys
-        shown by <option>--list-attachments</option>. If specified
+        shown by @1@option@1@--list-attachments@2@option@2@. If specified
         multiple times, only the last attachment will be shown.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--add-attachment <replaceable>file</replaceable> <replaceable>options</replaceable> --</option></term>
+      <term>@1@option@1@--add-attachment @1@replaceable@1@file@2@replaceable@2@ @1@replaceable@1@options@2@replaceable@2@ --@2@option@2@</term>
       <listitem>
        <para>
         Add or replace an attachment with the contents of
-        <replaceable>file</replaceable>. This may be specified more
+        @1@replaceable@1@file@2@replaceable@2@. This may be specified more
         than once. The following additional options may appear before
         the <literal>--</literal> that ends this option:
         <variablelist>
          <varlistentry>
-          <term><option>--key=<replaceable>key</replaceable></option></term>
+          <term>@1@option@1@--key=@1@replaceable@1@key@2@replaceable@2@@2@option@2@</term>
           <listitem>
            <para>
             The key to use to register the attachment in the embedded
             files table. Defaults to the last path element of
-            <replaceable>file</replaceable>.
+            @1@replaceable@1@file@2@replaceable@2@.
            </para>
           </listitem>
          </varlistentry>
          <varlistentry>
-          <term><option>--filename=<replaceable>name</replaceable></option></term>
+          <term>@1@option@1@--filename=@1@replaceable@1@name@2@replaceable@2@@2@option@2@</term>
           <listitem>
            <para>
             The file name to be used for the attachment. This is what is usually
             displayed to the user and is the name most graphical PDF
             viewers will use when saving a file. It defaults to the
-            last path element of <replaceable>file</replaceable>.
+            last path element of @1@replaceable@1@file@2@replaceable@2@.
            </para>
           </listitem>
          </varlistentry>
          <varlistentry>
-          <term><option>--creationdate=<replaceable>date</replaceable></option></term>
+          <term>@1@option@1@--creationdate=@1@replaceable@1@date@2@replaceable@2@@2@option@2@</term>
           <listitem>
            <para>
             The attachment's creation date in PDF format; defaults to
@@ -1910,7 +1910,7 @@ outfile.pdf&lt;/option&gt;
           </listitem>
          </varlistentry>
          <varlistentry>
-          <term><option>--moddate=<replaceable>date</replaceable></option></term>
+          <term>@1@option@1@--moddate=@1@replaceable@1@date@2@replaceable@2@@2@option@2@</term>
           <listitem>
            <para>
             The attachment's modification date in PDF format; defaults
@@ -1919,7 +1919,7 @@ outfile.pdf&lt;/option&gt;
           </listitem>
          </varlistentry>
          <varlistentry>
-          <term><option>--mimetype=<replaceable>type/subtype</replaceable></option></term>
+          <term>@1@option@1@--mimetype=@1@replaceable@1@type/subtype@2@replaceable@2@@2@option@2@</term>
           <listitem>
            <para>
             The mime type for the attachment, e.g.
@@ -1932,7 +1932,7 @@ outfile.pdf&lt;/option&gt;
           </listitem>
          </varlistentry>
          <varlistentry>
-          <term><option>--description=<replaceable>&quot;text&quot;</replaceable></option></term>
+          <term>@1@option@1@--description=@1@replaceable@1@&quot;text&quot;@2@replaceable@2@@2@option@2@</term>
           <listitem>
            <para>
             Descriptive text for the attachment, displayed by some PDF
@@ -1941,12 +1941,12 @@ outfile.pdf&lt;/option&gt;
           </listitem>
          </varlistentry>
          <varlistentry>
-          <term><option>--replace</option></term>
+          <term>@1@option@1@--replace@2@option@2@</term>
           <listitem>
            <para>
             Indicates that any existing attachment with the same key
             should be replaced by the new attachment. Otherwise,
-            <command>qpdf</command> gives an error if an attachment
+            @1@command@1@qpdf@2@command@2@ gives an error if an attachment
             with that key is already present.
            </para>
           </listitem>
@@ -1956,20 +1956,20 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--remove-attachment=<replaceable>key</replaceable></option></term>
+      <term>@1@option@1@--remove-attachment=@1@replaceable@1@key@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         Remove the specified attachment. This doesn't only remove the
         attachment from the embedded files table but also clears out
         the file specification. That means that any potential internal
         links to the attachment will be broken. This option may be
-        specified multiple times. Run with <option>--verbose</option>
+        specified multiple times. Run with @1@option@1@--verbose@2@option@2@
         to see status of the removal.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--copy-attachments-from <replaceable>file</replaceable> <replaceable>options</replaceable> --</option></term>
+      <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>
       <listitem>
        <para>
         Copy attachments from another file. This may be specified more
@@ -1977,16 +1977,16 @@ outfile.pdf&lt;/option&gt;
         the <literal>--</literal> that ends this option:
         <variablelist>
          <varlistentry>
-          <term><option>--password=<replaceable>password</replaceable></option></term>
+          <term>@1@option@1@--password=@1@replaceable@1@password@2@replaceable@2@@2@option@2@</term>
           <listitem>
            <para>
             If required, the password needed to open
-            <replaceable>file</replaceable>
+            @1@replaceable@1@file@2@replaceable@2@
            </para>
           </listitem>
          </varlistentry>
          <varlistentry>
-          <term><option>--prefix=<replaceable>prefix</replaceable></option></term>
+          <term>@1@option@1@--prefix=@1@replaceable@1@prefix@2@replaceable@2@@2@option@2@</term>
           <listitem>
            <para>
             Only required if the file from which attachments are being
@@ -2006,11 +2006,11 @@ outfile.pdf&lt;/option&gt;
     </variablelist>
     When a date is required, the date should conform to the PDF date
     format specification, which is
-    <literal>D:</literal><replaceable>yyyymmddhhmmss&lt;z&gt;</replaceable>,
-    where <replaceable>&lt;z&gt;</replaceable> is either
+    <literal>D:</literal>@1@replaceable@1@yyyymmddhhmmss&lt;z&gt;@2@replaceable@2@,
+    where @1@replaceable@1@&lt;z&gt;@2@replaceable@2@ is either
     <literal>Z</literal> for UTC or a timezone offset in the form
-    <replaceable>-hh'mm'</replaceable> or
-    <replaceable>+hh'mm'</replaceable>. Examples:
+    @1@replaceable@1@-hh'mm'@2@replaceable@2@ or
+    @1@replaceable@1@+hh'mm'@2@replaceable@2@. Examples:
     <literal>D:20210207161528-05'00'</literal>,
     <literal>D:20210207211528Z</literal>.
    </para>
@@ -2024,7 +2024,7 @@ outfile.pdf&lt;/option&gt;
     to solve specific problems. The following options are available:
     <variablelist>
      <varlistentry>
-      <term><option>--suppress-recovery</option></term>
+      <term>@1@option@1@--suppress-recovery@2@option@2@</term>
       <listitem>
        <para>
         Prevents qpdf from attempting to recover damaged files.
@@ -2032,7 +2032,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--ignore-xref-streams</option></term>
+      <term>@1@option@1@--ignore-xref-streams@2@option@2@</term>
       <listitem>
        <para>
         Tells qpdf to ignore any cross-reference streams.
@@ -2048,13 +2048,13 @@ outfile.pdf&lt;/option&gt;
     of stream length errors.  Sometimes, qpdf may think it has
     recovered but may not have actually recovered, so care should be
     taken when using this option as some data loss is possible.  The
-    <option>--suppress-recovery</option> option will prevent qpdf from
+    @1@option@1@--suppress-recovery@2@option@2@ option will prevent qpdf from
     attempting recovery.  In this case, it will fail on the first
     error that it encounters.
    </para>
    <para>
     Ordinarily, qpdf reads cross-reference streams when they are
-    present in a PDF file.  If <option>--ignore-xref-streams</option>
+    present in a PDF file.  If @1@option@1@--ignore-xref-streams@2@option@2@
     is specified, qpdf will ignore any cross-reference streams for
     hybrid PDF files.  The purpose of hybrid files is to make some
     content available to viewers that are not aware of cross-reference
@@ -2074,34 +2074,34 @@ outfile.pdf&lt;/option&gt;
     developers.  The following options are available:
     <variablelist>
      <varlistentry>
-      <term><option>--compress-streams=<replaceable>[yn]</replaceable></option></term>
+      <term>@1@option@1@--compress-streams=@1@replaceable@1@[yn]@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
-        By default, or with <option>--compress-streams=y</option>,
+        By default, or with @1@option@1@--compress-streams=y@2@option@2@,
         qpdf will compress any stream with no other filters applied to
         it with the <literal>/FlateDecode</literal> filter when it
         writes it. To suppress this behavior and preserve uncompressed
         streams as uncompressed, use
-        <option>--compress-streams=n</option>.
+        @1@option@1@--compress-streams=n@2@option@2@.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--decode-level=<replaceable>option</replaceable></option></term>
+      <term>@1@option@1@--decode-level=@1@replaceable@1@option@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         Controls which streams qpdf tries to decode. The default is
-        <option>generalized</option>. The following options are
+        @1@option@1@generalized@2@option@2@. The following options are
         available:
         <itemizedlist>
          <listitem>
           <para>
-           <option>none</option>: do not attempt to decode any streams
+           @1@option@1@none@2@option@2@: do not attempt to decode any streams
           </para>
          </listitem>
          <listitem>
           <para>
-           <option>generalized</option>: decode streams filtered with
+           @1@option@1@generalized@2@option@2@: decode streams filtered with
            supported generalized filters:
            <literal>/LZWDecode</literal>,
            <literal>/FlateDecode</literal>,
@@ -2112,12 +2112,12 @@ outfile.pdf&lt;/option&gt;
            for image data. Note that, by default, streams already
            compressed with <literal>/FlateDecode</literal> are not
            uncompressed and recompressed unless you also specify
-           <option>--recompress-flate</option>.
+           @1@option@1@--recompress-flate@2@option@2@.
           </para>
          </listitem>
          <listitem>
           <para>
-           <option>specialized</option>: in addition to generalized,
+           @1@option@1@specialized@2@option@2@: in addition to generalized,
            decode streams with supported non-lossy specialized
            filters; currently this is just
            <literal>/RunLengthDecode</literal>
@@ -2125,7 +2125,7 @@ outfile.pdf&lt;/option&gt;
          </listitem>
          <listitem>
           <para>
-           <option>all</option>: in addition to generalized and
+           @1@option@1@all@2@option@2@: in addition to generalized and
            specialized, decode streams with supported lossy filters;
            currently this is just <literal>/DCTDecode</literal> (JPEG)
           </para>
@@ -2135,40 +2135,40 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--stream-data=<replaceable>option</replaceable></option></term>
+      <term>@1@option@1@--stream-data=@1@replaceable@1@option@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         Controls transformation of stream data. This option predates
-        the <option>--compress-streams</option> and
-        <option>--decode-level</option> options. Those options can be
+        the @1@option@1@--compress-streams@2@option@2@ and
+        @1@option@1@--decode-level@2@option@2@ options. Those options can be
         used to achieve the same affect with more control. The value
-        of <option><replaceable>option</replaceable></option> may be
+        of @1@option@1@@1@replaceable@1@option@2@replaceable@2@@2@option@2@ may be
         one of the following:
         <itemizedlist>
          <listitem>
           <para>
-           <option>compress</option>: recompress stream data when
+           @1@option@1@compress@2@option@2@: recompress stream data when
            possible (default); equivalent to
-           <option>--compress-streams=y</option>
-           <option>--decode-level=generalized</option>. Does not
+           @1@option@1@--compress-streams=y@2@option@2@
+           @1@option@1@--decode-level=generalized@2@option@2@. Does not
            recompress streams already compressed with
            <literal>/FlateDecode</literal> unless
-           <option>--recompress-flate</option> is also specified.
+           @1@option@1@--recompress-flate@2@option@2@ is also specified.
           </para>
          </listitem>
          <listitem>
           <para>
-           <option>preserve</option>: leave all stream data as is;
-           equivalent to <option>--compress-streams=n</option>
-           <option>--decode-level=none</option>
+           @1@option@1@preserve@2@option@2@: leave all stream data as is;
+           equivalent to @1@option@1@--compress-streams=n@2@option@2@
+           @1@option@1@--decode-level=none@2@option@2@
           </para>
          </listitem>
          <listitem>
           <para>
-           <option>uncompress</option>: uncompress stream data
+           @1@option@1@uncompress@2@option@2@: uncompress stream data
            compressed with generalized filters when possible;
-           equivalent to <option>--compress-streams=n</option>
-           <option>--decode-level=generalized</option>
+           equivalent to @1@option@1@--compress-streams=n@2@option@2@
+           @1@option@1@--decode-level=generalized@2@option@2@
           </para>
          </listitem>
         </itemizedlist>
@@ -2176,7 +2176,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--recompress-flate</option></term>
+      <term>@1@option@1@--recompress-flate@2@option@2@</term>
       <listitem>
        <para>
         By default, streams already compressed with
@@ -2185,29 +2185,29 @@ outfile.pdf&lt;/option&gt;
         to uncompress and recompress the streams. There is a
         significant performance cost to using this option, but you
         probably want to use it if you specify
-        <option>--compression-level</option>.
+        @1@option@1@--compression-level@2@option@2@.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--compression-level=<replaceable>level</replaceable></option></term>
+      <term>@1@option@1@--compression-level=@1@replaceable@1@level@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         When writing new streams that are compressed with
         <literal>/FlateDecode</literal>, use the specified compression
-        level. The value of <option>level</option> should be a number
+        level. The value of @1@option@1@level@2@option@2@ should be a number
         from 1 to 9 and is passed directly to zlib, which implements
         deflate compression. Note that qpdf doesn't uncompress and
         recompress streams by default. To have this option apply to
         already compressed streams, you should also specify
-        <option>--recompress-flate</option>. If your goal is to shrink
+        @1@option@1@--recompress-flate@2@option@2@. If your goal is to shrink
         the size of PDF files, you should also use
-        <option>--object-streams=generate</option>.
+        @1@option@1@--object-streams=generate@2@option@2@.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--normalize-content=[yn]</option></term>
+      <term>@1@option@1@--normalize-content=[yn]@2@option@2@</term>
       <listitem>
        <para>
         Enables or disables normalization of content streams. Content
@@ -2218,27 +2218,27 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--object-streams=<replaceable>mode</replaceable></option></term>
+      <term>@1@option@1@--object-streams=@1@replaceable@1@mode@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         Controls handling of object streams.  The value of
-        <option><replaceable>mode</replaceable></option> may be one of
+        @1@option@1@@1@replaceable@1@mode@2@replaceable@2@@2@option@2@ may be one of
         the following:
         <itemizedlist>
          <listitem>
           <para>
-           <option>preserve</option>: preserve original object streams
+           @1@option@1@preserve@2@option@2@: preserve original object streams
            (default)
           </para>
          </listitem>
          <listitem>
           <para>
-           <option>disable</option>: don't write any object streams
+           @1@option@1@disable@2@option@2@: don't write any object streams
           </para>
          </listitem>
          <listitem>
           <para>
-           <option>generate</option>: use object streams wherever
+           @1@option@1@generate@2@option@2@: use object streams wherever
            possible
           </para>
          </listitem>
@@ -2247,7 +2247,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--preserve-unreferenced</option></term>
+      <term>@1@option@1@--preserve-unreferenced@2@option@2@</term>
       <listitem>
        <para>
         Tells qpdf to preserve objects that are not referenced when
@@ -2266,16 +2266,16 @@ outfile.pdf&lt;/option&gt;
         file, and the original file may have gaps in its numbering.
        </para>
        <para>
-        See also <option>--preserve-unreferenced-resources</option>,
+        See also @1@option@1@--preserve-unreferenced-resources@2@option@2@,
         which does something completely different.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--remove-unreferenced-resources=<replaceable>option</replaceable></option></term>
+      <term>@1@option@1@--remove-unreferenced-resources=@1@replaceable@1@option@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
-        The <replaceable>option</replaceable> may be
+        The @1@replaceable@1@option@2@replaceable@2@ may be
         <literal>auto</literal>, <literal>yes</literal>, or
         <literal>no</literal>. The default is <literal>auto</literal>.
        </para>
@@ -2311,20 +2311,20 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--preserve-unreferenced-resources</option></term>
+      <term>@1@option@1@--preserve-unreferenced-resources@2@option@2@</term>
       <listitem>
        <para>
         This is a synonym for
-        <option>--remove-unreferenced-resources=no</option>.
+        @1@option@1@--remove-unreferenced-resources=no@2@option@2@.
        </para>
        <para>
-        See also <option>--preserve-unreferenced</option>, which does
+        See also @1@option@1@--preserve-unreferenced@2@option@2@, which does
         something completely different.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--newline-before-endstream</option></term>
+      <term>@1@option@1@--newline-before-endstream@2@option@2@</term>
       <listitem>
        <para>
         Tells qpdf to insert a newline before the
@@ -2339,7 +2339,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--linearize-pass1=<replaceable>file</replaceable></option></term>
+      <term>@1@option@1@--linearize-pass1=@1@replaceable@1@file@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         Write the first pass of linearization to the named file. The
@@ -2354,7 +2354,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--coalesce-contents</option></term>
+      <term>@1@option@1@--coalesce-contents@2@option@2@</term>
       <listitem>
        <para>
         When a page's contents are split across multiple streams, this
@@ -2368,7 +2368,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--flatten-annotations=<replaceable>option</replaceable></option></term>
+      <term>@1@option@1@--flatten-annotations=@1@replaceable@1@option@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         This option collapses annotations into the pages' contents
@@ -2380,24 +2380,24 @@ outfile.pdf&lt;/option&gt;
         functionality backing this option was added for the benefit of
         programs that want to create <emphasis>n-up</emphasis> page
         layouts and other similar things that don't work well with
-        annotations. The <replaceable>option</replaceable> parameter
+        annotations. The @1@replaceable@1@option@2@replaceable@2@ parameter
         may be any of the following:
         <itemizedlist>
          <listitem>
           <para>
-           <option>all</option>: include all annotations that are not
+           @1@option@1@all@2@option@2@: include all annotations that are not
            marked invisible or hidden
           </para>
          </listitem>
          <listitem>
           <para>
-           <option>print</option>: only include annotations that
+           @1@option@1@print@2@option@2@: only include annotations that
            indicate that they should appear when the page is printed
           </para>
          </listitem>
          <listitem>
           <para>
-           <option>screen</option>: omit annotations that indicate
+           @1@option@1@screen@2@option@2@: omit annotations that indicate
            they should not appear on the screen
           </para>
          </listitem>
@@ -2413,13 +2413,13 @@ outfile.pdf&lt;/option&gt;
         the form field to be lost. This gives you a chance to go back
         and resave the form with a program that knows how to generate
         appearances. QPDF itself can generate appearances with some
-        limitations. See the <option>--generate-appearances</option>
+        limitations. See the @1@option@1@--generate-appearances@2@option@2@
         option below.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--generate-appearances</option></term>
+      <term>@1@option@1@--generate-appearances@2@option@2@</term>
       <listitem>
        <para>
         If a file contains interactive form fields and indicates that
@@ -2427,7 +2427,7 @@ outfile.pdf&lt;/option&gt;
         this flag will regenerate appearances, subject to a few
         limitations. Note that there is not usually a reason to do
         this, but it can be necessary before using the
-        <option>--flatten-annotations</option> option. Most of these
+        @1@option@1@--flatten-annotations@2@option@2@ option. Most of these
         are not a problem with well-behaved PDF files. The limitations
         are as follows:
         <itemizedlist>
@@ -2485,7 +2485,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--optimize-images</option></term>
+      <term>@1@option@1@--optimize-images@2@option@2@</term>
       <listitem>
        <para>
         This flag causes qpdf to recompress all images that are not
@@ -2493,19 +2493,19 @@ outfile.pdf&lt;/option&gt;
         doing so decreases the size in bytes of the image data and the
         image does not fall below minimum specified dimensions. Useful
         information is provided when used in combination with
-        <option>--verbose</option>. See also the
-        <option>--oi-min-width</option>,
-        <option>--oi-min-height</option>, and
-        <option>--oi-min-area</option> options. By default, starting
+        @1@option@1@--verbose@2@option@2@. See also the
+        @1@option@1@--oi-min-width@2@option@2@,
+        @1@option@1@--oi-min-height@2@option@2@, and
+        @1@option@1@--oi-min-area@2@option@2@ options. By default, starting
         in qpdf 8.4, inline images are converted to regular images
         and optimized as well. Use
-        <option>--keep-inline-images</option> to prevent inline images
+        @1@option@1@--keep-inline-images@2@option@2@ to prevent inline images
         from being included.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--oi-min-width=<replaceable>width</replaceable></option></term>
+      <term>@1@option@1@--oi-min-width=@1@replaceable@1@width@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         Avoid optimizing images whose width is below the specified
@@ -2515,7 +2515,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--oi-min-height=<replaceable>height</replaceable></option></term>
+      <term>@1@option@1@--oi-min-height=@1@replaceable@1@height@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         Avoid optimizing images whose height is below the specified
@@ -2525,7 +2525,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--oi-min-area=<replaceable>area-in-pixels</replaceable></option></term>
+      <term>@1@option@1@--oi-min-area=@1@replaceable@1@area-in-pixels@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         Avoid optimizing images whose pixel count
@@ -2535,21 +2535,21 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--externalize-inline-images</option></term>
+      <term>@1@option@1@--externalize-inline-images@2@option@2@</term>
       <listitem>
        <para>
         Convert inline images to regular images. By default, images
         whose data is at least 1,024 bytes are converted when this
-        option is selected. Use <option>--ii-min-bytes</option> to
+        option is selected. Use @1@option@1@--ii-min-bytes@2@option@2@ to
         change the size threshold. This option is implicitly selected
-        when <option>--optimize-images</option> is selected. Use
-        <option>--keep-inline-images</option> to exclude inline images
+        when @1@option@1@--optimize-images@2@option@2@ is selected. Use
+        @1@option@1@--keep-inline-images@2@option@2@ to exclude inline images
         from image optimization.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--ii-min-bytes=<replaceable>bytes</replaceable></option></term>
+      <term>@1@option@1@--ii-min-bytes=@1@replaceable@1@bytes@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         Avoid converting inline images whose size is below the
@@ -2559,17 +2559,17 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--keep-inline-images</option></term>
+      <term>@1@option@1@--keep-inline-images@2@option@2@</term>
       <listitem>
        <para>
         Prevent inline images from being included in image
         optimization. This option has no affect when
-        <option>--optimize-images</option> is not specified.
+        @1@option@1@--optimize-images@2@option@2@ is not specified.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--remove-page-labels</option></term>
+      <term>@1@option@1@--remove-page-labels@2@option@2@</term>
       <listitem>
        <para>
         Remove page labels from the output file.
@@ -2577,21 +2577,21 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--qdf</option></term>
+      <term>@1@option@1@--qdf@2@option@2@</term>
       <listitem>
        <para>
         Turns on QDF mode.  For additional information on QDF, please
         see <xref linkend="ref.qdf"/>. Note that
-        <option>--linearize</option> disables QDF mode.
+        @1@option@1@--linearize@2@option@2@ disables QDF mode.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--min-version=<replaceable>version</replaceable></option></term>
+      <term>@1@option@1@--min-version=@1@replaceable@1@version@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         Forces the PDF version of the output file to be at least
-        <replaceable>version</replaceable>.  In other words, if the
+        @1@replaceable@1@version@2@replaceable@2@.  In other words, if the
         input file has a lower version than the specified version, the
         specified version will be used.  If the input file has a
         higher version, the input file's original version will be
@@ -2601,10 +2601,10 @@ outfile.pdf&lt;/option&gt;
        </para>
        <para>
         The version number may be expressed in the form
-        <replaceable>major.minor.extension-level</replaceable>, in
+        @1@replaceable@1@major.minor.extension-level@2@replaceable@2@, in
         which case the version is interpreted as
-        <replaceable>major.minor</replaceable> at extension level
-        <replaceable>extension-level</replaceable>.  For example,
+        @1@replaceable@1@major.minor@2@replaceable@2@ at extension level
+        @1@replaceable@1@extension-level@2@replaceable@2@.  For example,
         version <literal>1.7.8</literal> represents version 1.7 at
         extension level 8.  Note that minimal syntax checking is done
         on the command line.
@@ -2612,14 +2612,14 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--force-version=<replaceable>version</replaceable></option></term>
+      <term>@1@option@1@--force-version=@1@replaceable@1@version@2@replaceable@2@@2@option@2@</term>
       <listitem>
        <para>
         This option forces the PDF version to be the exact version
         specified <emphasis>even when the file may have content that
         is not supported in that version</emphasis>.  The version
         number is interpreted in the same way as with
-        <option>--min-version</option> so that extension levels can be
+        @1@option@1@--min-version@2@option@2@ so that extension levels can be
         set.  In some cases, forcing the output file's PDF version to
         be lower than that of the input file will cause qpdf to
         disable certain features of the document.  Specifically,
@@ -2653,10 +2653,10 @@ outfile.pdf&lt;/option&gt;
     compression scheme, qpdf will uncompress and recompress streams.
     Assuming proper filter implements, this is safe and generally
     results in smaller files.  This behavior may also be explicitly
-    requested with <option>--stream-data=compress</option>.
+    requested with @1@option@1@--stream-data=compress@2@option@2@.
    </para>
    <para>
-    When <option>--normalize-content=y</option> is specified, qpdf
+    When @1@option@1@--normalize-content=y@2@option@2@ is specified, qpdf
     will attempt to normalize whitespace and newlines in page content
     streams.  This is generally safe but could, in some cases, cause
     damage to the content streams.  This option is intended for people
@@ -2673,10 +2673,10 @@ outfile.pdf&lt;/option&gt;
     that do this are invalid since the PDF specification states that
     content streams are not to be split in the middle of a token. If
     you want to inspect the original content streams in an
-    uncompressed format, you can always run with <option>--qdf
-    --normalize-content=n</option> for a QDF file without content
+    uncompressed format, you can always run with @1@option@1@--qdf
+    --normalize-content=n@2@option@2@ for a QDF file without content
     normalization, or alternatively
-    <option>--stream-data=uncompress</option> for a regular non-QDF
+    @1@option@1@--stream-data=uncompress@2@option@2@ for a regular non-QDF
     mode file with uncompressed streams. These will both uncompress
     all the streams but will not attempt to normalize content. Please
     note that if you are using content normalization or QDF mode for
@@ -2690,25 +2690,25 @@ outfile.pdf&lt;/option&gt;
     object streams.  qpdf can be used to transform files with object
     streams to files without object streams or vice versa.  As
     mentioned above, there are three object stream modes:
-    <option>preserve</option>, <option>disable</option>, and
-    <option>generate</option>.
+    @1@option@1@preserve@2@option@2@, @1@option@1@disable@2@option@2@, and
+    @1@option@1@generate@2@option@2@.
    </para>
    <para>
-    In <option>preserve</option> mode, the relationship to objects and
+    In @1@option@1@preserve@2@option@2@ mode, the relationship to objects and
     the streams that contain them is preserved from the original file.
-    In <option>disable</option> mode, all objects are written as
+    In @1@option@1@disable@2@option@2@ mode, all objects are written as
     regular, uncompressed objects.  The resulting file should be
     readable by older PDF viewers.  (Of course, the content of the
     files may include features not supported by older viewers, but at
     least the structure will be supported.)  In
-    <option>generate</option> mode, qpdf will create its own object
+    @1@option@1@generate@2@option@2@ mode, qpdf will create its own object
     streams.  This will usually result in more compact PDF files,
     though they may not be readable by older viewers.  In this mode,
     qpdf will also make sure the PDF version number in the header is
     at least 1.5.
    </para>
    <para>
-    The <option>--qdf</option> flag turns on QDF mode, which changes
+    The @1@option@1@--qdf@2@option@2@ flag turns on QDF mode, which changes
     some of the defaults described above.  Specifically, in QDF mode,
     by default, stream data is uncompressed, content streams are
     normalized, and encryption is removed.  These defaults can still
@@ -2717,7 +2717,7 @@ outfile.pdf&lt;/option&gt;
     indirect objects, objects are laid out in a less efficient but
     more readable fashion, and the documents are interspersed with
     comments that make it easier for the user to find things and also
-    make it possible for <command>fix-qdf</command> to work properly.
+    make it possible for @1@command@1@fix-qdf@2@command@2@ to work properly.
     QDF mode is intended for people, mostly developers, who wish to
     inspect or modify PDF files in a text editor.  For details, please
     see <xref linkend="ref.qdf"/>.
@@ -2732,7 +2732,7 @@ outfile.pdf&lt;/option&gt;
     file should be given.  The following options are available:
     <variablelist>
      <varlistentry>
-      <term><option>--deterministic-id</option></term>
+      <term>@1@option@1@--deterministic-id@2@option@2@</term>
       <listitem>
        <para>
         Causes generation of a deterministic value for /ID. This
@@ -2748,19 +2748,19 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--static-id</option></term>
+      <term>@1@option@1@--static-id@2@option@2@</term>
       <listitem>
        <para>
         Causes generation of a fixed value for /ID. This is intended
         for testing only. Never use it for production files. If you
         are trying to get the same /ID each time for a given file and
         you are not generating encrypted files, consider using the
-        <option>--deterministic-id</option> option.
+        @1@option@1@--deterministic-id@2@option@2@ option.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--static-aes-iv</option></term>
+      <term>@1@option@1@--static-aes-iv@2@option@2@</term>
       <listitem>
        <para>
         Causes use of a static initialization vector for AES-CBC.
@@ -2772,7 +2772,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--no-original-object-ids</option></term>
+      <term>@1@option@1@--no-original-object-ids@2@option@2@</term>
       <listitem>
        <para>
         Suppresses inclusion of original object ID comments in QDF
@@ -2783,7 +2783,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--show-encryption</option></term>
+      <term>@1@option@1@--show-encryption@2@option@2@</term>
       <listitem>
        <para>
         Shows document encryption parameters.  Also shows the
@@ -2792,16 +2792,16 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--show-encryption-key</option></term>
+      <term>@1@option@1@--show-encryption-key@2@option@2@</term>
       <listitem>
        <para>
         When encryption information is being displayed, as when
-        <option>--check</option> or <option>--show-encryption</option>
+        @1@option@1@--check@2@option@2@ or @1@option@1@--show-encryption@2@option@2@
         is given, display the computed or retrieved encryption key as
         a hexadecimal string. This value is not ordinarily useful to
         users, but it can be used as the argument to
-        <option>--password</option> if the
-        <option>--password-is-hex-key</option> is specified. Note
+        @1@option@1@--password@2@option@2@ if the
+        @1@option@1@--password-is-hex-key@2@option@2@ is specified. Note
         that, when PDF files are encrypted, passwords and other
         metadata are used only to compute an encryption key, and the
         encryption key is what is actually used for encryption. This
@@ -2810,7 +2810,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--check-linearization</option></term>
+      <term>@1@option@1@--check-linearization@2@option@2@</term>
       <listitem>
        <para>
         Checks file integrity and linearization status.
@@ -2818,7 +2818,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--show-linearization</option></term>
+      <term>@1@option@1@--show-linearization@2@option@2@</term>
       <listitem>
        <para>
         Checks and displays all data in the linearization hint tables.
@@ -2826,7 +2826,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--show-xref</option></term>
+      <term>@1@option@1@--show-xref@2@option@2@</term>
       <listitem>
        <para>
         Shows the contents of the cross-reference table in a
@@ -2836,7 +2836,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--show-object=trailer|obj[,gen]</option></term>
+      <term>@1@option@1@--show-object=trailer|obj[,gen]@2@option@2@</term>
       <listitem>
        <para>
         Show the contents of the given object.  This is especially
@@ -2846,20 +2846,20 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--raw-stream-data</option></term>
+      <term>@1@option@1@--raw-stream-data@2@option@2@</term>
       <listitem>
        <para>
-        When used along with the <option>--show-object</option>
+        When used along with the @1@option@1@--show-object@2@option@2@
         option, if the object is a stream, shows the raw stream data
         instead of object's contents.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--filtered-stream-data</option></term>
+      <term>@1@option@1@--filtered-stream-data@2@option@2@</term>
       <listitem>
        <para>
-        When used along with the <option>--show-object</option>
+        When used along with the @1@option@1@--show-object@2@option@2@
         option, if the object is a stream, shows the filtered stream
         data instead of object's contents.  If the stream is filtered
         using filters that qpdf does not support, an error will be
@@ -2868,7 +2868,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--show-npages</option></term>
+      <term>@1@option@1@--show-npages@2@option@2@</term>
       <listitem>
        <para>
         Prints the number of pages in the input file on a line by
@@ -2879,7 +2879,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--show-pages</option></term>
+      <term>@1@option@1@--show-pages@2@option@2@</term>
       <listitem>
        <para>
         Shows the object and generation number for each page
@@ -2890,10 +2890,10 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--with-images</option></term>
+      <term>@1@option@1@--with-images@2@option@2@</term>
       <listitem>
        <para>
-        When used along with <option>--show-pages</option>, also shows
+        When used along with @1@option@1@--show-pages@2@option@2@, also shows
         the object and generation numbers for the image objects on
         each page.  (At present, information about images in shared
         resource dictionaries are not output by this command.  This is
@@ -2902,7 +2902,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--json</option></term>
+      <term>@1@option@1@--json@2@option@2@</term>
       <listitem>
        <para>
         Generate a JSON representation of the file. This is described
@@ -2911,7 +2911,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--json-help</option></term>
+      <term>@1@option@1@--json-help@2@option@2@</term>
       <listitem>
        <para>
         Describe the format of the JSON output.
@@ -2919,7 +2919,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--json-key=key</option></term>
+      <term>@1@option@1@--json-key=key@2@option@2@</term>
       <listitem>
        <para>
         This option is repeatable. If specified, only top-level keys
@@ -2929,7 +2929,7 @@ outfile.pdf&lt;/option&gt;
       </listitem>
       </varlistentry>
      <varlistentry>
-      <term><option>--json-object=trailer|obj[,gen]</option></term>
+      <term>@1@option@1@--json-object=trailer|obj[,gen]@2@option@2@</term>
       <listitem>
        <para>
         This option is repeatable. If specified, only specified
@@ -2940,30 +2940,30 @@ outfile.pdf&lt;/option&gt;
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--check</option></term>
+      <term>@1@option@1@--check@2@option@2@</term>
       <listitem>
        <para>
         Checks file structure and well as encryption, linearization,
         and encoding of stream data.  A file for which
-        <option>--check</option> reports no errors may still have
+        @1@option@1@--check@2@option@2@ reports no errors may still have
         errors in stream data content but should otherwise be
-        structurally sound.  If <option>--check</option> any errors,
+        structurally sound.  If @1@option@1@--check@2@option@2@ any errors,
         qpdf will exit with a status of 2.  There are some recoverable
-        conditions that <option>--check</option> detects.  These are
+        conditions that @1@option@1@--check@2@option@2@ detects.  These are
         issued as warnings instead of errors.  If qpdf finds no errors
         but finds warnings, it will exit with a status of 3 (as of
-        version&nbsp;2.0.4). When <option>--check</option> is combined
+        version&nbsp;2.0.4). When @1@option@1@--check@2@option@2@ is combined
         with other options, checks are always performed before any
         other options are processed. For erroneous files,
-        <option>--check</option> will cause qpdf to attempt to
+        @1@option@1@--check@2@option@2@ will cause qpdf to attempt to
         recover, after which other options are effectively operating
-        on the recovered file. Combining <option>--check</option> with
+        on the recovered file. Combining @1@option@1@--check@2@option@2@ with
         other options in this way can be useful for manually
         recovering severely damaged files. Note that
-        <option>--check</option> produces no output to standard output
+        @1@option@1@--check@2@option@2@ produces no output to standard output
         when everything is valid, so if you are using this to
         programmatically validate files in bulk, it is safe to run
-        without output redirected to <filename>/dev/null</filename>
+        without output redirected to @1@filename@1@/dev/null@2@filename@2@
         and just check for a 0 exit code.
        </para>
       </listitem>
@@ -2971,17 +2971,17 @@ outfile.pdf&lt;/option&gt;
     </variablelist>
    </para>
    <para>
-    The <option>--raw-stream-data</option> and
-    <option>--filtered-stream-data</option> options are ignored unless
-    <option>--show-object</option> is given.  Either of these options
+    The @1@option@1@--raw-stream-data@2@option@2@ and
+    @1@option@1@--filtered-stream-data@2@option@2@ options are ignored unless
+    @1@option@1@--show-object@2@option@2@ is given.  Either of these options
     will cause the stream data to be written to standard output.  In
     order to avoid commingling of stream data with other output, it is
     recommend that these objects not be combined with other
     test/inspection options.
    </para>
    <para>
-    If <option>--filtered-stream-data</option> is given and
-    <option>--normalize-content=y</option> is also given, qpdf will
+    If @1@option@1@--filtered-stream-data@2@option@2@ is given and
+    @1@option@1@--normalize-content=y@2@option@2@ is also given, qpdf will
     attempt to normalize the stream data as if it is a page content
     stream.  This attempt will be made even if it is not a page
     content stream, in which case it will produce unusable results.
@@ -3029,7 +3029,7 @@ outfile.pdf&lt;/option&gt;
     the supplied password is not a valid UTF-8 string, qpdf will fall
     back to the behavior of interpreting the password as a string of
     bytes. If you have old scripts that encrypt files by passing the
-    output of <command>iconv</command> to qpdf, you no longer need to
+    output of @1@command@1@iconv@2@command@2@ to qpdf, you no longer need to
     do that, but if you do, qpdf should still work. The only exception
     would be for the extremely unlikely case of a password that is
     encoded with a single-byte encoding but also happens to be valid
@@ -3037,24 +3037,24 @@ outfile.pdf&lt;/option&gt;
     characters that alternate between accented letters and symbols. In
     the extremely unlikely event that you are intentionally using such
     passwords and qpdf is thwarting you by interpreting them as UTF-8,
-    you can use <option>--password-mode=bytes</option> to suppress
+    you can use @1@option@1@--password-mode=bytes@2@option@2@ to suppress
     qpdf's automatic behavior.
    </para>
    <para>
-    The <option>--password-mode</option> option, as described earlier
+    The @1@option@1@--password-mode@2@option@2@ option, as described earlier
     in this chapter, can be used to change qpdf's interpretation of
     supplied passwords. There are very few reasons to use this option.
     One would be the unlikely case described in the previous paragraph
     in which the supplied password happens to be valid UTF-8 but isn't
     supposed to be UTF-8. Your best bet would be just to provide the
     password as a valid UTF-8 string, but you could also use
-    <option>--password-mode=bytes</option>. Another reason to use
-    <option>--password-mode=bytes</option> would be to intentionally
+    @1@option@1@--password-mode=bytes@2@option@2@. Another reason to use
+    @1@option@1@--password-mode=bytes@2@option@2@ would be to intentionally
     generate PDF files encrypted with passwords that are not properly
     encoded. The qpdf test suite does this to generate invalid files
     for the purpose of testing its password recovery capability. If
     you were trying to create intentionally incorrect files for a
-    similar purposes, the <option>bytes</option> password mode can
+    similar purposes, the @1@option@1@bytes@2@option@2@ password mode can
     enable you to do this.
    </para>
    <para>
@@ -3064,7 +3064,7 @@ outfile.pdf&lt;/option&gt;
     handful of different coding systems and then transcode them to the
     required format. This helps to compensate for the supplied
     password being given in the wrong coding system, such as would
-    happen if you used the <command>iconv</command> workaround that
+    happen if you used the @1@command@1@iconv@2@command@2@ workaround that
     was previously needed. It also generates passwords by doing the
     reverse operation: translating from correct in incorrect encoding
     of the password. This would enable qpdf to decrypt files using
@@ -3075,7 +3075,7 @@ outfile.pdf&lt;/option&gt;
     encrypted files with the password supplied correctly but in the
     wrong coding system. There are no real downsides to this behavior,
     but if you don't want qpdf to do this, you can use the
-    <option>--suppress-password-recovery</option> option. One reason
+    @1@option@1@--suppress-password-recovery@2@option@2@ option. One reason
     to do that is to ensure that you know the exact password that was
     used to encrypt the file.
    </para>
@@ -3094,7 +3094,7 @@ outfile.pdf&lt;/option&gt;
     bytes.
    </para>
    <para>
-    Please note that the <option>--password-is-hex-key</option> option
+    Please note that the @1@option@1@--password-is-hex-key@2@option@2@ option
     is unrelated to all this. This flag bypasses the normal process of
     going from password to encryption string entirely, allowing the
     raw encryption key to be specified directly. This is useful for
@@ -3106,8 +3106,8 @@ outfile.pdf&lt;/option&gt;
  <chapter id="ref.qdf">
   <title>QDF Mode</title>
   <para>
-   In QDF mode, qpdf creates PDF files in what we call <firstterm>QDF
-   form</firstterm>.  A PDF file in QDF form, sometimes called a QDF
+   In QDF mode, qpdf creates PDF files in what we call @1@firstterm@1@QDF
+   form@2@firstterm@2@.  A PDF file in QDF form, sometimes called a QDF
    file, is a completely valid PDF file that has
    <literal>%QDF-1.0</literal> as its third line (after the pdf header
    and binary characters) and has certain other characteristics.  The
@@ -3125,9 +3125,9 @@ outfile.pdf&lt;/option&gt;
    and PDF files are full of offset and length information that makes
    it hard to add or remove data.  A QDF file is organized in a manner
    such that, if edits are kept within certain constraints, the
-   <command>fix-qdf</command> program, distributed with qpdf, is able
+   @1@command@1@fix-qdf@2@command@2@ program, distributed with qpdf, is able
    to restore edited files to a correct state.  The
-   <command>fix-qdf</command> program takes no command-line
+   @1@command@1@fix-qdf@2@command@2@ program takes no command-line
    arguments.  It reads a possibly edited QDF file from standard input
    and writes a repaired file to standard output.
   </para>
@@ -3218,11 +3218,11 @@ outfile.pdf&lt;/option&gt;
    It is not generally practical to remove objects from QDF files
    without messing up object numbering, but if you remove all
    references to an object, you can run qpdf on the file (after
-   running <command>fix-qdf</command>), and qpdf will omit the
+   running @1@command@1@fix-qdf@2@command@2@), and qpdf will omit the
    now-orphaned object.
   </para>
   <para>
-   When <command>fix-qdf</command> is run, it goes through the file
+   When @1@command@1@fix-qdf@2@command@2@ is run, it goes through the file
    and recomputes the following parts of the file:
    <itemizedlist>
     <listitem>
@@ -3262,26 +3262,26 @@ outfile.pdf&lt;/option&gt;
    <title>Using QPDF from C++</title>
    <para>
     The source tree for the qpdf package has an
-    <filename>examples</filename> directory that contains a few
-    example programs.  The <filename>qpdf/qpdf.cc</filename> source
+    @1@filename@1@examples@2@filename@2@ directory that contains a few
+    example programs.  The @1@filename@1@qpdf/qpdf.cc@2@filename@2@ source
     file also serves as a useful example since it exercises almost all
     of the qpdf library's public interface.  The best source of
     documentation on the library itself is reading comments in
-    <filename>include/qpdf/QPDF.hh</filename>,
-    <filename>include/qpdf/QPDFWriter.hh</filename>, and
-    <filename>include/qpdf/QPDFObjectHandle.hh</filename>.
+    @1@filename@1@include/qpdf/QPDF.hh@2@filename@2@,
+    @1@filename@1@include/qpdf/QPDFWriter.hh@2@filename@2@, and
+    @1@filename@1@include/qpdf/QPDFObjectHandle.hh@2@filename@2@.
    </para>
    <para>
-    All header files are installed in the <filename>include/qpdf</filename> directory.  It
+    All header files are installed in the @1@filename@1@include/qpdf@2@filename@2@ directory.  It
     is recommend that you use <literal>#include
     &lt;qpdf/QPDF.hh&gt;</literal> rather than adding
-    <filename>include/qpdf</filename> to your include path.
+    @1@filename@1@include/qpdf@2@filename@2@ to your include path.
    </para>
    <para>
     When linking against the qpdf static library, you may also need to
     specify <literal>-lz -ljpeg</literal> on your link command. If
     your system understands how to read libtool
-    <filename>.la</filename> files, this may not be necessary.
+    @1@filename@1@.la@2@filename@2@ files, this may not be necessary.
    </para>
    <para>
     The qpdf library is safe to use in a multithreaded program, but no
@@ -3305,7 +3305,7 @@ outfile.pdf&lt;/option&gt;
       <para>
        The qpdf library includes a &ldquo;C&rdquo; language interface
        that provides a subset of the overall capabilities. The header
-       file <filename>qpdf/qpdf-c.h</filename> includes information
+       file @1@filename@1@qpdf/qpdf-c.h@2@filename@2@ includes information
        about its use. As long as you use a C++ linker, you can link C
        programs with qpdf and use the C API. For languages that can
        directly load methods from a shared library, the C API can also
@@ -3333,7 +3333,7 @@ outfile.pdf&lt;/option&gt;
      <term>Other Languages</term>
      <listitem>
       <para>
-       Starting with version 8.3.0, the <command>qpdf</command>
+       Starting with version 8.3.0, the @1@command@1@qpdf@2@command@2@
        command-line tool can produce a JSON representation of the PDF
        file's non-content data. This can facilitate interacting
        programmatically with PDF files through qpdf's command line
@@ -3384,13 +3384,13 @@ outfile.pdf&lt;/option&gt;
    In version 10.4, qpdf generates warnings for some (but not all)
    cases of writing files with weak cryptography when invoked from the
    command-line. These warnings can be suppressed using the
-   <option>--allow-weak-crypto</option> option.
+   @1@option@1@--allow-weak-crypto@2@option@2@ option.
   </para>
   <para>
    It is planned for qpdf version 11 to be stricter, making it an
    error to write files with insecure cryptography from the
    command-line tool in most cases without specifying the
-   <option>--allow-weak-crypto</option> flag and also to require
+   @1@option@1@--allow-weak-crypto@2@option@2@ flag and also to require
    explicit steps when using the C++ library to enable use of insecure
    cryptography.
   </para>
@@ -3412,7 +3412,7 @@ outfile.pdf&lt;/option&gt;
   <sect1 id="ref.json-overview">
    <title>Overview</title>
    <para>
-    Beginning with qpdf version 8.3.0, the <command>qpdf</command>
+    Beginning with qpdf version 8.3.0, the @1@command@1@qpdf@2@command@2@
     command-line program can produce a JSON representation of the
     non-content data in a PDF file. It includes a dump in JSON format
     of all objects in the PDF file excluding the content of streams.
@@ -3466,8 +3466,8 @@ outfile.pdf&lt;/option&gt;
       <term>Documentation</term>
       <listitem>
        <para>
-        The <command>qpdf</command> command can be invoked with the
-        <option>--json-help</option> option. This will output a JSON
+        The @1@command@1@qpdf@2@command@2@ command can be invoked with the
+        @1@option@1@--json-help@2@option@2@ option. This will output a JSON
         structure that has the same structure as the JSON output that
         qpdf generates, except that each field in the help output is a
         description of the corresponding field in the JSON output. The
@@ -3585,7 +3585,7 @@ outfile.pdf&lt;/option&gt;
        encoding. In other words, it's best if you don't try to use the
        JSON format to extract binary strings from the PDF file, but if
        you really had to, it could be done. Note that qpdf's
-       <option>--show-object</option> option does not have this
+       @1@option@1@--show-object@2@option@2@ option does not have this
        limitation and will reveal the string as encoded in the original
        file.
       </para>
@@ -3605,9 +3605,9 @@ outfile.pdf&lt;/option&gt;
        While qpdf guarantees that keys present in the help will be
        present in the output, those fields may be null or empty if the
        information is not known or absent in the file. Also, if you
-       specify <option>--json-keys</option>, the keys that are not
+       specify @1@option@1@--json-keys@2@option@2@, the keys that are not
        listed will be excluded entirely except for those that
-       <option>--json-help</option> says are always present.
+       @1@option@1@--json-help@2@option@2@ says are always present.
       </para>
      </listitem>
      <listitem>
@@ -3633,13 +3633,13 @@ outfile.pdf&lt;/option&gt;
        section of the JSON output includes the key
        &ldquo;<literal>filterable</literal>&rdquo;. Note that the
        value of this field may depend on the
-       <option>--decode-level</option> that you invoke qpdf with. The
+       @1@option@1@--decode-level@2@option@2@ that you invoke qpdf with. The
        JSON output includes a top-level key
        &ldquo;<literal>parameters</literal>&rdquo; that indicates the
        decode level used for computing whether a stream was
        filterable. For example, jpeg images will be shown as not
        filterable by default, but they will be shown as filterable if
-       you run <command>qpdf --json --decode-level=all</command>.
+       you run @1@command@1@qpdf --json --decode-level=all@2@command@2@.
       </para>
      </listitem>
     </itemizedlist>
@@ -3748,7 +3748,7 @@ outfile.pdf&lt;/option&gt;
     object from a string representation of the object.  Existing
     instances of <classname>QPDFObjectHandle</classname> can also be
     modified in several ways.  See comments in
-    <filename>QPDFObjectHandle.hh</filename> for details.
+    @1@filename@1@QPDFObjectHandle.hh@2@filename@2@ for details.
    </para>
    <para>
     An instance of <classname>QPDF</classname> is constructed by using
@@ -3785,8 +3785,8 @@ outfile.pdf&lt;/option&gt;
     There are some convenience routines for very common operations
     such as walking the page tree and returning a vector of all page
     objects. For full details, please see the header files
-    <filename>QPDF.hh</filename> and
-    <filename>QPDFObjectHandle.hh</filename>. There are also some
+    @1@filename@1@QPDF.hh@2@filename@2@ and
+    @1@filename@1@QPDFObjectHandle.hh@2@filename@2@. There are also some
     additional helper classes that provide higher level API functions
     for certain document constructions. These are discussed in <xref
     linkend="ref.helper-classes"/>.
@@ -3868,8 +3868,8 @@ outfile.pdf&lt;/option&gt;
     are derived from <classname>QPDFObjectHelper</classname>. For
     details on specific helpers, please see their header files. You
     can find them by looking at
-    <filename>include/qpdf/QPDF*DocumentHelper.hh</filename> and
-    <filename>include/qpdf/QPDF*ObjectHelper.hh</filename>.
+    @1@filename@1@include/qpdf/QPDF*DocumentHelper.hh@2@filename@2@ and
+    @1@filename@1@include/qpdf/QPDF*ObjectHelper.hh@2@filename@2@.
    </para>
    <para>
     In order to avoid creation of circular dependencies, the following
@@ -3999,7 +3999,7 @@ outfile.pdf&lt;/option&gt;
      <listitem>
       <para>
        The <classname>QPDF</classname> class checks the beginning of
-       <filename>a.pdf</filename> for a PDF header. It then reads the
+       @1@filename@1@a.pdf@2@filename@2@ for a PDF header. It then reads the
        cross reference table mentioned at the end of the file,
        ensuring that it is looking before the last
        <literal>%%EOF</literal>. After getting to
@@ -4107,7 +4107,7 @@ outfile.pdf&lt;/option&gt;
    </para>
    <para>
     The <classname>QIntC</classname> namespace, provided by
-    <filename>include/qpdf/QIntC.hh</filename>, implements safe
+    @1@filename@1@include/qpdf/QIntC.hh@2@filename@2@, implements safe
     functions for converting between integer types. These functions do
     range checking and throw a <type>std::range_error</type>, which is
     subclass of <type>std::runtime_error</type>, if conversion from one
@@ -4263,7 +4263,7 @@ outfile.pdf&lt;/option&gt;
     dependency on Microsoft's cryptography API. You can also supply
     your own random data provider. For details on how to do this,
     please refer to the top-level README.md file in the source
-    distribution and to comments in <filename>QUtil.hh</filename>.
+    distribution and to comments in @1@filename@1@QUtil.hh@2@filename@2@.
    </para>
   </sect1>
   <sect1 id="ref.adding-and-remove-pages">
@@ -4276,7 +4276,7 @@ outfile.pdf&lt;/option&gt;
     <literal>/Pages</literal> tree down to individual pages and
     manipulation of the <literal>/Pages</literal> tree itself.  For
     details, see <function>addPage</function> and surrounding methods
-    in <filename>QPDF.hh</filename>.
+    in @1@filename@1@QPDF.hh@2@filename@2@.
    </para>
   </sect1>
   <sect1 id="ref.reserved-objects">
@@ -4294,7 +4294,7 @@ outfile.pdf&lt;/option&gt;
     <classname>QPDF</classname> object prior to version 3.0 would be
     to add the new objects first and then make them refer to each
     other after adding them.  Now it is possible to create a
-    <firstterm>reserved object</firstterm> using
+    @1@firstterm@1@reserved object@2@firstterm@2@ using
     <function>QPDFObjectHandle::newReserved</function>.  This is an
     indirect object that stays &ldquo;unresolved&rdquo; even if it is
     queried for its type.  So now, if you want to create a set of
@@ -4307,7 +4307,7 @@ outfile.pdf&lt;/option&gt;
     when copying objects from other PDF files, as discussed in <xref
     linkend="ref.foreign-objects"/>.  For an example of how to use
     reserved objects, search for <function>newReserved</function> in
-    <filename>test_driver.cc</filename> in qpdf's sources.
+    @1@filename@1@test_driver.cc@2@filename@2@ in qpdf's sources.
    </para>
   </sect1>
   <sect1 id="ref.foreign-objects">
@@ -4316,10 +4316,10 @@ outfile.pdf&lt;/option&gt;
     Version 3.0 of qpdf introduced the ability to copy objects into a
     <classname>QPDF</classname> object from a different
     <classname>QPDF</classname> object, which we refer to as
-    <firstterm>foreign objects</firstterm>. This allows arbitrary
+    @1@firstterm@1@foreign objects@2@firstterm@2@. This allows arbitrary
     merging of PDF files. The &ldquo;from&rdquo;
     <classname>QPDF</classname> object must remain valid after the
-    copy as discussed in the note below. The <command>qpdf</command>
+    copy as discussed in the note below. The @1@command@1@qpdf@2@command@2@
     command-line tool provides limited support for basic page
     selection, including merging in pages from other files, but the
     library's API makes it possible to implement arbitrarily complex
@@ -4447,7 +4447,7 @@ outfile.pdf&lt;/option&gt;
         </listitem>
         <listitem>
          <para>
-          Write <literal><replaceable>n</replaceable> 0 obj</literal>.
+          Write <literal>@1@replaceable@1@n@2@replaceable@2@ 0 obj</literal>.
          </para>
         </listitem>
         <listitem>
@@ -4540,7 +4540,7 @@ outfile.pdf&lt;/option&gt;
     pipeline may be an end-of-the-line pipeline that does something
     like store its output to a file or a memory buffer ignoring a
     successor.  For additional details, look at
-    <filename>Pipeline.hh</filename>.
+    @1@filename@1@Pipeline.hh@2@filename@2@.
    </para>
    <para>
     <classname>QPDF</classname> can read raw or filtered streams.
@@ -4558,7 +4558,7 @@ outfile.pdf&lt;/option&gt;
    <para>
     For general information about how to access instances of
     <classname>QPDFObjectHandle</classname>, please see the comments
-    in <filename>QPDFObjectHandle.hh</filename>. Search for
+    in @1@filename@1@QPDFObjectHandle.hh@2@filename@2@. Search for
     &ldquo;Accessor methods&rdquo;. This section provides a more
     in-depth discussion of the behavior and the rationale for the
     behavior.
@@ -4655,9 +4655,9 @@ outfile.pdf&lt;/option&gt;
    <para>
     To avoid the incestuous problem of having the qpdf library
     validate its own linearized files, we have a special linearized
-    file checking mode which can be invoked via <command>qpdf
-    --check-linearization</command> (or <command>qpdf
-    --check</command>).  This mode reads the linearization parameter
+    file checking mode which can be invoked via @1@command@1@qpdf
+    --check-linearization@2@command@2@ (or @1@command@1@qpdf
+    --check@2@command@2@).  This mode reads the linearization parameter
     dictionary and the hint streams and validates that object
     ordering, parameters, and hint stream contents are correct.  The
     validation code was first tested against linearized files created
@@ -4674,10 +4674,10 @@ outfile.pdf&lt;/option&gt;
     in the <literal>/Pages</literal> tree).  We also have to know
     which objects refer to which other objects, being concerned with
     page boundaries and a few other cases.  We refer to this part of
-    preparing the PDF file as <firstterm>optimization</firstterm>,
+    preparing the PDF file as @1@firstterm@1@optimization@2@firstterm@2@,
     discussed in <xref linkend="ref.optimization"/>.  Note the, in
-    this context, the term <firstterm>optimization</firstterm> is a
-    qpdf term, and the term <firstterm>linearization</firstterm> is a
+    this context, the term @1@firstterm@1@optimization@2@firstterm@2@ is a
+    qpdf term, and the term @1@firstterm@1@linearization@2@firstterm@2@ is a
     term from the PDF specification.  Do not be confused by the fact
     that many applications refer to linearization as optimization or
     web optimization.
@@ -4716,14 +4716,14 @@ outfile.pdf&lt;/option&gt;
    </para>
    <para>
     We refer to the process of enforcing these constraints as
-    <firstterm>optimization</firstterm>.  As mentioned above, note
+    @1@firstterm@1@optimization@2@firstterm@2@.  As mentioned above, note
     that some applications refer to linearization as optimization.
     Although this optimization was initially motivated by the need to
     create linearized files, we are using these terms separately.
    </para>
    <para>
     PDF file optimization is implemented in the
-    <filename>QPDF_optimization.cc</filename> source file.  That file
+    @1@filename@1@QPDF_optimization.cc@2@filename@2@ source file.  That file
     is richly commented and serves as the primary reference for the
     optimization process.
    </para>
@@ -4857,11 +4857,11 @@ outfile.pdf&lt;/option&gt;
   <sect1 id="ref.linearization-debugging">
    <title>Debugging Note</title>
    <para>
-    The <command>qpdf --show-linearization</command> command can show
+    The @1@command@1@qpdf --show-linearization@2@command@2@ command can show
     the complete contents of linearization hint streams.  To look at
     the raw data, you can extract the filtered contents of the
-    linearization hint tables using <command>qpdf --show-object=n
-    --filtered-stream-data</command>.  Then, to convert this into a
+    linearization hint tables using @1@command@1@qpdf --show-object=n
+    --filtered-stream-data@2@command@2@.  Then, to convert this into a
     bit stream (since linearization tables are bit streams written
     without regard to byte boundaries), you can pipe the resulting
     data through the following perl code:
@@ -5022,7 +5022,7 @@ print &quot;\n&quot;;
      <listitem>
       <para>
        <literal>/Index</literal> (optional): value
-       <literal>[<replaceable>n count</replaceable> ...]</literal>
+       <literal>[@1@replaceable@1@n count@2@replaceable@2@ ...]</literal>
        used to determine which objects' information is stored in this
        stream.  The default is <literal>[0 /Size]</literal>.
       </para>
@@ -5030,7 +5030,7 @@ print &quot;\n&quot;;
      <listitem>
       <para>
        <literal>/Prev</literal>: value
-       <replaceable>offset</replaceable>: byte offset of previous xref
+       @1@replaceable@1@offset@2@replaceable@2@: byte offset of previous xref
        stream (same as <literal>/Prev</literal> in the trailer
        dictionary)
       </para>
@@ -5127,8 +5127,8 @@ print &quot;\n&quot;;
    <title>Implementation Notes</title>
    <para>
     There are three modes for writing object streams:
-    <option>disable</option>, <option>preserve</option>, and
-    <option>generate</option>.  In disable mode, we do not generate
+    @1@option@1@disable@2@option@2@, @1@option@1@preserve@2@option@2@, and
+    @1@option@1@generate@2@option@2@.  In disable mode, we do not generate
     any object streams, and we also generate an xref table rather than
     xref streams.  This can be used to generate PDF files that are
     viewable with older readers.  In preserve mode, we write object
@@ -5139,7 +5139,7 @@ print &quot;\n&quot;;
     objects that are allowed in object streams together in sets of no
     more than 100 objects.  We also ensure that the PDF version is at
     least 1.5 in generate mode, but we preserve the version header in
-    the other modes.  The default is <option>preserve</option>.
+    the other modes.  The default is @1@option@1@preserve@2@option@2@.
    </para>
    <para>
     We do not support creation of hybrid files.  When we write files,
@@ -5152,7 +5152,7 @@ print &quot;\n&quot;;
   <title>Release Notes</title>
   <para>
    For a detailed list of changes, please see the file
-   <filename>ChangeLog</filename> in the source distribution.
+   @1@filename@1@ChangeLog@2@filename@2@ in the source distribution.
   </para>
   <variablelist>
 <!--
@@ -5215,7 +5215,7 @@ print &quot;\n&quot;;
           These warnings now have an error code of
           <literal>qpdf_e_object</literal> instead of
           <literal>qpdf_e_damaged_pdf</literal>. Also, comments have
-          been added to <filename>QPDFObjectHandle.hh</filename> to
+          been added to @1@filename@1@QPDFObjectHandle.hh@2@filename@2@ to
           explain in more detail what the behavior is. See <xref
           linkend="ref.object-accessors"/> for a more in-depth
           discussion.
@@ -5225,7 +5225,7 @@ print &quot;\n&quot;;
          <para>
           Overhaul error handling for the object handle functions in
           the C API. See comments in the &ldquo;Object handling&rdquo;
-          section of <filename>include/qpdf/qpdf-c.h</filename> for
+          section of @1@filename@1@include/qpdf/qpdf-c.h@2@filename@2@ for
           details. In particular, exceptions thrown by the underlying
           C++ code when calling object accessors are caught and
           converted into errors. The errors can be trapped by
@@ -5280,7 +5280,7 @@ print &quot;\n&quot;;
        <itemizedlist>
         <listitem>
          <para>
-          From the qpdf CLI, the <option>--allow-weak-crypto</option>
+          From the qpdf CLI, the @1@option@1@--allow-weak-crypto@2@option@2@
           is now required to suppress a warning when explicitly
           creating PDF files using RC4 encryption. While qpdf will
           always retain the ability to read and write such files,
@@ -5314,7 +5314,7 @@ print &quot;\n&quot;;
         <listitem>
          <para>
           Fix crash that could occur under certain conditions when
-          using <option>--pages</option> with files that had form
+          using @1@option@1@--pages@2@option@2@ with files that had form
           fields.
          </para>
         </listitem>
@@ -5355,7 +5355,7 @@ print &quot;\n&quot;;
        <itemizedlist>
         <listitem>
          <para>
-          Improve diagnostics around parsing <option>--pages</option>
+          Improve diagnostics around parsing @1@option@1@--pages@2@option@2@
           command-line options
          </para>
         </listitem>
@@ -5390,7 +5390,7 @@ print &quot;\n&quot;;
          <para>
           When generating a file while preserving object streams,
           unreferenced objects are correctly removed unless
-          <option>--preserve-unreferenced</option> is specified.
+          @1@option@1@--preserve-unreferenced@2@option@2@ is specified.
          </para>
         </listitem>
        </itemizedlist>
@@ -5405,7 +5405,7 @@ print &quot;\n&quot;;
           When adding a page that already exists, make a shallow copy
           instead of throwing an exception. This makes the library
           behavior consistent with the CLI behavior. See
-          <filename>ChangeLog</filename> for additional notes.
+          @1@filename@1@ChangeLog@2@filename@2@ for additional notes.
          </para>
         </listitem>
        </itemizedlist>
@@ -5495,7 +5495,7 @@ print &quot;\n&quot;;
           are in methods most people would never call and that will
           hopefully be superseded by higher-level interfaces for
           handling page copies. Please see the
-          <filename>ChangeLog</filename> file for details.
+          @1@filename@1@ChangeLog@2@filename@2@ file for details.
          </para>
         </listitem>
         <listitem>
@@ -5523,10 +5523,10 @@ print &quot;\n&quot;;
          <para>
           Operations that work on combining pages are much better
           about protecting form fields. In particular,
-          <option>--split-pages</option> and <option>--pages</option>
+          @1@option@1@--split-pages@2@option@2@ and @1@option@1@--pages@2@option@2@
           now preserve interaction form functionality by copying the
           relevant form field information from the original files.
-          Additionally, if you use <option>--pages</option> to select
+          Additionally, if you use @1@option@1@--pages@2@option@2@ to select
           only some pages from the original input file, unused form
           fields are removed, which prevents lots of unused
           annotations from being retained.
@@ -5534,11 +5534,11 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          By default, <command>qpdf</command> no longer allows
+          By default, @1@command@1@qpdf@2@command@2@ no longer allows
           creation of encrypted PDF files whose user password is
           non-empty and owner password is empty when a 256-bit key is
-          in use. The <option>--allow-insecure</option> option,
-          specified inside the <option>--encrypt</option> options,
+          in use. The @1@option@1@--allow-insecure@2@option@2@ option,
+          specified inside the @1@option@1@--encrypt@2@option@2@ options,
           allows creation of such files. Behavior changes in the CLI
           are avoided when possible, but an exception was made here
           because this is security-related. qpdf must always allow
@@ -5609,7 +5609,7 @@ print &quot;\n&quot;;
         <listitem>
          <para>
           Page splitting and merging operations, as well as
-          <option>--flatten-rotation</option>, are better behaved
+          @1@option@1@--flatten-rotation@2@option@2@, are better behaved
           with respect to annotations and interactive form fields. In
           most cases, interactive form field functionality and proper
           formatting and functionality of annotations is preserved by
@@ -5626,12 +5626,12 @@ print &quot;\n&quot;;
         <listitem>
          <para>
           The option
-          <option>--password-file=<replaceable>filename</replaceable></option>
+          @1@option@1@--password-file=@1@replaceable@1@filename@2@replaceable@2@@2@option@2@
           can now be used to read the decryption password from a file.
           You can use <literal>-</literal> as the file name to read
           the password from standard input. This is an easier/more
           obvious way to read passwords from files or standard input
-          than using <option>@file</option> for this purpose.
+          than using @1@option@1@@file@2@option@2@ for this purpose.
          </para>
         </listitem>
         <listitem>
@@ -5649,15 +5649,15 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          Add numeric option to <option>--collate</option>. If
-          <option>--collate=<replaceable>n</replaceable></option> is
-          given, take pages in groups of <replaceable>n</replaceable>
+          Add numeric option to @1@option@1@--collate@2@option@2@. If
+          @1@option@1@--collate=@1@replaceable@1@n@2@replaceable@2@@2@option@2@ is
+          given, take pages in groups of @1@replaceable@1@n@2@replaceable@2@
           from the given files.
          </para>
         </listitem>
         <listitem>
          <para>
-          It is now valid to provide <option>--rotate=0</option> to
+          It is now valid to provide @1@option@1@--rotate=0@2@option@2@ to
           clear rotation from a page.
          </para>
         </listitem>
@@ -5672,7 +5672,7 @@ print &quot;\n&quot;;
          <para>
           This release includes numerous additions to the API. Not all
           changes are listed here. Please see the
-          <filename>ChangeLog</filename> file in the source
+          @1@filename@1@ChangeLog@2@filename@2@ file in the source
           distribution for a comprehensive list. Highlights appear
           below.
          </para>
@@ -5683,8 +5683,8 @@ print &quot;\n&quot;;
           <function>QPDFObjectHandle::aitems()</function> that enable
           C++-style iteration, including range-for iteration, over
           dictionary and array QPDFObjectHandles. See comments in
-          <filename>include/qpdf/QPDFObjectHandle.hh</filename> and
-          <filename>examples/pdf-name-number-tree.cc</filename> for
+          @1@filename@1@include/qpdf/QPDFObjectHandle.hh@2@filename@2@ and
+          @1@filename@1@examples/pdf-name-number-tree.cc@2@filename@2@ for
           details.
          </para>
         </listitem>
@@ -5703,7 +5703,7 @@ print &quot;\n&quot;;
           <classname>QPDFFileSpecObjectHelper</classname>, and
           <classname>QPDFEFStreamObjectHelper</classname>. See their
           respective headers for details and
-          <filename>examples/pdf-attach-file.cc</filename> for an
+          @1@filename@1@examples/pdf-attach-file.cc@2@filename@2@ for an
           example.
          </para>
         </listitem>
@@ -5714,7 +5714,7 @@ print &quot;\n&quot;;
           <classname>QPDF</classname> pointer as context so that it
           can parse strings containing indirect object references.
           This is illustrated in
-          <filename>examples/pdf-attach-file.cc</filename>.
+          @1@filename@1@examples/pdf-attach-file.cc@2@filename@2@.
          </para>
         </listitem>
         <listitem>
@@ -5742,13 +5742,13 @@ print &quot;\n&quot;;
          <para>
           The <classname>QPDFMatrix</classname> class, formerly a
           private, internal class, has been added to the public API.
-          See <filename>include/qpdf/QPDFMatrix.hh</filename> for
+          See @1@filename@1@include/qpdf/QPDFMatrix.hh@2@filename@2@ for
           details. This class is for working with transformation
           matrices. Some methods in
           <classname>QPDFPageObjectHelper</classname> make use of this
           to make information about transformation matrices available.
           For an example, see
-          <filename>examples/pdf-overlay-page.cc</filename>.
+          @1@filename@1@examples/pdf-overlay-page.cc@2@filename@2@.
          </para>
         </listitem>
         <listitem>
@@ -5799,7 +5799,7 @@ print &quot;\n&quot;;
        <itemizedlist>
         <listitem>
          <para>
-	  The <option>--flatten-rotation</option> option applies
+	  The @1@option@1@--flatten-rotation@2@option@2@ option applies
           transformations to any annotations that may be on the page.
          </para>
         </listitem>
@@ -5843,7 +5843,7 @@ print &quot;\n&quot;;
        <itemizedlist>
         <listitem>
          <para>
-          Add <option>--flatten-rotation</option> command-line option,
+          Add @1@option@1@--flatten-rotation@2@option@2@ command-line option,
           which causes all pages that are rotated using parameters in
           the page's dictionary to instead be identically rotated in
           the page's contents. The change is not user-visible for
@@ -5867,7 +5867,7 @@ print &quot;\n&quot;;
           including those used by <classname>QPDFWriter</classname>,
           can decode streams with filters not directly supported by
           the library. The example
-          <filename>examples/pdf-custom-filter.cc</filename>
+          @1@filename@1@examples/pdf-custom-filter.cc@2@filename@2@
           illustrates how to use this capability.
          </para>
         </listitem>
@@ -5886,7 +5886,7 @@ print &quot;\n&quot;;
           Enhance several methods in
           <classname>QPDFPageObjectHelper</classname> to work with
           form XObjects as well as pages, as noted in comments. See
-          <filename>ChangeLog</filename> for a full list.
+          @1@filename@1@ChangeLog@2@filename@2@ for a full list.
          </para>
         </listitem>
         <listitem>
@@ -6017,7 +6017,7 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          When extracting pages, the <command>qpdf</command> CLI only
+          When extracting pages, the @1@command@1@qpdf@2@command@2@ CLI only
           removes unreferenced resources from the pages that are being
           kept, resulting in a significant performance improvement
           when extracting small numbers of pages from large, complex
@@ -6110,7 +6110,7 @@ print &quot;\n&quot;;
         <listitem>
          <para>
           When concatenating content streams, as with
-          <option>--coalesce-contents</option>, there were cases in
+          @1@option@1@--coalesce-contents@2@option@2@, there were cases in
           which qpdf would merge two lexical tokens together, creating
           invalid results. A newline is now inserted between
           merged content streams if one is not already present.
@@ -6137,7 +6137,7 @@ print &quot;\n&quot;;
         <listitem>
          <para>
           Fix several instances in which warnings were not suppressed
-          in spite of <option>--no-warn</option> and/or errors or
+          in spite of @1@option@1@--no-warn@2@option@2@ and/or errors or
           warnings were written to standard output rather than
           standard error.
          </para>
@@ -6146,7 +6146,7 @@ print &quot;\n&quot;;
          <para>
           Fixed a memory leak that could occur under specific
           circumstances when
-          <option>--object-streams=generate</option> was used.
+          @1@option@1@--object-streams=generate@2@option@2@ was used.
          </para>
         </listitem>
         <listitem>
@@ -6164,10 +6164,10 @@ print &quot;\n&quot;;
        <itemizedlist>
         <listitem>
          <para>
-          New option <option>--warning-exit-0</option> causes qpdf to
+          New option @1@option@1@--warning-exit-0@2@option@2@ causes qpdf to
           exit with a status of <literal>0</literal> rather than
           <literal>3</literal> if there are warnings but no errors.
-          Combine with <option>--no-warn</option> to completely ignore
+          Combine with @1@option@1@--no-warn@2@option@2@ to completely ignore
           warnings.
          </para>
         </listitem>
@@ -6192,8 +6192,8 @@ print &quot;\n&quot;;
        <itemizedlist>
         <listitem>
          <para>
-          The option <option>--disable-rpath</option> is now supported
-          by qpdf's <command>./configure</command> script. Some
+          The option @1@option@1@--disable-rpath@2@option@2@ is now supported
+          by qpdf's @1@command@1@./configure@2@command@2@ script. Some
           distributions' packaging standards recommended the use of
           this option.
          </para>
@@ -6205,7 +6205,7 @@ print &quot;\n&quot;;
           an autoconf test. If you are using your own build system,
           you will need to provide a value for
           <literal>LL_FMT</literal> in
-          <filename>libqpdf/qpdf/qpdf-config.h</filename>, which would
+          @1@filename@1@libqpdf/qpdf/qpdf-config.h@2@filename@2@, which would
           typically be <literal>&quot;%lld&quot;</literal> or, for
           some Windows compilers, <literal>&quot;%I64d&quot;</literal>.
          </para>
@@ -6295,7 +6295,7 @@ print &quot;\n&quot;;
        <itemizedlist>
         <listitem>
          <para>
-          Improve the <filename>pdf-invert-images</filename> example
+          Improve the @1@filename@1@pdf-invert-images@2@filename@2@ example
           to avoid having to load all the images into RAM at the same
           time.
          </para>
@@ -6386,14 +6386,14 @@ print &quot;\n&quot;;
           object indicating whether it is a stream and, if so, what
           its length and filters are. Without this, it was not
           possible to tell conclusively from the JSON output alone
-          whether or not an object was a stream. Run <command>qpdf
-          --json-help</command> for details.
+          whether or not an object was a stream. Run @1@command@1@qpdf
+          --json-help@2@command@2@ for details.
          </para>
         </listitem>
         <listitem>
          <para>
           Add new option
-          <option>--remove-unreferenced-resources</option> which takes
+          @1@option@1@--remove-unreferenced-resources@2@option@2@ which takes
           <literal>auto</literal>, <literal>yes</literal>, or
           <literal>no</literal> as arguments. The new
           <literal>auto</literal> mode, which is the default, performs
@@ -6408,21 +6408,21 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          The <option>--preserve-unreferenced-resources</option> is
+          The @1@option@1@--preserve-unreferenced-resources@2@option@2@ is
           now just a synonym for
-          <option>--remove-unreferenced-resources=no</option>.
+          @1@option@1@--remove-unreferenced-resources=no@2@option@2@.
          </para>
         </listitem>
         <listitem>
          <para>
           If the <literal>QPDF_EXECUTABLE</literal> environment
-          variable is set when invoking <command>qpdf
-          --bash-completion</command> or <command>qpdf
-          --zsh-completion</command>, the completion command that it
+          variable is set when invoking @1@command@1@qpdf
+          --bash-completion@2@command@2@ or @1@command@1@qpdf
+          --zsh-completion@2@command@2@, the completion command that it
           outputs will refer to qpdf using the value of that variable
-          rather than what <command>qpdf</command> determines its
+          rather than what @1@command@1@qpdf@2@command@2@ determines its
           executable path to be. This can be useful when wrapping
-          <command>qpdf</command> with a script, working with a
+          @1@command@1@qpdf@2@command@2@ with a script, working with a
           version in the source tree, using an AppImage, or other
           situations where there is some indirection.
          </para>
@@ -6582,8 +6582,8 @@ print &quot;\n&quot;;
        <itemizedlist>
         <listitem>
          <para>
-          Added options <option>--is-encrypted</option> and
-          <option>--requires-password</option> for testing whether a
+          Added options @1@option@1@--is-encrypted@2@option@2@ and
+          @1@option@1@--requires-password@2@option@2@ for testing whether a
           file is encrypted or requires a password other than the
           supplied (or empty) password. These communicate via exit
           status, making them useful for shell scripts. They also work
@@ -6597,9 +6597,9 @@ print &quot;\n&quot;;
           Added <literal>encrypt</literal> key to JSON options. With
           the exception of the reconstructed user password for older
           encryption formats, this provides the same information as
-          <option>--show-encryption</option> but in a consistent,
-          parseable format. See output of <command>qpdf
-          --json-help</command> for details.
+          @1@option@1@--show-encryption@2@option@2@ but in a consistent,
+          parseable format. See output of @1@command@1@qpdf
+          --json-help@2@command@2@ for details.
          </para>
         </listitem>
        </itemizedlist>
@@ -6613,8 +6613,8 @@ print &quot;\n&quot;;
          <para>
           In QDF mode, be sure not to write more than one XRef stream
           to a file, even when
-          <option>--preserve-unreferenced</option> is used.
-          <command>fix-qdf</command> assumes that there is only one
+          @1@option@1@--preserve-unreferenced@2@option@2@ is used.
+          @1@command@1@fix-qdf@2@command@2@ assumes that there is only one
           XRef stream, and that it appears at the end of the file.
          </para>
         </listitem>
@@ -6711,7 +6711,7 @@ print &quot;\n&quot;;
        <itemizedlist>
         <listitem>
          <para>
-          Addition of the <option>--show-crypto</option> option in
+          Addition of the @1@option@1@--show-crypto@2@option@2@ option in
           support of selectable crypto providers, as described in
           <xref linkend="ref.crypto"/>.
          </para>
@@ -6726,7 +6726,7 @@ print &quot;\n&quot;;
         <listitem>
          <para>
           Fix shell wildcard expansion behavior (<literal>*</literal>
-          and <literal>?</literal>) of the <command>qpdf.exe</command>
+          and <literal>?</literal>) of the @1@command@1@qpdf.exe@2@command@2@
           as built my MSVC.
          </para>
         </listitem>
@@ -6747,7 +6747,7 @@ print &quot;\n&quot;;
         <listitem>
          <para>
           Fix the name of the temporary file used by
-          <option>--replace-input</option> so that it doesn't require
+          @1@option@1@--replace-input@2@option@2@ so that it doesn't require
           path splitting and works with paths include directories.
          </para>
         </listitem>
@@ -6861,29 +6861,29 @@ print &quot;\n&quot;;
        <itemizedlist>
         <listitem>
          <para>
-          The <option>--replace-input</option> option may be given in
+          The @1@option@1@--replace-input@2@option@2@ option may be given in
           place of an output file name. This causes qpdf to overwrite
           the input file with the output. See the description of
-          <option>--replace-input</option> in <xref
+          @1@option@1@--replace-input@2@option@2@ in <xref
           linkend="ref.basic-options"/> for more details.
          </para>
         </listitem>
         <listitem>
          <para>
-          The <option>--recompress-flate</option> instructs
-          <command>qpdf</command> to recompress streams that are
+          The @1@option@1@--recompress-flate@2@option@2@ instructs
+          @1@command@1@qpdf@2@command@2@ to recompress streams that are
           already compressed with <literal>/FlateDecode</literal>.
-          Useful with <option>--compression-level</option>.
+          Useful with @1@option@1@--compression-level@2@option@2@.
          </para>
         </listitem>
         <listitem>
          <para>
           The
-          <option>--compression-level=<replaceable>level</replaceable></option>
+          @1@option@1@--compression-level=@1@replaceable@1@level@2@replaceable@2@@2@option@2@
           sets the zlib compression level used for any streams
           compressed by <literal>/FlateDecode</literal>. Most
           effective when combined with
-          <option>--recompress-flate</option>.
+          @1@option@1@--recompress-flate@2@option@2@.
          </para>
         </listitem>
        </itemizedlist>
@@ -6896,7 +6896,7 @@ print &quot;\n&quot;;
         <listitem>
          <para>
           A new namespace <classname>QIntC</classname>, provided by
-          <filename>qpdf/QIntC.hh</filename>, provides safe conversion
+          @1@filename@1@qpdf/QIntC.hh@2@filename@2@, provides safe conversion
           methods between different integer types. These conversion
           methods do range checking to ensure that the cast can be
           performed with no loss of information. Every use of
@@ -6969,9 +6969,9 @@ print &quot;\n&quot;;
           and <function>QPDF::ownerPasswordMatched</function> have
           been added to enable a caller to determine whether the
           supplied password was the user password, the owner password,
-          or both. This information is also displayed by <command>qpdf
-          --show-encryption</command> and <command>qpdf
-          --check</command>.
+          or both. This information is also displayed by @1@command@1@qpdf
+          --show-encryption@2@command@2@ and @1@command@1@qpdf
+          --check@2@command@2@.
          </para>
         </listitem>
         <listitem>
@@ -7026,7 +7026,7 @@ print &quot;\n&quot;;
           PDF 1.2 and above, are properly handled by the library: a
           warning is generated, and the name token is properly
           preserved, even if invalid, in the output. See
-          <filename>ChangeLog</filename> for a more complete
+          @1@filename@1@ChangeLog@2@filename@2@ for a more complete
           description of this change.
          </para>
         </listitem>
@@ -7047,16 +7047,16 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          When <command>qpdf --check</command> or <command>qpdf
-          --check-linearization</command> encounters a file with
+          When @1@command@1@qpdf --check@2@command@2@ or @1@command@1@qpdf
+          --check-linearization@2@command@2@ encounters a file with
           linearization warnings but not errors, it now properly exits
           with exit code 3 instead of 2.
          </para>
         </listitem>
         <listitem>
          <para>
-          The <option>--completion-bash</option> and
-          <option>--completion-zsh</option> options now work properly
+          The @1@option@1@--completion-bash@2@option@2@ and
+          @1@option@1@--completion-zsh@2@option@2@ options now work properly
           when qpdf is invoked as an AppImage.
          </para>
         </listitem>
@@ -7087,7 +7087,7 @@ print &quot;\n&quot;;
         <listitem>
          <para>
           On platforms that support it, qpdf now builds with
-          <option>-fvisibility=hidden</option>. If you build qpdf with
+          @1@option@1@-fvisibility=hidden@2@option@2@. If you build qpdf with
           your own build system, this is now safe to use. This
           prevents methods that are not part of the public API from
           being exported by the shared library, and makes qpdf's ELF
@@ -7112,7 +7112,7 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          QPDF's <command>make install</command> target explicitly
+          QPDF's @1@command@1@make install@2@command@2@ target explicitly
           specifies the mode to use when installing files instead of
           relying the user's umask. It was previously doing this for
           some files but not others.
@@ -7120,9 +7120,9 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          If <command>pkg-config</command> is available, use it to
-          locate <filename>libjpeg</filename> and
-          <filename>zlib</filename> dependencies, falling back on old
+          If @1@command@1@pkg-config@2@command@2@ is available, use it to
+          locate @1@filename@1@libjpeg@2@filename@2@ and
+          @1@filename@1@zlib@2@filename@2@ dependencies, falling back on old
           behavior if unsuccessful.
          </para>
         </listitem>
@@ -7170,7 +7170,7 @@ print &quot;\n&quot;;
        <itemizedlist>
         <listitem>
          <para>
-          When <command>qpdf --version</command> is run, it will
+          When @1@command@1@qpdf --version@2@command@2@ is run, it will
           detect if the qpdf CLI was built with a different version of
           qpdf than the library, which may indicate a problem with the
           installation.
@@ -7178,9 +7178,9 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-	  New option <option>--remove-page-labels</option> will remove page
+	  New option @1@option@1@--remove-page-labels@2@option@2@ will remove page
           labels before generating output. This used to happen if you
-          ran <command>qpdf --empty --pages .. --</command>, but the
+          ran @1@command@1@qpdf --empty --pages .. --@2@command@2@, but the
           behavior changed in qpdf 8.3.0. This option enables people
           who were relying on the old behavior to get it again.
          </para>
@@ -7188,7 +7188,7 @@ print &quot;\n&quot;;
         <listitem>
          <para>
           New option
-          <option>--keep-files-open-threshold=<replaceable>count</replaceable></option>
+          @1@option@1@--keep-files-open-threshold=@1@replaceable@1@count@2@replaceable@2@@2@option@2@
           can be used to override number of files that qpdf will use
           to trigger the behavior of not keeping all files open when
           merging files. This may be necessary if your system allows
@@ -7222,7 +7222,7 @@ print &quot;\n&quot;;
         <listitem>
          <para>
 	  Revert change that included preservation of outlines
-	  (bookmarks) in <option>--split-pages</option>. The way it
+	  (bookmarks) in @1@option@1@--split-pages@2@option@2@. The way it
 	  was implemented in 8.3.0 and 8.4.0 caused a very significant
 	  degradation of performance for splitting certain files. A
 	  future release of qpdf may re-introduce the behavior in a
@@ -7305,20 +7305,20 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          New options <option>--externalize-inline-images</option>,
-          <option>--ii-min-bytes</option>, and
-          <option>--keep-inline-images</option> control qpdf's
+          New options @1@option@1@--externalize-inline-images@2@option@2@,
+          @1@option@1@--ii-min-bytes@2@option@2@, and
+          @1@option@1@--keep-inline-images@2@option@2@ control qpdf's
           handling of inline images and possible conversion of them to
           regular images. By default,
-          <option>--optimize-images</option> now also applies to
+          @1@option@1@--optimize-images@2@option@2@ now also applies to
           inline images. These options are discussed in <xref
           linkend="ref.advanced-transformation"/>.
          </para>
         </listitem>
         <listitem>
          <para>
-          Add options <option>--overlay</option> and
-          <option>--underlay</option> for overlaying or underlaying
+          Add options @1@option@1@--overlay@2@option@2@ and
+          @1@option@1@--underlay@2@option@2@ for overlaying or underlaying
           pages of other files onto output pages. See <xref
           linkend="ref.overlay-underlay"/> for details.
          </para>
@@ -7330,14 +7330,14 @@ print &quot;\n&quot;;
           any non-ASCII characters, qpdf will try a number of
           alternative passwords to try to compensate for possible
           character encoding errors. This behavior can be suppressed
-          with the <option>--suppress-password-recovery</option>
+          with the @1@option@1@--suppress-password-recovery@2@option@2@
           option. See <xref linkend="ref.unicode-passwords"/> for a
           full discussion.
          </para>
         </listitem>
         <listitem>
          <para>
-          Add the <option>--password-mode</option> option to fine-tune
+          Add the @1@option@1@--password-mode@2@option@2@ option to fine-tune
           how qpdf interprets password arguments, especially when they
           contain non-ASCII characters. See <xref
           linkend="ref.unicode-passwords"/> for more information.
@@ -7345,7 +7345,7 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          In the <option>--pages</option> option, it is now possible
+          In the @1@option@1@--pages@2@option@2@ option, it is now possible
           to copy the same page more than once from the same file
           without using the previous workaround of specifying two
           different paths to the same file.
@@ -7353,21 +7353,21 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          In the <option>--pages</option> option, allow use of
+          In the @1@option@1@--pages@2@option@2@ option, allow use of
           &ldquo;.&rdquo; as a shortcut for the primary input file.
-          That way, you can do <command>qpdf in.pdf --pages . 1-2 --
-          out.pdf</command> instead of having to repeat
-          <filename>in.pdf</filename> in the command.
+          That way, you can do @1@command@1@qpdf in.pdf --pages . 1-2 --
+          out.pdf@2@command@2@ instead of having to repeat
+          @1@filename@1@in.pdf@2@filename@2@ in the command.
          </para>
         </listitem>
         <listitem>
          <para>
           When encrypting with 128-bit and 256-bit encryption, new
-          encryption options <option>--assemble</option>,
-          <option>--annotate</option>, <option>--form</option>, and
-          <option>--modify-other</option> allow more fine-grained
+          encryption options @1@option@1@--assemble@2@option@2@,
+          @1@option@1@--annotate@2@option@2@, @1@option@1@--form@2@option@2@, and
+          @1@option@1@--modify-other@2@option@2@ allow more fine-grained
           granularity in configuring options. Before, the
-          <option>--modify</option> option only configured certain
+          @1@option@1@--modify@2@option@2@ option only configured certain
           predefined groups of permissions.
          </para>
         </listitem>
@@ -7387,7 +7387,7 @@ print &quot;\n&quot;;
           resource lists across pages and if some but not all of the
           pages in the output did not reference all the fonts and
           images. Using the
-          <option>--preserve-unreferenced-resources</option> option
+          @1@option@1@--preserve-unreferenced-resources@2@option@2@ option
           would work around the incorrect behavior. This bug was the
           result of a typo in the code and a deficiency in the test
           suite. The case that triggered the error was known, just not
@@ -7411,7 +7411,7 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          Using older option <option>--stream-data=compress</option>
+          Using older option @1@option@1@--stream-data=compress@2@option@2@
           with object streams, object streams and xref streams were
           not compressed.
          </para>
@@ -7453,7 +7453,7 @@ print &quot;\n&quot;;
           Add new versions of
           <function>QPDFWriter::setR{3,4,5,6}EncryptionParameters</function>
           that allow more granular setting of permissions bits. See
-          <filename>QPDFWriter.hh</filename> for details.
+          @1@filename@1@QPDFWriter.hh@2@filename@2@ for details.
          </para>
         </listitem>
         <listitem>
@@ -7480,7 +7480,7 @@ print &quot;\n&quot;;
           passed to
           <function>QPDFPageDocumentHelper::addPage()</function> for
           either the original <classname>QPDF</classname> object or a
-          different one. This is what the <command>qpdf</command>
+          different one. This is what the @1@command@1@qpdf@2@command@2@
           command-line tool uses to copy the same page multiple times
           from the same file during splitting and merging operations.
          </para>
@@ -7506,7 +7506,7 @@ print &quot;\n&quot;;
           immediately instead of lazily. This option uses more memory
           but allows the source object to go out of scope before the
           destination object is written in all cases. See comments in
-          <filename>QPDF.hh</filename> for details.
+          @1@filename@1@QPDF.hh@2@filename@2@ for details.
          </para>
         </listitem>
         <listitem>
@@ -7568,7 +7568,7 @@ print &quot;\n&quot;;
         <listitem>
          <para>
           Add new configure option
-          <option>--enable-avoid-windows-handle</option>, which causes
+          @1@option@1@--enable-avoid-windows-handle@2@option@2@, which causes
           the preprocessor symbol
           <literal>AVOID_WINDOWS_HANDLE</literal> to be defined. When
           defined, qpdf will avoid referencing the Windows
@@ -7585,7 +7585,7 @@ print &quot;\n&quot;;
           defined. If you do your own builds with other compilers, you
           can define this symbol to cause <function>wmain</function>
           to be used. This is needed to allow the Windows
-          <command>qpdf</command> command to receive Unicode
+          @1@command@1@qpdf@2@command@2@ command to receive Unicode
           command-line options.
          </para>
         </listitem>
@@ -7605,9 +7605,9 @@ print &quot;\n&quot;;
        <itemizedlist>
         <listitem>
          <para>
-          Shell completion: you can now use eval <command>$(qpdf
-          --completion-bash)</command> and eval <command>$(qpdf
-          --completion-zsh)</command> to enable shell completion for
+          Shell completion: you can now use eval @1@command@1@$(qpdf
+          --completion-bash)@2@command@2@ and eval @1@command@1@$(qpdf
+          --completion-zsh)@2@command@2@ to enable shell completion for
           bash and zsh.
          </para>
         </listitem>
@@ -7615,14 +7615,14 @@ print &quot;\n&quot;;
          <para>
           Page numbers (also known as page labels) are now preserved
           when merging and splitting files with the
-          <option>--pages</option> and <option>--split-pages</option>
+          @1@option@1@--pages@2@option@2@ and @1@option@1@--split-pages@2@option@2@
           options.
          </para>
         </listitem>
         <listitem>
          <para>
           Bookmarks are partially preserved when splitting pages with
-          the <option>--split-pages</option> option. Specifically, the
+          the @1@option@1@--split-pages@2@option@2@ option. Specifically, the
           outlines dictionary and some supporting metadata are copied
           into the split files. The result is that all bookmarks from
           the original file appear, those that point to pages that are
@@ -7634,8 +7634,8 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          Page collation: add new option <option>--collate</option>.
-          When specified, the semantics of <option>--pages</option>
+          Page collation: add new option @1@option@1@--collate@2@option@2@.
+          When specified, the semantics of @1@option@1@--pages@2@option@2@
           change from concatenation to collation. See <xref
           linkend="ref.page-selection"/> for examples and discussion.
          </para>
@@ -7644,17 +7644,17 @@ print &quot;\n&quot;;
          <para>
           Generation of information in JSON format, primarily to
           facilitate use of qpdf from languages other than C++. Add
-          new options <option>--json</option>,
-          <option>--json-key</option>, and
-          <option>--json-object</option> to generate a JSON
-          representation of the PDF file. Run <command>qpdf
-          --json-help</command> to get a description of the JSON
+          new options @1@option@1@--json@2@option@2@,
+          @1@option@1@--json-key@2@option@2@, and
+          @1@option@1@--json-object@2@option@2@ to generate a JSON
+          representation of the PDF file. Run @1@command@1@qpdf
+          --json-help@2@command@2@ to get a description of the JSON
           format. For more information, see <xref linkend="ref.json"/>.
          </para>
         </listitem>
         <listitem>
          <para>
-          The <option>--generate-appearances</option> flag will cause
+          The @1@option@1@--generate-appearances@2@option@2@ flag will cause
           qpdf to generate appearances for form fields if the PDF file
           indicates that form field appearances are out of date. This
           can happen when PDF forms are filled in by a program that
@@ -7664,14 +7664,14 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          The <option>--flatten-annotations</option> flag can be used
+          The @1@option@1@--flatten-annotations@2@option@2@ flag can be used
           to <emphasis>flatten</emphasis> annotations, including form
           fields. Ordinarily, annotations are drawn separately from
           the page. Flattening annotations is the process of combining
           their appearances into the page's contents. You might want
           to do this if you are going to rotate or combine pages using
           a tool that doesn't understand about annotations. You may
-          also want to use <option>--generate-appearances</option>
+          also want to use @1@option@1@--generate-appearances@2@option@2@
           when using this flag since annotations for outdated form
           fields are not flattened as that would cause loss of
           information.
@@ -7679,13 +7679,13 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          The <option>--optimize-images</option> flag tells qpdf to
+          The @1@option@1@--optimize-images@2@option@2@ flag tells qpdf to
           recompresses every image using DCT (JPEG) compression as
           long as the image is not already compressed with lossy
           compression and recompressing the image reduces its size.
-          The additional options <option>--oi-min-width</option>,
-          <option>--oi-min-height</option>, and
-          <option>--oi-min-area</option> prevent recompression of
+          The additional options @1@option@1@--oi-min-width@2@option@2@,
+          @1@option@1@--oi-min-height@2@option@2@, and
+          @1@option@1@--oi-min-area@2@option@2@ prevent recompression of
           images whose width, height, or pixel area
           (width&nbsp;&#xd7;&nbsp;height) are below a specified
           threshold.
@@ -7693,8 +7693,8 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          The <option>--show-object</option> option can now be given
-          as <option>--show-object=trailer</option> to show the
+          The @1@option@1@--show-object@2@option@2@ option can now be given
+          as @1@option@1@--show-object=trailer@2@option@2@ to show the
           trailer dictionary.
          </para>
         </listitem>
@@ -7735,11 +7735,11 @@ print &quot;\n&quot;;
         <listitem>
          <para>
           Ordinarily qpdf treats an argument of the form
-          <option>@file</option> to mean that command-line options
-          should be read from <filename>file</filename>. Now, if
-          <filename>file</filename> does not exist but
-          <filename>@file</filename> does, qpdf will treat
-          <filename>@file</filename> as a regular option. This makes
+          @1@option@1@@file@2@option@2@ to mean that command-line options
+          should be read from @1@filename@1@file@2@filename@2@. Now, if
+          @1@filename@1@file@2@filename@2@ does not exist but
+          @1@filename@1@@file@2@filename@2@ does, qpdf will treat
+          @1@filename@1@@file@2@filename@2@ as a regular option. This makes
           it possible to work more easily with PDF files whose names
           happen to start with the <literal>@</literal> character.
          </para>
@@ -7761,7 +7761,7 @@ print &quot;\n&quot;;
           using a QPDFObjectHandle::StreamDataProvider. For a more
           in-depth discussion, see comments around
           <function>copyForeignObject</function> in
-          <filename>QPDF.hh</filename>.
+          @1@filename@1@QPDF.hh@2@filename@2@.
          </para>
         </listitem>
         <listitem>
@@ -7770,7 +7770,7 @@ print &quot;\n&quot;;
           <function>QPDFWriter::getFinalVersion()</function>, which
           returns the PDF version that will ultimately be written to
           the final file. See comments in
-          <filename>QPDFWriter.hh</filename> for some restrictions on
+          @1@filename@1@QPDFWriter.hh@2@filename@2@ for some restrictions on
           its use.
          </para>
         </listitem>
@@ -7793,7 +7793,7 @@ print &quot;\n&quot;;
           <classname>QPDFAnnotationObjectHelper</classname> and
           <classname>QPDFFormFieldObjectHelper</classname> for
           querying flags and interpretation of different field types.
-          Define constants in <filename>qpdf/Constants.h</filename> to
+          Define constants in @1@filename@1@qpdf/Constants.h@2@filename@2@ to
           help with interpretation of flag values.
          </para>
         </listitem>
@@ -7804,7 +7804,7 @@ print &quot;\n&quot;;
           and
           <function>QPDFFormFieldObjectHelper::generateAppearance</function>
           for generating appearance streams. See discussion in
-          <filename>QPDFFormFieldObjectHelper.hh</filename> for
+          @1@filename@1@QPDFFormFieldObjectHelper.hh@2@filename@2@ for
           limitations.
          </para>
         </listitem>
@@ -7885,11 +7885,11 @@ print &quot;\n&quot;;
         <listitem>
          <para>
           It is no longer necessary to run
-          <command>autogen.sh</command> to build from a pristine
+          @1@command@1@autogen.sh@2@command@2@ to build from a pristine
           checkout. Automatically generated files are now committed so
           that it is possible to build on platforms without autoconf
           directly from a clean checkout of the repository. The
-          <command>configure</command> script detects if the files are
+          @1@command@1@configure@2@command@2@ script detects if the files are
           out of date when it also determines that the tools are
           present to regenerate them.
          </para>
@@ -7924,8 +7924,8 @@ print &quot;\n&quot;;
           If your packaging system automatically refreshes libtool or
           autoconf files, it could cause this check to fail. To avoid
           this problem, pass
-          <option>--disable-check-autofiles</option> to
-          <command>configure</command>.
+          @1@option@1@--disable-check-autofiles@2@option@2@ to
+          @1@command@1@configure@2@command@2@.
          </para>
         </listitem>
         <listitem>
@@ -7934,7 +7934,7 @@ print &quot;\n&quot;;
           automatically, you can install completion files in the
           distribution's default location. You can find sample
           completion files to install in the
-          <filename>completions</filename> directory.
+          @1@filename@1@completions@2@filename@2@ directory.
          </para>
         </listitem>
        </itemizedlist>
@@ -7954,10 +7954,10 @@ print &quot;\n&quot;;
         <listitem>
          <para>
 	  Add
-	  <option>--keep-files-open=<replaceable>[yn]</replaceable></option>
+	  @1@option@1@--keep-files-open=@1@replaceable@1@[yn]@2@replaceable@2@@2@option@2@
 	  to override default determination of whether to keep files
 	  open when merging. Please see the discussion of
-	  <option>--keep-files-open</option> in <xref
+	  @1@option@1@--keep-files-open@2@option@2@ in <xref
 	  linkend="ref.basic-options"/> for additional details.
          </para>
         </listitem>
@@ -7977,7 +7977,7 @@ print &quot;\n&quot;;
        <itemizedlist>
         <listitem>
          <para>
-	  Add <option>--no-warn</option> option to suppress issuing
+	  Add @1@option@1@--no-warn@2@option@2@ option to suppress issuing
 	  warning messages. If there are any conditions that would
 	  have caused warnings to be issued, the exit status is still
 	  3.
@@ -8014,7 +8014,7 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-	  Bug fix: using <option>--progress</option> on very small
+	  Bug fix: using @1@option@1@--progress@2@option@2@ on very small
           files could cause an infinite loop.
          </para>
         </listitem>
@@ -8053,8 +8053,8 @@ print &quot;\n&quot;;
         <listitem>
          <para>
 	  For the mingw builds, change the name of the DLL import
-	  library from <filename>libqpdf.a</filename> to
-	  <filename>libqpdf.dll.a</filename> to more accurately
+	  library from @1@filename@1@libqpdf.a@2@filename@2@ to
+	  @1@filename@1@libqpdf.dll.a@2@filename@2@ to more accurately
 	  reflect that it is an import library rather than a static
 	  library. This potentially clears the way for supporting a
 	  static library in the future, though presently, the qpdf
@@ -8089,7 +8089,7 @@ print &quot;\n&quot;;
           unlikely event that the old behavior should be desired, or
           if you have a case where page splitting is very slow, the
           old behavior (and speed) can be enabled by specifying
-          <option>--preserve-unreferenced-resources</option>. For
+          @1@option@1@--preserve-unreferenced-resources@2@option@2@. For
           additional details, please see <xref
           linkend="ref.advanced-transformation"/>.
          </para>
@@ -8104,9 +8104,9 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          The <option>--rotate</option> option's syntax has been
+          The @1@option@1@--rotate@2@option@2@ option's syntax has been
           extended to make the page range optional. If you specify
-          <option>--rotate=<replaceable>angle</replaceable></option>
+          @1@option@1@--rotate=@1@replaceable@1@angle@2@replaceable@2@@2@option@2@
           without specifying a page range, the rotation will be
           applied to all pages. This can be especially useful for
           adjusting a PDF created from a multi-page document that
@@ -8115,14 +8115,14 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          When merging multiple files, the <option>--verbose</option>
+          When merging multiple files, the @1@option@1@--verbose@2@option@2@
           option now prints information about each file as it operates
           on that file.
          </para>
         </listitem>
         <listitem>
          <para>
-          When the <option>--progress</option> option is specified,
+          When the @1@option@1@--progress@2@option@2@ option is specified,
           qpdf will print a running indicator of its best guess at how
           far through the writing process it is. Note that, as with
           all progress meters, it's an approximation. This option is
@@ -8190,7 +8190,7 @@ print &quot;\n&quot;;
           <classname>QPDFObjectHandle</classname> and
           <classname>QPDF</classname> directly. Comments in the header
           files direct you to the new interfaces. Please see the
-          header files and <filename>ChangeLog</filename> for
+          header files and @1@filename@1@ChangeLog@2@filename@2@ for
           additional details.
          </para>
         </listitem>
@@ -8208,7 +8208,7 @@ print &quot;\n&quot;;
         <listitem>
          <para>
           A new example program
-          <filename>examples/pdf-set-form-values.cc</filename> has
+          @1@filename@1@examples/pdf-set-form-values.cc@2@filename@2@ has
           been added that illustrates use of the new document and
           object helpers.
          </para>
@@ -8222,8 +8222,8 @@ print &quot;\n&quot;;
           to update your idea of the percentage it thinks it is
           through writing its output. Client programs can use this to
           implement reasonably accurate progress meters. The
-          <command>qpdf</command> command line tool uses this to
-          implement its <option>--progress</option> option.
+          @1@command@1@qpdf@2@command@2@ command line tool uses this to
+          implement its @1@option@1@--progress@2@option@2@ option.
          </para>
         </listitem>
         <listitem>
@@ -8344,7 +8344,7 @@ print &quot;\n&quot;;
       </listitem>
       <listitem>
        <para>
-        Enhancements to the <command>qpdf</command> Command-line Tool.
+        Enhancements to the @1@command@1@qpdf@2@command@2@ Command-line Tool.
         All new options listed here are documented in more detail in
         <xref linkend="ref.using"/>.
        </para>
@@ -8352,13 +8352,13 @@ print &quot;\n&quot;;
         <listitem>
          <para>
           The option
-          <option>--linearize-pass1=<replaceable>file</replaceable></option>
+          @1@option@1@--linearize-pass1=@1@replaceable@1@file@2@replaceable@2@@2@option@2@
           has been added for debugging qpdf's linearization code.
          </para>
         </listitem>
         <listitem>
          <para>
-          The option <option>--coalesce-contents</option> can be used
+          The option @1@option@1@--coalesce-contents@2@option@2@ can be used
           to combine content streams of a page whose contents are an
           array of streams into a single stream.
          </para>
@@ -8376,14 +8376,14 @@ print &quot;\n&quot;;
          <para>
           Add function <function>qpdf_check_pdf</function> to the C API.
           This function does basic checking that is a subset of what
-          <command>qpdf --check</command> performs.
+          @1@command@1@qpdf --check@2@command@2@ performs.
          </para>
         </listitem>
         <listitem>
          <para>
           Major enhancements to the lexical layer of qpdf. For a
           complete list of enhancements, please refer to the
-          <filename>ChangeLog</filename> file. Most of the changes
+          @1@filename@1@ChangeLog@2@filename@2@ file. Most of the changes
           result in improvements to qpdf's ability handle erroneous
           files. It is also possible for programs to handle
           whitespace, comments, and inline images as tokens.
@@ -8398,9 +8398,9 @@ print &quot;\n&quot;;
           used with several different methods in
           <classname>QPDFObjectHandle</classname> as well as with a
           lower-level interface. See comments in
-          <filename>QPDFObjectHandle.hh</filename> as well as the new
-          examples <filename>examples/pdf-filter-tokens.cc</filename>
-          and <filename>examples/pdf-count-strings.cc</filename> for
+          @1@filename@1@QPDFObjectHandle.hh@2@filename@2@ as well as the new
+          examples @1@filename@1@examples/pdf-filter-tokens.cc@2@filename@2@
+          and @1@filename@1@examples/pdf-count-strings.cc@2@filename@2@ for
           details.
          </para>
         </listitem>
@@ -8449,10 +8449,10 @@ print &quot;\n&quot;;
         optionally display the encryption key used by a file. This is
         a non-standard operation, but it can be useful in certain
         situations. Please see the discussion of
-        <option>--password-is-hex-key</option> in <xref
+        @1@option@1@--password-is-hex-key@2@option@2@ in <xref
         linkend="ref.basic-options"/> or the comments around
         <function>QPDF::setPasswordIsHexKey</function> in
-        <filename>QPDF.hh</filename> for additional details.
+        @1@filename@1@QPDF.hh@2@filename@2@ for additional details.
        </para>
       </listitem>
       <listitem>
@@ -8530,8 +8530,8 @@ print &quot;\n&quot;;
           JPEG or RunLength encoding. Library API enhancements and
           command-line options have been added to control this
           behavior. See command-line options
-          <option>--compress-streams</option> and
-          <option>--decode-level</option> and methods
+          @1@option@1@--compress-streams@2@option@2@ and
+          @1@option@1@--decode-level@2@option@2@ and methods
           <function>QPDFWriter::setCompressStreams</function> and
           <function>QPDFWriter::setDecodeLevel</function>.
          </para>
@@ -8567,7 +8567,7 @@ print &quot;\n&quot;;
      <itemizedlist>
       <listitem>
        <para>
-        Enhancements to the <command>qpdf</command> Command-line Tool.
+        Enhancements to the @1@command@1@qpdf@2@command@2@ Command-line Tool.
         All new options listed here are documented in more detail in
         <xref linkend="ref.using"/>.
        </para>
@@ -8582,12 +8582,12 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          <option>--rotate</option>: request page rotation
+          @1@option@1@--rotate@2@option@2@: request page rotation
          </para>
         </listitem>
         <listitem>
          <para>
-          <option>--newline-before-endstream</option>: ensure that a
+          @1@option@1@--newline-before-endstream@2@option@2@: ensure that a
           newline appears before every <literal>endstream</literal>
           keyword in the file; used to prevent qpdf from breaking
           PDF/A compliance on already compliant files.
@@ -8595,35 +8595,35 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          <option>--preserve-unreferenced</option>: preserve
+          @1@option@1@--preserve-unreferenced@2@option@2@: preserve
           unreferenced objects in the input PDF
          </para>
         </listitem>
         <listitem>
          <para>
-	  <option>--split-pages</option>: break output into chunks
+	  @1@option@1@--split-pages@2@option@2@: break output into chunks
           with fixed numbers of pages
          </para>
         </listitem>
         <listitem>
          <para>
-	  <option>--verbose</option>: print the name of each output
+	  @1@option@1@--verbose@2@option@2@: print the name of each output
           file that is created
          </para>
         </listitem>
         <listitem>
          <para>
-          <option>--compress-streams</option> and
-          <option>--decode-level</option> replace
-          <option>--stream-data</option> for improving granularity of
+          @1@option@1@--compress-streams@2@option@2@ and
+          @1@option@1@--decode-level@2@option@2@ replace
+          @1@option@1@--stream-data@2@option@2@ for improving granularity of
           controlling compression and decompression of stream data.
-          The <option>--stream-data</option> option will remain
+          The @1@option@1@--stream-data@2@option@2@ option will remain
           available.
          </para>
         </listitem>
         <listitem>
          <para>
-          When running <command>qpdf --check</command> with other
+          When running @1@command@1@qpdf --check@2@command@2@ with other
           options, checks are always run first. This enables qpdf to
           perform its full recovery logic before outputting other
           information. This can be especially useful when manually
@@ -8633,9 +8633,9 @@ print &quot;\n&quot;;
         </listitem>
         <listitem>
          <para>
-          Process <command>--pages</command> earlier so that other
-          options like <option>--show-pages</option> or
-          <option>--split-pages</option> can operate on the file after
+          Process @1@command@1@--pages@2@command@2@ earlier so that other
+          options like @1@option@1@--show-pages@2@option@2@ or
+          @1@option@1@--split-pages@2@option@2@ can operate on the file after
           page splitting/merging has occurred.
          </para>
         </listitem>
@@ -8674,7 +8674,7 @@ print &quot;\n&quot;;
           <classname>Pl_RunLength</classname> and
           <classname>Pl_DCT</classname> are available for developers
           who wish to produce or consume RunLength or DCT stream data
-          directly. The <filename>examples/pdf-create.cc</filename>
+          directly. The @1@filename@1@examples/pdf-create.cc@2@filename@2@
           example illustrates their use.
          </para>
         </listitem>
@@ -8707,7 +8707,7 @@ print &quot;\n&quot;;
      <itemizedlist>
       <listitem>
        <para>
-        Implement <option>--deterministic-id</option> command-line
+        Implement @1@option@1@--deterministic-id@2@option@2@ command-line
         option and <function>QPDFWriter::setDeterministicID</function>
         as well as C API function
         <function>qpdf_set_deterministic_ID</function> for generating
@@ -8787,10 +8787,10 @@ print &quot;\n&quot;;
       </listitem>
       <listitem>
        <para>
-        New example program: <command>pdf-split-pages</command>:
+        New example program: @1@command@1@pdf-split-pages@2@command@2@:
         efficiently split PDF files into individual pages. The example
-        program does this more efficiently than using <command>qpdf
-        --pages</command> to do it.
+        program does this more efficiently than using @1@command@1@qpdf
+        --pages@2@command@2@ to do it.
        </para>
       </listitem>
       <listitem>
@@ -8876,14 +8876,14 @@ print &quot;\n&quot;;
         For the Windows build, this results in an added dependency on
         Microsoft's cryptography API.  To disable the OS-specific
         cryptography and use the old version, pass the
-        <option>--enable-insecure-random</option> option to
-        <command>./configure</command>.
+        @1@option@1@--enable-insecure-random@2@option@2@ option to
+        @1@command@1@./configure@2@command@2@.
        </para>
       </listitem>
       <listitem>
        <para>
-        The <command>qpdf</command> command-line tool now issues a
-        warning when <option>-accessibility=n</option> is specified
+        The @1@command@1@qpdf@2@command@2@ command-line tool now issues a
+        warning when @1@option@1@-accessibility=n@2@option@2@ is specified
         for newer encryption versions stating that the option is
         ignored.  qpdf, per the spec, has always ignored this flag,
         but it previously did so silently.  This warning is issued
@@ -8922,21 +8922,21 @@ print &quot;\n&quot;;
         <function>QPDFObjectHandle::getGeneration()</function> as it
         makes it less likely for people to accidentally write code
         that ignores the generation number.  See
-        <filename>QPDF.hh</filename> and
-        <filename>QPDFObjectHandle.hh</filename> for additional notes.
+        @1@filename@1@QPDF.hh@2@filename@2@ and
+        @1@filename@1@QPDFObjectHandle.hh@2@filename@2@ for additional notes.
        </para>
       </listitem>
       <listitem>
        <para>
-        Add <option>--show-npages</option> command-line option to the
-        <command>qpdf</command> command to show the number of pages in
+        Add @1@option@1@--show-npages@2@option@2@ command-line option to the
+        @1@command@1@qpdf@2@command@2@ command to show the number of pages in
         a file.
        </para>
       </listitem>
       <listitem>
        <para>
         Allow omission of the page range within
-        <option>--pages</option> for the <command>qpdf</command>
+        @1@option@1@--pages@2@option@2@ for the @1@command@1@qpdf@2@command@2@
         command.  When omitted, the page range is implicitly taken to
         be all the pages in the file.
        </para>
@@ -8945,7 +8945,7 @@ print &quot;\n&quot;;
        <para>
         Various enhancements were made to support different types of
         broken files or broken readers.  Details can be found in
-        <filename>ChangeLog</filename>.
+        @1@filename@1@ChangeLog@2@filename@2@.
        </para>
       </listitem>
      </itemizedlist>
@@ -8958,10 +8958,10 @@ print &quot;\n&quot;;
       <listitem>
        <para>
         Note to people including qpdf in distributions: the
-        <filename>.la</filename> files generated by libtool are now
-        installed by qpdf's <command>make install</command> target.
+        @1@filename@1@.la@2@filename@2@ files generated by libtool are now
+        installed by qpdf's @1@command@1@make install@2@command@2@ target.
         Before, they were not installed.  This means that if your
-        distribution does not want to include <filename>.la</filename>
+        distribution does not want to include @1@filename@1@.la@2@filename@2@
         files, you must remove them as part of your packaging process.
        </para>
       </listitem>
@@ -8976,7 +8976,7 @@ print &quot;\n&quot;;
            <function>QPDFObjectHandle::parseContentStream</function>
            method parses objects in a content stream and calls
            handlers in a callback class.  The example
-           <filename>examples/pdf-parse-content.cc</filename>
+           @1@filename@1@examples/pdf-parse-content.cc@2@filename@2@
            illustrates how this may be used.
           </para>
          </listitem>
@@ -9004,7 +9004,7 @@ print &quot;\n&quot;;
       </listitem>
       <listitem>
        <para>
-        <command>qpdf --check</command> now parses all pages' content
+        @1@command@1@qpdf --check@2@command@2@ now parses all pages' content
         streams in addition to doing other checks.  While there are
         still many types of errors that cannot be detected, syntactic
         errors in content streams will now be reported.
@@ -9019,12 +9019,12 @@ print &quot;\n&quot;;
          <listitem>
           <para>
            Warning flags have been moved into a separate variable in
-           <filename>autoconf.mk</filename>
+           @1@filename@1@autoconf.mk@2@filename@2@
           </para>
          </listitem>
          <listitem>
           <para>
-           The configure flag <option>--enable-werror</option> work
+           The configure flag @1@option@1@--enable-werror@2@option@2@ work
            for Microsoft compilers
           </para>
          </listitem>
@@ -9052,7 +9052,7 @@ print &quot;\n&quot;;
            converts numbers to strings.  This is largely invisible to
            users, but it does trigger a bug in some older versions of
            mingw-w64's C++ library.  See
-           <filename>README-windows.md</filename> in the source
+           @1@filename@1@README-windows.md@2@filename@2@ in the source
            distribution if you think this may affect you.  The copy of
            the DLL distributed with qpdf's binary distribution is not
            affected by this problem.
@@ -9084,7 +9084,7 @@ print &quot;\n&quot;;
          <listitem>
           <para>
            Installation no longer uses GNU/Linux-specific versions of
-           some commands, so <command>make install</command> works on
+           some commands, so @1@command@1@make install@2@command@2@ works on
            Solaris with native tools.
           </para>
          </listitem>
@@ -9112,7 +9112,7 @@ print &quot;\n&quot;;
       </listitem>
       <listitem>
        <para>
-        Add clarifying comment in <filename>QPDF.hh</filename> to
+        Add clarifying comment in @1@filename@1@QPDF.hh@2@filename@2@ to
         methods that return the user password explaining that it is no
         longer possible with newer encryption formats to recover the
         user password knowing the owner password.  In earlier
@@ -9252,12 +9252,12 @@ print &quot;\n&quot;;
          <listitem>
           <para>
            Removed the method <function>decodeStreams</function>.
-           This method was used by the <option>--check</option> option
-           of the <command>qpdf</command> command-line tool to force
+           This method was used by the @1@option@1@--check@2@option@2@ option
+           of the @1@command@1@qpdf@2@command@2@ command-line tool to force
            all streams in the file to be decoded, but it also suffered
            from the problem of opening otherwise unreferenced streams
            and thus could report false positive.  The
-           <option>--check</option> option now causes qpdf to go
+           @1@option@1@--check@2@option@2@ option now causes qpdf to go
            through all the motions of writing a new file based on the
            original one, so it will always reference and check exactly
            those parts of a file that any ordinary viewer would check.
@@ -9289,9 +9289,9 @@ print &quot;\n&quot;;
       </listitem>
       <listitem>
        <para>
-        Fix the <command>pkg-config</command> files to list zlib and
+        Fix the @1@command@1@pkg-config@2@command@2@ files to list zlib and
         pcre in <function>Requires.private</function> to better
-        support static linking using <command>pkg-config</command>.
+        support static linking using @1@command@1@pkg-config@2@command@2@.
        </para>
       </listitem>
      </itemizedlist>
@@ -9328,7 +9328,7 @@ print &quot;\n&quot;;
       <listitem>
        <para>
         Version 3.0.0 included addition of files for
-        <command>pkg-config</command>, but this was not mentioned in
+        @1@command@1@pkg-config@2@command@2@, but this was not mentioned in
         the release notes.  The release notes for 3.0.0 were updated
         to mention this.
        </para>
@@ -9385,13 +9385,13 @@ print &quot;\n&quot;;
       <listitem>
        <para>
         Support for page selection (splitting and merging PDF files)
-        has been added to the <command>qpdf</command> command-line
+        has been added to the @1@command@1@qpdf@2@command@2@ command-line
         tool.  See <xref linkend="ref.page-selection"/>.
        </para>
       </listitem>
       <listitem>
        <para>
-        Options have been added to the <command>qpdf</command>
+        Options have been added to the @1@command@1@qpdf@2@command@2@
         command-line tool for copying encryption parameters from
         another file.  See <xref linkend="ref.basic-options"/>.
        </para>
@@ -9434,7 +9434,7 @@ print &quot;\n&quot;;
        <para>
         The <function>QPDF::emptyPDF</function> can be used to allow
         creation of PDF files from scratch.  The example
-        <filename>examples/pdf-create.cc</filename> illustrates how it
+        @1@filename@1@examples/pdf-create.cc@2@filename@2@ illustrates how it
         can be used.
        </para>
       </listitem>
@@ -9449,7 +9449,7 @@ print &quot;\n&quot;;
        <para>
         Many new convenience methods have been added to the library,
         most in <classname>QPDFObjectHandle</classname>.  See
-        <filename>ChangeLog</filename> for a full list.
+        @1@filename@1@ChangeLog@2@filename@2@ for a full list.
        </para>
       </listitem>
       <listitem>
@@ -9457,14 +9457,14 @@ print &quot;\n&quot;;
         When building on a platform that supports ELF shared libraries
         (such as Linux), symbol versions are enabled by default.  They
         can be disabled by passing
-        <option>--disable-ld-version-script</option> to
-        <command>./configure</command>.
+        @1@option@1@--disable-ld-version-script@2@option@2@ to
+        @1@command@1@./configure@2@command@2@.
        </para>
       </listitem>
       <listitem>
        <para>
-        The file <filename>libqpdf.pc</filename> is now installed to
-        support <command>pkg-config</command>.
+        The file @1@filename@1@libqpdf.pc@2@filename@2@ is now installed to
+        support @1@command@1@pkg-config@2@command@2@.
        </para>
       </listitem>
       <listitem>
@@ -9473,26 +9473,26 @@ print &quot;\n&quot;;
         not needed to verify a correct build or port of qpdf.  They
         are needed only when changing the actual PDF output generated
         by qpdf.  You should enable them if you are making deep
-        changes to qpdf itself.  See <filename>README.md</filename> for
+        changes to qpdf itself.  See @1@filename@1@README.md@2@filename@2@ for
         details.
        </para>
       </listitem>
       <listitem>
        <para>
         Large file tests are off by default but can be turned on with
-        <command>./configure</command> or by setting an environment
+        @1@command@1@./configure@2@command@2@ or by setting an environment
         variable before running the test suite.  See
-        <filename>README.md</filename> for details.
+        @1@filename@1@README.md@2@filename@2@ for details.
        </para>
       </listitem>
       <listitem>
        <para>
         When qpdf's test suite fails, failures are not printed to the
         terminal anymore by default.  Instead, find them in
-        <filename>build/qtest.log</filename>.  For packagers who are
+        @1@filename@1@build/qtest.log@2@filename@2@.  For packagers who are
         building with an autobuilder, you can add the
-        <option>--enable-show-failed-test-output</option> option to
-        <command>./configure</command> to restore the old behavior.
+        @1@option@1@--enable-show-failed-test-output@2@option@2@ option to
+        @1@command@1@./configure@2@command@2@ to restore the old behavior.
        </para>
       </listitem>
      </itemizedlist>
@@ -9664,7 +9664,7 @@ print &quot;\n&quot;;
         way.  Note that QPDF does not write to
         <varname>std::cout</varname> (or the specified output stream)
         except where explicitly mentioned in
-        <filename>QPDF.hh</filename>, and that the only use of the
+        @1@filename@1@QPDF.hh@2@filename@2@, and that the only use of the
         error stream is for warnings.  Note also that output of
         warnings is suppressed when
         <literal>setSuppressWarnings(true)</literal> is called.
@@ -9751,8 +9751,8 @@ print &quot;\n&quot;;
       <listitem>
        <para>
         Provide two new examples:
-        <command>pdf-double-page-size</command> and
-        <command>pdf-invert-images</command> that illustrate the newly
+        @1@command@1@pdf-double-page-size@2@command@2@ and
+        @1@command@1@pdf-invert-images@2@command@2@ that illustrate the newly
         added interfaces.
        </para>
       </listitem>
@@ -9794,7 +9794,7 @@ print &quot;\n&quot;;
       </listitem>
       <listitem>
        <para>
-        Since <command>qpdf --check</command> only performs limited
+        Since @1@command@1@qpdf --check@2@command@2@ only performs limited
         checks, clarify the output to make it clear that there still
         may be errors that qpdf can't check.  This should make it less
         surprising to people when another PDF reader is unable to read
@@ -9870,8 +9870,8 @@ print &quot;\n&quot;;
        </para>
        <para>
         For programming to the C interface, please see the header file
-        <filename>qpdf/qpdf-c.h</filename> and the example
-        <filename>examples/pdf-linearize.c</filename>.
+        @1@filename@1@qpdf/qpdf-c.h@2@filename@2@ and the example
+        @1@filename@1@examples/pdf-linearize.c@2@filename@2@.
        </para>
       </listitem>
       <listitem>
@@ -9880,7 +9880,7 @@ print &quot;\n&quot;;
         be downloaded from qpdf's download side.  Žarko's Delphi
         wrapper is released with the same licensing terms as qpdf
         itself and comes with this disclaimer: &ldquo;Delphi wrapper
-        unit <filename>qpdf.pas</filename> created by Žarko Gajić
+        unit @1@filename@1@qpdf.pas@2@filename@2@ created by Žarko Gajić
         (<ulink
         url="http://zarko-gajic.iz.hr/">http://zarko-gajic.iz.hr/</ulink>).
         Use at your own risk and for whatever purpose you want.  No
@@ -9931,7 +9931,7 @@ print &quot;\n&quot;;
       </listitem>
       <listitem>
        <para>
-        The <option>--check</option> option to <command>qpdf</command>
+        The @1@option@1@--check@2@option@2@ option to @1@command@1@qpdf@2@command@2@
         has been extended to include some additional information.
        </para>
       </listitem>
@@ -10017,7 +10017,7 @@ print &quot;\n&quot;;
       <listitem>
        <para>
         Update test suite to work properly with a
-        non-<command>bash</command> <filename>/bin/sh</filename> and
+        non-@1@command@1@bash@2@command@2@ @1@filename@1@/bin/sh@2@filename@2@ and
         with Perl 5.10.  No changes were made to the actual qpdf
         source code itself for this release.
        </para>
@@ -10034,7 +10034,7 @@ print &quot;\n&quot;;
         No changes in functionality or interface.  This release
         includes fixes to the source code so that qpdf compiles
         properly and passes its test suite on a broader range of
-        platforms.  See <filename>ChangeLog</filename> in the source
+        platforms.  See @1@filename@1@ChangeLog@2@filename@2@ in the source
         distribution for details.
        </para>
       </listitem>
@@ -10075,7 +10075,7 @@ print &quot;\n&quot;;
      favor of the now removed <classname>QEXC</classname> classes used
      in previous versions.  The <classname>QEXC</classname> exception
      classes predated the addition of the
-     <filename>&lt;stdexcept&gt;</filename> header file to the C++
+     @1@filename@1@&lt;stdexcept&gt;@2@filename@2@ header file to the C++
      standard library.  Most of the exceptions thrown by the qpdf
      library itself are still of type <classname>QPDFExc</classname>
      which is now derived from
@@ -10092,7 +10092,7 @@ print &quot;\n&quot;;
      interfaces for querying them.  Among the fields is a numeric
      error code that can help applications act differently on (a small
      number of) different error conditions.  See
-     <filename>QPDFExc.hh</filename> for details.
+     @1@filename@1@QPDFExc.hh@2@filename@2@ for details.
     </para>
    </listitem>
    <listitem>
@@ -10132,7 +10132,7 @@ print &quot;\n&quot;;
      The enumerated types that used to be nested in
      <classname>QPDFWriter</classname> have moved to top-level
      enumerated types and are now defined in the file
-     <filename>qpdf/Constants.h</filename>.  This enables them to be
+     @1@filename@1@qpdf/Constants.h@2@filename@2@.  This enables them to be
      shared by both the C and C++ interfaces.
     </para>
    </listitem>