From bf4d1078534f14776d777ae37a83736eb969cb7e Mon Sep 17 00:00:00 2001
From: Jay Berkenbilt <ejb@ql.org>
Date: Sat, 11 Dec 2021 19:11:56 -0500
Subject: Convert <option> to :samp: and clean up literal blocks

:option: is stronger and assumes a reference to a list of options.
Since we don't have that yet, just use :samp: for options. Inside
literal code blocks, there is no expansion, so just remove markup.
---
 TODO             |   1 -
 manual/index.rst | 910 +++++++++++++++++++++++++++----------------------------
 2 files changed, 455 insertions(+), 456 deletions(-)

diff --git a/TODO b/TODO
index 1b55520e..055e0570 100644
--- a/TODO
+++ b/TODO
@@ -36,7 +36,6 @@ Make sure the information from <book> is in there
 <xref> -- find #ref. in converted rst
 Correct placement of comment: <!-- This section is referenced in QPDFObjectHandle.hh -->
 
-<option> -> :samp: (allows {x})
 <firstterm> -> just use literal
 <replaceable> -> Make sure in :file: or :samp:, then use {}
 
diff --git a/manual/index.rst b/manual/index.rst
index 7000d7e9..28e2e51b 100644
--- a/manual/index.rst
+++ b/manual/index.rst
@@ -131,7 +131,7 @@ 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` with the
-@1@option@1@--enable-test-compare-images@2@option@2@ flag. If you enable
+:samp:`--enable-test-compare-images` 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.
 
@@ -226,22 +226,22 @@ 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`:
 
-- @1@option@1@--enable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@
+- :samp:`--enable-crypto-@1@replaceable@1@x@2@replaceable@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
 
-- @1@option@1@--disable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@:
+- :samp:`--disable-crypto-@1@replaceable@1@x@2@replaceable@2@`:
   disable the @1@replaceable@1@x@2@replaceable@2@ provider, and do not
   link against its dependencies even if they are available
 
-- @1@option@1@--with-default-crypto=@1@replaceable@1@x@2@replaceable@2@@2@option@2@:
+- :samp:`--with-default-crypto=@1@replaceable@1@x@2@replaceable@2@`:
   make @1@replaceable@1@x@2@replaceable@2@ the default provider even if
   a higher priority one is available
 
-- @1@option@1@--disable-implicit-crypto@2@option@2@: only build crypto
+- :samp:`--disable-implicit-crypto`: only build crypto
   providers that are explicitly requested with an
-  @1@option@1@--enable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@
+  :samp:`--enable-crypto-@1@replaceable@1@x@2@replaceable@2@`
   option
 
 For example, if you want to guarantee that the gnutls crypto provider is
@@ -278,7 +278,7 @@ files you need to build.
 Runtime Crypto Provider Selection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can use the @1@option@1@--show-crypto@2@option@2@ option to
+You can use the :samp:`--show-crypto` option to
 :command:`qpdf` 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
@@ -395,7 +395,7 @@ some things you may want to keep in mind:
   providers. Read `Build Support For Crypto
   Providers <#ref.crypto.build>`__ for details.
 
-- Passing @1@option@1@--enable-show-failed-test-output@2@option@2@ to
+- Passing :samp:`--enable-show-failed-test-output` to
   :command:`./configure` 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
@@ -408,7 +408,7 @@ some things you may want to keep in mind:
   accidentally forgetting to regenerate 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 @1@option@1@--disable-check-autofiles@2@option@2@
+  checks by passing :samp:`--disable-check-autofiles`
   to :command:`/.configure`. This is safe since qpdf's
   :command:`autogen.sh` just runs autotools in the
   normal way.
@@ -440,41 +440,41 @@ When running qpdf, the basic invocation is as follows:
 
 ::
 
-   :command:`qpdf`@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@
+   qpdf [ options ] { infilename | --empty } outfilename
 
-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
+This converts PDF file :samp:`infilename` to PDF file
+:samp:`outfilename`. 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 @1@option@1@infilename@2@option@2@, the parameter
-@1@option@1@--empty@2@option@2@ may be specified. This causes qpdf to
+place of :samp:`infilename`, the parameter
+:samp:`--empty` may be specified. This causes qpdf to
 use a dummy input file that contains zero pages. The only normal use
-case for using @1@option@1@--empty@2@option@2@ would be if you were
+case for using :samp:`--empty` would be if you were
 going to add pages from another source, as discussed in `Page Selection
 Options <#ref.page-selection>`__.
 
-If @1@option@1@@filename@2@option@2@ appears as a word anywhere in the
+If :samp:`@filename` 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 @1@option@1@@-@2@option@2@
+arguments that start or end with spaces. The :samp:`@-`
 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 @1@option@1@@filename@2@option@2@ can't appear in
+line. Note that the :samp:`@filename` 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
+:samp:`--arg=@option` will not work. You would have to
 include the argument and its options together in the arguments file.
 
-@1@option@1@outfilename@2@option@2@ does not have to be seekable, even
-when generating linearized files. Specifying "@1@option@1@-@2@option@2@"
-as @1@option@1@outfilename@2@option@2@ means to write to standard
+:samp:`outfilename` does not have to be seekable, even
+when generating linearized files. Specifying ":samp:`-`"
+as :samp:`outfilename` means to write to standard
 output. If you want to overwrite the input file with the output, use the
-option @1@option@1@--replace-input@2@option@2@ and omit the output file
+option :samp:`--replace-input` 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
-@1@option@1@--replace-input@2@option@2@ option.
+:samp:`--replace-input` option.
 
 Most options require an output file, but some testing or inspection
 commands do not. These are specifically noted.
@@ -489,7 +489,7 @@ follows:
 
 - ``0``: no errors or warnings were found. The file may still have
   problems qpdf can't detect. If
-  @1@option@1@--warning-exit-0@2@option@2@ was specified, exit status 0
+  :samp:`--warning-exit-0` was specified, exit status 0
   is used even if there are warnings.
 
 - ``2``: errors were found. qpdf was not able to fully process the
@@ -498,8 +498,8 @@ follows:
 - ``3``: qpdf encountered problems that it was able to recover from. In
   some cases, the resulting file may still be damaged. Note that qpdf
   still exits with status ``3`` if it finds warnings even when
-  @1@option@1@--no-warn@2@option@2@ is specified. With
-  @1@option@1@--warning-exit-0@2@option@2@, warnings without errors
+  :samp:`--no-warn` is specified. With
+  :samp:`--warning-exit-0`, warnings without errors
   exit with status 0 instead of 3.
 
 Note that :command:`qpdf` never exists with status ``1``.
@@ -534,94 +534,94 @@ Basic Options
 The following options are the most common ones and perform commonly
 needed transformations.
 
-@1@option@1@--help@2@option@2@
+:samp:`--help`
    Display command-line invocation help.
 
-@1@option@1@--version@2@option@2@
+:samp:`--version`
    Display the current version of qpdf.
 
-@1@option@1@--copyright@2@option@2@
+:samp:`--copyright`
    Show detailed copyright information.
 
-@1@option@1@--show-crypto@2@option@2@
+:samp:`--show-crypto`
    Show a list of available crypto providers, each on a line by itself.
    The default provider is always listed first. See `Crypto
    Providers <#ref.crypto>`__ for more information about crypto
    providers.
 
-@1@option@1@--completion-bash@2@option@2@
+:samp:`--completion-bash`
    Output a completion command you can eval to enable shell completion
    from bash.
 
-@1@option@1@--completion-zsh@2@option@2@
+:samp:`--completion-zsh`
    Output a completion command you can eval to enable shell completion
    from zsh.
 
-@1@option@1@--password=@1@replaceable@1@password@2@replaceable@2@@2@option@2@
+:samp:`--password=@1@replaceable@1@password@2@replaceable@2@`
    Specifies a password for accessing encrypted files. To read the
    password from a file or standard input, you can use
-   @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
+   :samp:`--password-file`, added in qpdf 10.2. Note
+   that you can also use :samp:`@filename` or
+   :samp:`@-` 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
-   @1@option@1@--password=@1@replaceable@1@password@2@replaceable@2@@2@option@2@
+   :samp:`--password=@1@replaceable@1@password@2@replaceable@2@`
    option in the file. Syntax such as
-   @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
+   :samp:`--password=@filename` won't work since
+   :samp:`@filename` is not recognized in the middle of
    an argument.
 
-@1@option@1@--password-file=@1@replaceable@1@filename@2@replaceable@2@@2@option@2@
+:samp:`--password-file=@1@replaceable@1@filename@2@replaceable@2@`
    Reads the first line from the specified file and uses it as the
    password for accessing encrypted files.
-   @1@option@1@@1@replaceable@1@filename@2@replaceable@2@@2@option@2@
+   :samp:`@1@replaceable@1@filename@2@replaceable@2@`
    may be ``-`` 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.
 
-@1@option@1@--is-encrypted@2@option@2@
+:samp:`--is-encrypted`
    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 @1@option@1@--requires-password@2@option@2@. Both this
-   option and @1@option@1@--requires-password@2@option@2@ exit with
+   exclusive with :samp:`--requires-password`. Both this
+   option and :samp:`--requires-password` exit with
    status 2 for non-encrypted files.
 
-@1@option@1@--requires-password@2@option@2@
+:samp:`--requires-password`
    Silently exit with status 0 if a password (other than as supplied) is
    required. Exit with status 2 if the file is not encrypted. Exit with
    status 3 if the file is encrypted but 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 @1@option@1@--password@2@option@2@ option, this option
+   used with a :samp:`--password` 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
-   @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
+   :samp:`--is-encrypted`. Both this option and
+   :samp:`--is-encrypted` exit with status 2 for
    non-encrypted files.
 
-@1@option@1@--verbose@2@option@2@
+:samp:`--verbose`
    Increase verbosity of output. For now, this just prints some
    indication of any file that it creates.
 
-@1@option@1@--progress@2@option@2@
+:samp:`--progress`
    Indicate progress while writing files.
 
-@1@option@1@--no-warn@2@option@2@
+:samp:`--no-warn`
    Suppress writing of warnings to stderr. If warnings were detected and
    suppressed, :command:`qpdf` will still exit with exit
-   code 3. See also @1@option@1@--warning-exit-0@2@option@2@.
+   code 3. See also :samp:`--warning-exit-0`.
 
-@1@option@1@--warning-exit-0@2@option@2@
+:samp:`--warning-exit-0`
    If warnings are found but no errors, exit with exit code 0 instead 3.
-   When combined with @1@option@1@--no-warn@2@option@2@, the effect is
+   When combined with :samp:`--no-warn`, the effect is
    for :command:`qpdf` to completely ignore warnings.
 
-@1@option@1@--linearize@2@option@2@
+:samp:`--linearize`
    Causes generation of a linearized (web-optimized) output file.
 
-@1@option@1@--replace-input@2@option@2@
+:samp:`--replace-input`
    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
@@ -630,17 +630,17 @@ needed transformations.
    If there were any warnings, the original input is saved as
    :file:`@1@replaceable@1@infilename@2@replaceable@2@.~qpdf-orig`.
 
-@1@option@1@--copy-encryption=file@2@option@2@
+:samp:`--copy-encryption=file`
    Encrypt the file using the same encryption parameters, including user
    and owner password, as the specified file. Use
-   @1@option@1@--encryption-file-password@2@option@2@ to specify a
+   :samp:`--encryption-file-password` 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
    ``/ID`` from the file since this is part of the encryption
    parameters.
 
-@1@option@1@--encryption-file-password=password@2@option@2@
-   If the file specified with @1@option@1@--copy-encryption@2@option@2@
+:samp:`--encryption-file-password=password`
+   If the file specified with :samp:`--copy-encryption`
    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 distinguish between
@@ -648,30 +648,30 @@ needed transformations.
    including the owner password, from a file even if you don't know the
    file's owner password.
 
-@1@option@1@--allow-weak-crypto@2@option@2@
+:samp:`--allow-weak-crypto`
    Starting with version 10.4, qpdf issues warnings when requested to
    create files using RC4 encryption. This option suppresses those
    warnings. In future versions of qpdf, qpdf will refuse to create
    files with weak cryptography when this flag is not given. See `Weak
    Cryptography <#ref.weak-crypto>`__ for additional details.
 
-@1@option@1@--encrypt options --@2@option@2@
+:samp:`--encrypt options --`
    Causes generation an encrypted output file. Please see `Encryption
    Options <#ref.encryption-options>`__ for details on how to specify
    encryption parameters.
 
-@1@option@1@--decrypt@2@option@2@
+:samp:`--decrypt`
    Removes any encryption on the file. A password must be supplied if
    the file is password protected.
 
-@1@option@1@--password-is-hex-key@2@option@2@
+:samp:`--password-is-hex-key`
    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 @1@option@1@--password@2@option@2@ option is
+   the argument to the :samp:`--password` 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 @1@option@1@--pages@2@option@2@ or other
+   other files opened by :samp:`--pages` or other
    options or to files being written.
 
    Most users will never have a need for this option, and no standard
@@ -682,28 +682,28 @@ needed transformations.
    Also, if a file is 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 @1@option@1@--show-encryption-key@2@option@2@
+   normally, use the :samp:`--show-encryption-key`
    option.
 
-@1@option@1@--suppress-password-recovery@2@option@2@
+:samp:`--suppress-password-recovery`
    Ordinarily, qpdf attempts to automatically compensate for passwords
    specified in the wrong character encoding. This option suppresses
    that behavior. Under normal conditions, there are no reasons to use
    this option. See `Unicode Passwords <#ref.unicode-passwords>`__ for a
    discussion
 
-@1@option@1@--password-mode=@1@replaceable@1@mode@2@replaceable@2@@2@option@2@
+:samp:`--password-mode=@1@replaceable@1@mode@2@replaceable@2@`
    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 @1@option@1@hex-bytes@2@option@2@ mode, these only
+   exception of the :samp:`hex-bytes` mode, these only
    apply to passwords provided when encrypting files. The
-   @1@option@1@hex-bytes@2@option@2@ mode also applies to passwords
+   :samp:`hex-bytes` 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
    `Unicode Passwords <#ref.unicode-passwords>`__. The following modes
    are supported:
 
-   - @1@option@1@auto@2@option@2@: Automatically determine whether the
+   - :samp:`auto`: 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 with version 8.4.0,
@@ -711,40 +711,40 @@ needed transformations.
      be properly encoded in UTF-8, so this is almost always what you
      want.
 
-   - @1@option@1@unicode@2@option@2@: Tells qpdf that the incoming
+   - :samp:`unicode`: Tells qpdf that the incoming
      password is UTF-8, overriding whatever its automatic detection
      determines. The only difference between this mode and
-     @1@option@1@auto@2@option@2@ is that qpdf will fail with an error
+     :samp:`auto` is that qpdf will fail with an error
      message if the password is not valid UTF-8 instead of falling back
-     to @1@option@1@bytes@2@option@2@ mode with a warning.
+     to :samp:`bytes` mode with a warning.
 
-   - @1@option@1@bytes@2@option@2@: Interpret the password as a literal
+   - :samp:`bytes`: 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 @1@option@1@@filename@2@option@2@ option to do it,
+     you can use the :samp:`@filename` 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.
 
-   - @1@option@1@hex-bytes@2@option@2@: Interpret the password as a
+   - :samp:`hex-bytes`: 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
-     @1@option@1@bytes@2@option@2@, this option may allow creation of
+     :samp:`bytes`, 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 it possible to specify
      strings that are encoded in some manner other than the system's
      default encoding.
 
-@1@option@1@--rotate=[+|-]angle[:page-range]@2@option@2@
+:samp:`--rotate=[+|-]angle[:page-range]`
    Apply rotation to specified pages. The
-   @1@option@1@page-range@2@option@2@ portion of the option value has
+   :samp:`page-range` portion of the option value has
    the same format as page ranges in `Page Selection
    Options <#ref.page-selection>`__. If the page range is omitted, the
-   rotation is applied to all pages. The @1@option@1@angle@2@option@2@
+   rotation is applied to all pages. The :samp:`angle`
    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@,
+   preceded by :samp:`+` or :samp:`-`,
    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
@@ -757,7 +757,7 @@ needed transformations.
    out.pdf --rotate=+180` would rotate all pages by 180
    degrees.
 
-@1@option@1@--keep-files-open=@1@replaceable@1@[yn]@2@replaceable@2@@2@option@2@
+:samp:`--keep-files-open=@1@replaceable@1@[yn]@2@replaceable@2@`
    This option controls whether qpdf keeps individual files open while
    merging. Prior to version 8.1.0, qpdf always kept all files open, but
    this meant that the number of files that could be merged was limited
@@ -770,45 +770,45 @@ needed transformations.
    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
-   @1@option@1@--keep-files-open@2@option@2@ flag. If you are merging
+   :samp:`--keep-files-open` 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
-   @1@option@1@--keep-files-open=y@2@option@2@, especially if working
+   :samp:`--keep-files-open=y`, 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
-   @1@option@1@--keep-files-open=n@2@option@2@. The threshold for
+   :samp:`--keep-files-open=n`. The threshold for
    switching may be changed from the default 200 with the
-   @1@option@1@--keep-files-open-threshold@2@option@2@ option.
+   :samp:`--keep-files-open-threshold` option.
 
-@1@option@1@--keep-files-open-threshold=@1@replaceable@1@count@2@replaceable@2@@2@option@2@
+:samp:`--keep-files-open-threshold=@1@replaceable@1@count@2@replaceable@2@`
    If specified, overrides the default value of 200 used as the
    threshold for qpdf deciding whether or not to keep files open. See
-   @1@option@1@--keep-files-open@2@option@2@ for details.
+   :samp:`--keep-files-open` for details.
 
-@1@option@1@--pages options --@2@option@2@
+:samp:`--pages options --`
    Select specific pages from one or more input files. See `Page
    Selection Options <#ref.page-selection>`__ for details on how to do
    page selection (splitting and merging).
 
-@1@option@1@--collate=@1@replaceable@1@n@2@replaceable@2@@2@option@2@
+:samp:`--collate=@1@replaceable@1@n@2@replaceable@2@`
    When specified, collate rather than concatenate pages from files
-   specified with @1@option@1@--pages@2@option@2@. With a numeric
+   specified with :samp:`--pages`. With a numeric
    argument, collate in groups of @1@replaceable@1@n@2@replaceable@2@.
    The default is 1. See `Page Selection
    Options <#ref.page-selection>`__ for additional details.
 
-@1@option@1@--flatten-rotation@2@option@2@
+:samp:`--flatten-rotation`
    For each page that is rotated using the ``/Rotate`` key in the page's
    dictionary, remove the ``/Rotate`` key and implement the identical
    rotation semantics by modifying the page's contents. This option can
    be useful to prepare files for buggy PDF applications that don't
    properly handle rotated pages.
 
-@1@option@1@--split-pages=[n]@2@option@2@
-   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
+:samp:`--split-pages=[n]`
+   Write each group of :samp:`n` pages to a separate
+   output file. If :samp:`n` is not specified, create
    single pages. Output file names are generated as follows:
 
    - If the string ``%d`` appears in the output file name, it is
@@ -845,24 +845,24 @@ needed transformations.
    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` 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
+   :samp:`--pages` option once for each file. Using
+   :samp:`--split-pages` is much faster if you don't
    require the global data.
 
-@1@option@1@--overlay options --@2@option@2@
+:samp:`--overlay options --`
    Overlay pages from another file onto the output pages. See `Overlay
    and Underlay Options <#ref.overlay-underlay>`__ for details on
    overlay/underlay.
 
-@1@option@1@--underlay options --@2@option@2@
+:samp:`--underlay options --`
    Overlay pages from another file onto the output pages. See `Overlay
    and Underlay Options <#ref.overlay-underlay>`__ for details on
    overlay/underlay.
 
 Password-protected files may be opened by specifying a password. By
 default, qpdf will preserve any encryption data associated with a file.
-If @1@option@1@--decrypt@2@option@2@ is specified, qpdf will attempt to
-remove any encryption information. If @1@option@1@--encrypt@2@option@2@
+If :samp:`--decrypt` is specified, qpdf will attempt to
+remove any encryption information. If :samp:`--encrypt`
 is specified, qpdf will replace the document's encryption parameters
 with whatever is specified.
 
@@ -893,9 +893,9 @@ The syntax is
 
 ::
 
-   @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@
+   --encrypt user-password owner-password key-length [ restrictions ] --
 
-Note that "@1@option@1@--@2@option@2@" terminates parsing of encryption
+Note that ":samp:`--`" terminates parsing of encryption
 flags and must be present even if no restrictions are present.
 
 Either or both of the user password and the owner password may be empty
@@ -903,34 +903,34 @@ strings. Starting in qpdf 10.2, qpdf defaults to not 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
-@1@option@1@--allow-insecure@2@option@2@, as described below.
+:samp:`--allow-insecure`, as described below.
 
 The value for
-@1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@ may
+:samp:`@1@replaceable@1@key-length@2@replaceable@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.
 
-If @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@
+If :samp:`@1@replaceable@1@key-length@2@replaceable@2@`
 is 40, the following restriction options are available:
 
-@1@option@1@--print=[yn]@2@option@2@
+:samp:`--print=[yn]`
    Determines whether or not to allow printing.
 
-@1@option@1@--modify=[yn]@2@option@2@
+:samp:`--modify=[yn]`
    Determines whether or not to allow document modification.
 
-@1@option@1@--extract=[yn]@2@option@2@
+:samp:`--extract=[yn]`
    Determines whether or not to allow text/image extraction.
 
-@1@option@1@--annotate=[yn]@2@option@2@
+:samp:`--annotate=[yn]`
    Determines whether or not to allow comments and form fill-in and
    signing.
 
-If @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@
+If :samp:`@1@replaceable@1@key-length@2@replaceable@2@`
 is 128, the following restriction options are available:
 
-@1@option@1@--accessibility=[yn]@2@option@2@
+:samp:`--accessibility=[yn]`
    Determines whether or not to allow accessibility to visually
    impaired. The qpdf library disregards this field when AES is used or
    when 256-bit encryption is used. You should really never disable
@@ -939,74 +939,74 @@ is 128, the following restriction options are available:
    conforming readers should disregard this permission and always allow
    accessibility.
 
-@1@option@1@--extract=[yn]@2@option@2@
+:samp:`--extract=[yn]`
    Determines whether or not to allow text/graphic extraction.
 
-@1@option@1@--assemble=[yn]@2@option@2@
+:samp:`--assemble=[yn]`
    Determines whether document assembly (rotation and reordering of
    pages) is allowed.
 
-@1@option@1@--annotate=[yn]@2@option@2@
+:samp:`--annotate=[yn]`
    Determines whether modifying annotations is allowed. This includes
    adding comments and filling in form fields. Also allows editing of
-   form fields if @1@option@1@--modify-other=y@2@option@2@ is given.
+   form fields if :samp:`--modify-other=y` is given.
 
-@1@option@1@--form=[yn]@2@option@2@
+:samp:`--form=[yn]`
    Determines whether filling form fields is allowed.
 
-@1@option@1@--modify-other=[yn]@2@option@2@
+:samp:`--modify-other=[yn]`
    Allow all document editing except those controlled separately 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.
+   :samp:`--assemble`,
+   :samp:`--annotate`, and
+   :samp:`--form` options.
 
-@1@option@1@--print=@1@replaceable@1@print-opt@2@replaceable@2@@2@option@2@
+:samp:`--print=@1@replaceable@1@print-opt@2@replaceable@2@`
    Controls printing access.
-   @1@option@1@@1@replaceable@1@print-opt@2@replaceable@2@@2@option@2@
+   :samp:`@1@replaceable@1@print-opt@2@replaceable@2@`
    may be one of the following:
 
-   - @1@option@1@full@2@option@2@: allow full printing
+   - :samp:`full`: allow full printing
 
-   - @1@option@1@low@2@option@2@: allow low-resolution printing only
+   - :samp:`low`: allow low-resolution printing only
 
-   - @1@option@1@none@2@option@2@: disallow printing
+   - :samp:`none`: disallow printing
 
-@1@option@1@--modify=@1@replaceable@1@modify-opt@2@replaceable@2@@2@option@2@
+:samp:`--modify=@1@replaceable@1@modify-opt@2@replaceable@2@`
    Controls modify access. This way of controlling modify access has
    less granularity than new options added in qpdf 8.4.
-   @1@option@1@@1@replaceable@1@modify-opt@2@replaceable@2@@2@option@2@
+   :samp:`@1@replaceable@1@modify-opt@2@replaceable@2@`
    may be one of the following:
 
-   - @1@option@1@all@2@option@2@: allow full document modification
+   - :samp:`all`: allow full document modification
 
-   - @1@option@1@annotate@2@option@2@: allow comment authoring, form
+   - :samp:`annotate`: allow comment authoring, form
      operations, and document assembly
 
-   - @1@option@1@form@2@option@2@: allow form field fill-in and signing
+   - :samp:`form`: allow form field fill-in and signing
      and document assembly
 
-   - @1@option@1@assembly@2@option@2@: allow document assembly only
+   - :samp:`assembly`: allow document assembly only
 
-   - @1@option@1@none@2@option@2@: allow no modifications
+   - :samp:`none`: allow no modifications
 
-   Using the @1@option@1@--modify@2@option@2@ option does not allow you
+   Using the :samp:`--modify` 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 @1@option@1@--modify=form
-   --assembly=n@2@option@2@ to fine tune.
+   individually, or you can use something like :samp:`--modify=form
+   --assembly=n` to fine tune.
 
-@1@option@1@--cleartext-metadata@2@option@2@
+:samp:`--cleartext-metadata`
    If specified, any metadata stream in the document will be left
    unencrypted even if the rest of the document is encrypted. This also
    forces the PDF version to be at least 1.5.
 
-@1@option@1@--use-aes=[yn]@2@option@2@
-   If @1@option@1@--use-aes=y@2@option@2@ is specified, AES encryption
+:samp:`--use-aes=[yn]`
+   If :samp:`--use-aes=y` is specified, AES encryption
    will be used instead of RC4 encryption. This forces the PDF version
    to be at least 1.6.
 
-@1@option@1@--allow-insecure@2@option@2@
+:samp:`--allow-insecure`
    From qpdf 10.2, qpdf defaults to not allowing creation of PDF files
    where the user password is non-empty, the owner password is empty,
    and a 256-bit key is in use. Files created in this way are insecure
@@ -1015,27 +1015,27 @@ is 128, the following restriction options are available:
    intentionally created strange files for testing (a definite valid use
    of qpdf!), this option allows you to create such insecure files.
 
-@1@option@1@--force-V4@2@option@2@
+:samp:`--force-V4`
    Use of this option forces the ``/V`` and ``/R`` parameters in the
    document's encryption dictionary to be set to the value ``4``. As
    qpdf will automatically do this when required, there is no reason to
    ever use this option. It exists primarily for use in testing qpdf
    itself. This option also forces the PDF version to be at least 1.5.
 
-If @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@
+If :samp:`@1@replaceable@1@key-length@2@replaceable@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:
 
-@1@option@1@--use-aes@2@option@2@
+:samp:`--use-aes`
    This option is not available with 256-bit keys. AES is always used
    with 256-bit encryption keys.
 
-@1@option@1@--force-V4@2@option@2@
+:samp:`--force-V4`
    This option is not available with 256 keys.
 
-@1@option@1@--force-R5@2@option@2@
+:samp:`--force-R5`
    If specified, qpdf sets the minimum version to 1.7 at extension level
    3 and writes the deprecated encryption format used by Acrobat version
    IX. This option should not be used in practice to generate PDF files
@@ -1057,11 +1057,11 @@ replaced with pages as specified.
 
 ::
 
-   @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@
+   --pages input-file [ --password=password ] [ page-range ] [ ... ] --
 
 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 "@1@option@1@--@2@option@2@" terminates
+the range of pages. Note that ":samp:`--`" terminates
 parsing of page selection flags.
 
 Starting with qpf 8.4, the special input file name
@@ -1077,7 +1077,7 @@ password here. The same file can be repeated 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
-@1@option@1@--empty@2@option@2@ as the primary input.
+:samp:`--empty` as the primary input.
 
 Starting with qpdf 5.0.0, it is possible to omit the page range. If qpdf
 sees a value in the place where it expects a page range and that value
@@ -1117,10 +1117,10 @@ Example page ranges:
   8, 9, and 12.
 
 Starting in qpdf version 8.3, you can specify the
-@1@option@1@--collate@2@option@2@ option. Note that this option is
-specified outside of @1@option@1@--pages ... --@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
+:samp:`--collate` option. Note that this option is
+specified outside of :samp:`--pages ... --`. When
+:samp:`--collate` is specified, it changes the meaning
+of :samp:`--pages` so that the specified files, as
 modified by page ranges, are collated rather than concatenated. For
 example, if you add the files :file:`odd.pdf` and
 :file:`even.pdf` containing odd and even pages of a
@@ -1153,8 +1153,8 @@ following pages in this order:
 - a.pdf page 5
 
 Starting in qpdf version 10.2, you may specify a numeric argument to
-@1@option@1@--collate@2@option@2@. With
-@1@option@1@--collate=@1@replaceable@1@n@2@replaceable@2@@2@option@2@,
+:samp:`--collate`. With
+:samp:`--collate=@1@replaceable@1@n@2@replaceable@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
@@ -1191,14 +1191,14 @@ remaining bookmarks will not work. A future version of
 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
-@1@option@1@--empty@2@option@2@ as the primary input file to avoid
+:samp:`--empty` 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 :file:`infile.pdf` while preserving
 all metadata associated with that file, you could use
 
 ::
 
-   :command:`qpdf` @1@option@1@infile.pdf --pages . 1-5 -- outfile.pdf@2@option@2@
+   qpdf infile.pdf --pages . 1-5 -- outfile.pdf
 
 If you wanted pages 1 through 5 from
 :file:`infile.pdf` but you wanted the rest of the
@@ -1206,7 +1206,7 @@ metadata to be dropped, you could instead run
 
 ::
 
-   :command:`qpdf` @1@option@1@--empty --pages infile.pdf 1-5 -- outfile.pdf@2@option@2@
+   qpdf --empty --pages infile.pdf 1-5 -- outfile.pdf
 
 If you wanted to take pages 1 through 5 from
 :file:`file1.pdf` and pages 11 through 15 from
@@ -1215,7 +1215,7 @@ metadata from :file:`file2.pdf`, you would run
 
 ::
 
-   :command:`qpdf` @1@option@1@file2.pdf --pages file1.pdf 1-5 . 15-11 -- outfile.pdf@2@option@2@
+   qpdf file2.pdf --pages file1.pdf 1-5 . 15-11 -- outfile.pdf
 
 If, for some reason, you wanted to take the first page of an encrypted
 file called :file:`encrypted.pdf` with password
@@ -1224,12 +1224,12 @@ drop document-level metadata but preserve encryption, you would use
 
 ::
 
-   :command:`qpdf` @1@option@1@--empty --copy-encryption=encrypted.pdf --encryption-file-password=pass
+   qpdf --empty --copy-encryption=encrypted.pdf --encryption-file-password=pass
    --pages encrypted.pdf --password=pass 1 ./encrypted.pdf --password=pass 1 --
-   outfile.pdf@2@option@2@
+   outfile.pdf
 
 Note that we had to specify the password all three times because giving
-a password as @1@option@1@--encryption-file-password@2@option@2@ doesn't
+a password as :samp:`--encryption-file-password` doesn't
 count for page selection, and as far as qpdf is concerned,
 :file:`encrypted.pdf` and
 :file:`./encrypted.pdf` are separated files. These
@@ -1260,11 +1260,11 @@ underlay as follows:
 
 ::
 
-   { @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@
+   { --overlay | --underlay } file [ options ] --
 
 Overlay and underlay options are processed late, so they can be combined
 with other like merging and will apply to the final output. The
-@1@option@1@--overlay@2@option@2@ and @1@option@1@--underlay@2@option@2@
+:samp:`--overlay` and :samp:`--underlay`
 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
@@ -1276,29 +1276,29 @@ from the overlay/underlay file in sequence and applied to corresponding
 pages in the output until there are no more output 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 @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:
+between the :samp:`--overlay` or
+:samp:`--underlay` flag and the
+:samp:`--` option. The following options are supported:
 
-- @1@option@1@--password=password@2@option@2@: supply a password if the
+- :samp:`--password=password`: supply a password if the
   overlay/underlay file is encrypted.
 
-- @1@option@1@--to=page-range@2@option@2@: a range of pages in the same
+- :samp:`--to=page-range`: a range of pages in the same
   form at described in `Page Selection Options <#ref.page-selection>`__
   indicates which pages in the output should have the overlay/underlay
   applied. If not specified, overlay/underlay are applied to all pages.
 
-- @1@option@1@--from=[page-range]@2@option@2@: a range of pages that
+- :samp:`--from=[page-range]`: 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
-  @1@option@1@--repeat@2@option@2@ is used.
+  :samp:`--repeat` is used.
 
-- @1@option@1@--repeat=page-range@2@option@2@: an optional range of
+- :samp:`--repeat=page-range`: an optional range of
   pages that specifies which pages in the overlay/underlay file will be
   repeated after the "from" pages are used up. If you want to repeat a
   range of pages starting at the beginning, you can explicitly use
-  @1@option@1@--from=@2@option@2@.
+  :samp:`--from=`.
 
 Here are some examples.
 
@@ -1323,78 +1323,78 @@ Embedded Files/Attachments Options
 Starting with qpdf 10.2, you can work with file attachments in PDF files
 from the command line. The following options are available:
 
-@1@option@1@--list-attachments@2@option@2@
+:samp:`--list-attachments`
    Show the "key" and stream number for embedded files. With
-   @1@option@1@--verbose@2@option@2@, additional information, including
+   :samp:`--verbose`, 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 other options.
 
-@1@option@1@--show-attachment=@1@replaceable@1@key@2@replaceable@2@@2@option@2@
+:samp:`--show-attachment=@1@replaceable@1@key@2@replaceable@2@`
    Write the contents of the specified attachment to standard output as
    binary data. The key should match one of the keys shown by
-   @1@option@1@--list-attachments@2@option@2@. If specified multiple
+   :samp:`--list-attachments`. If specified multiple
    times, only the last attachment will be shown.
 
-@1@option@1@--add-attachment @1@replaceable@1@file@2@replaceable@2@ @1@replaceable@1@options@2@replaceable@2@ --@2@option@2@
+:samp:`--add-attachment @1@replaceable@1@file@2@replaceable@2@ @1@replaceable@1@options@2@replaceable@2@ --`
    Add or replace an attachment with the contents of
    @1@replaceable@1@file@2@replaceable@2@. This may be specified more
    than once. The following additional options may appear before the
    ``--`` that ends this option:
 
-   @1@option@1@--key=@1@replaceable@1@key@2@replaceable@2@@2@option@2@
+   :samp:`--key=@1@replaceable@1@key@2@replaceable@2@`
       The key to use to register the attachment in the embedded files
       table. Defaults to the last path element of
       @1@replaceable@1@file@2@replaceable@2@.
 
-   @1@option@1@--filename=@1@replaceable@1@name@2@replaceable@2@@2@option@2@
+   :samp:`--filename=@1@replaceable@1@name@2@replaceable@2@`
       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 @1@replaceable@1@file@2@replaceable@2@.
 
-   @1@option@1@--creationdate=@1@replaceable@1@date@2@replaceable@2@@2@option@2@
+   :samp:`--creationdate=@1@replaceable@1@date@2@replaceable@2@`
       The attachment's creation date in PDF format; defaults to the
       current time. The date format is explained below.
 
-   @1@option@1@--moddate=@1@replaceable@1@date@2@replaceable@2@@2@option@2@
+   :samp:`--moddate=@1@replaceable@1@date@2@replaceable@2@`
       The attachment's modification date in PDF format; defaults to the
       current time. The date format is explained below.
 
-   @1@option@1@--mimetype=@1@replaceable@1@type/subtype@2@replaceable@2@@2@option@2@
+   :samp:`--mimetype=@1@replaceable@1@type/subtype@2@replaceable@2@`
       The mime type for the attachment, e.g. ``text/plain`` or
       ``application/pdf``. Note that the mimetype appears in a field
       called ``/Subtype`` in the PDF but actually includes the full type
       and subtype of the mime type.
 
-   @1@option@1@--description=@1@replaceable@1@"text"@2@replaceable@2@@2@option@2@
+   :samp:`--description=@1@replaceable@1@"text"@2@replaceable@2@`
       Descriptive text for the attachment, displayed by some PDF
       viewers.
 
-   @1@option@1@--replace@2@option@2@
+   :samp:`--replace`
       Indicates that any existing attachment with the same key should be
       replaced by the new attachment. Otherwise,
       :command:`qpdf` gives an error if an attachment
       with that key is already present.
 
-@1@option@1@--remove-attachment=@1@replaceable@1@key@2@replaceable@2@@2@option@2@
+:samp:`--remove-attachment=@1@replaceable@1@key@2@replaceable@2@`
    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 @1@option@1@--verbose@2@option@2@ to see status of
+   times. Run with :samp:`--verbose` to see status of
    the removal.
 
-@1@option@1@--copy-attachments-from @1@replaceable@1@file@2@replaceable@2@ @1@replaceable@1@options@2@replaceable@2@ --@2@option@2@
+:samp:`--copy-attachments-from @1@replaceable@1@file@2@replaceable@2@ @1@replaceable@1@options@2@replaceable@2@ --`
    Copy attachments from another file. This may be specified more than
    once. The following additional options may appear before the ``--``
    that ends this option:
 
-   @1@option@1@--password=@1@replaceable@1@password@2@replaceable@2@@2@option@2@
+   :samp:`--password=@1@replaceable@1@password@2@replaceable@2@`
       If required, the password needed to open
       @1@replaceable@1@file@2@replaceable@2@
 
-   @1@option@1@--prefix=@1@replaceable@1@prefix@2@replaceable@2@@2@option@2@
+   :samp:`--prefix=@1@replaceable@1@prefix@2@replaceable@2@`
       Only required if the file from which attachments are being copied
       has attachments with keys that conflict with attachments already
       in the file. In this case, the specified prefix will be prepended
@@ -1420,10 +1420,10 @@ are of use to people who are working with damaged files. There is little
 reason to use these options unless you are trying to solve specific
 problems. The following options are available:
 
-@1@option@1@--suppress-recovery@2@option@2@
+:samp:`--suppress-recovery`
    Prevents qpdf from attempting to recover damaged files.
 
-@1@option@1@--ignore-xref-streams@2@option@2@
+:samp:`--ignore-xref-streams`
    Tells qpdf to ignore any cross-reference streams.
 
 Ordinarily, qpdf will attempt to recover from certain types of errors in
@@ -1432,12 +1432,12 @@ types of object numbering errors, and certain types 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
-@1@option@1@--suppress-recovery@2@option@2@ option will prevent qpdf
+:samp:`--suppress-recovery` option will prevent qpdf
 from attempting recovery. In this case, it will fail on the first error
 that it encounters.
 
 Ordinarily, qpdf reads cross-reference streams when they are present in
-a PDF file. If @1@option@1@--ignore-xref-streams@2@option@2@ is
+a PDF file. If :samp:`--ignore-xref-streams` 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 streams. It is almost
@@ -1456,99 +1456,99 @@ output file. Mostly these are of use only to people who are very
 familiar with the PDF file format or who are PDF developers. The
 following options are available:
 
-@1@option@1@--compress-streams=@1@replaceable@1@[yn]@2@replaceable@2@@2@option@2@
-   By default, or with @1@option@1@--compress-streams=y@2@option@2@,
+:samp:`--compress-streams=@1@replaceable@1@[yn]@2@replaceable@2@`
+   By default, or with :samp:`--compress-streams=y`,
    qpdf will compress any stream with no other filters applied to it
    with the ``/FlateDecode`` filter when it writes it. To suppress this
    behavior and preserve uncompressed streams as uncompressed, use
-   @1@option@1@--compress-streams=n@2@option@2@.
+   :samp:`--compress-streams=n`.
 
-@1@option@1@--decode-level=@1@replaceable@1@option@2@replaceable@2@@2@option@2@
+:samp:`--decode-level=@1@replaceable@1@option@2@replaceable@2@`
    Controls which streams qpdf tries to decode. The default is
-   @1@option@1@generalized@2@option@2@. The following options are
+   :samp:`generalized`. The following options are
    available:
 
-   - @1@option@1@none@2@option@2@: do not attempt to decode any streams
+   - :samp:`none`: do not attempt to decode any streams
 
-   - @1@option@1@generalized@2@option@2@: decode streams filtered with
+   - :samp:`generalized`: decode streams filtered with
      supported generalized filters: ``/LZWDecode``, ``/FlateDecode``,
      ``/ASCII85Decode``, and ``/ASCIIHexDecode``. We define generalized
      filters as those to be used for general-purpose compression or
      encoding, as opposed to filters specifically designed for image
      data. Note that, by default, streams already compressed with
      ``/FlateDecode`` are not uncompressed and recompressed unless you
-     also specify @1@option@1@--recompress-flate@2@option@2@.
+     also specify :samp:`--recompress-flate`.
 
-   - @1@option@1@specialized@2@option@2@: in addition to generalized,
+   - :samp:`specialized`: in addition to generalized,
      decode streams with supported non-lossy specialized filters;
      currently this is just ``/RunLengthDecode``
 
-   - @1@option@1@all@2@option@2@: in addition to generalized and
+   - :samp:`all`: in addition to generalized and
      specialized, decode streams with supported lossy filters;
      currently this is just ``/DCTDecode`` (JPEG)
 
-@1@option@1@--stream-data=@1@replaceable@1@option@2@replaceable@2@@2@option@2@
+:samp:`--stream-data=@1@replaceable@1@option@2@replaceable@2@`
    Controls transformation of stream data. This option predates the
-   @1@option@1@--compress-streams@2@option@2@ and
-   @1@option@1@--decode-level@2@option@2@ options. Those options can be
+   :samp:`--compress-streams` and
+   :samp:`--decode-level` options. Those options can be
    used to achieve the same affect with more control. The value of
-   @1@option@1@@1@replaceable@1@option@2@replaceable@2@@2@option@2@ may
+   :samp:`@1@replaceable@1@option@2@replaceable@2@` may
    be one of the following:
 
-   - @1@option@1@compress@2@option@2@: recompress stream data when
+   - :samp:`compress`: recompress stream data when
      possible (default); equivalent to
-     @1@option@1@--compress-streams=y@2@option@2@
-     @1@option@1@--decode-level=generalized@2@option@2@. Does not
+     :samp:`--compress-streams=y`
+     :samp:`--decode-level=generalized`. Does not
      recompress streams already compressed with ``/FlateDecode`` unless
-     @1@option@1@--recompress-flate@2@option@2@ is also specified.
+     :samp:`--recompress-flate` is also specified.
 
-   - @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@
+   - :samp:`preserve`: leave all stream data as is;
+     equivalent to :samp:`--compress-streams=n`
+     :samp:`--decode-level=none`
 
-   - @1@option@1@uncompress@2@option@2@: uncompress stream data
+   - :samp:`uncompress`: uncompress stream data
      compressed with generalized filters when possible; equivalent to
-     @1@option@1@--compress-streams=n@2@option@2@
-     @1@option@1@--decode-level=generalized@2@option@2@
+     :samp:`--compress-streams=n`
+     :samp:`--decode-level=generalized`
 
-@1@option@1@--recompress-flate@2@option@2@
+:samp:`--recompress-flate`
    By default, streams already compressed with ``/FlateDecode`` are left
    alone rather than being uncompressed and recompressed. This option
    causes qpdf 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
-   @1@option@1@--compression-level@2@option@2@.
+   :samp:`--compression-level`.
 
-@1@option@1@--compression-level=@1@replaceable@1@level@2@replaceable@2@@2@option@2@
+:samp:`--compression-level=@1@replaceable@1@level@2@replaceable@2@`
    When writing new streams that are compressed with ``/FlateDecode``,
    use the specified compression level. The value of
-   @1@option@1@level@2@option@2@ should be a number from 1 to 9 and is
+   :samp:`level` 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 @1@option@1@--recompress-flate@2@option@2@. If your goal is
+   specify :samp:`--recompress-flate`. If your goal is
    to shrink the size of PDF files, you should also use
-   @1@option@1@--object-streams=generate@2@option@2@.
+   :samp:`--object-streams=generate`.
 
-@1@option@1@--normalize-content=[yn]@2@option@2@
+:samp:`--normalize-content=[yn]`
    Enables or disables normalization of content streams. Content
    normalization is enabled by default in QDF mode. Please see `QDF
    Mode <#ref.qdf>`__ for additional discussion of QDF mode.
 
-@1@option@1@--object-streams=@1@replaceable@1@mode@2@replaceable@2@@2@option@2@
+:samp:`--object-streams=@1@replaceable@1@mode@2@replaceable@2@`
    Controls handling of object streams. The value of
-   @1@option@1@@1@replaceable@1@mode@2@replaceable@2@@2@option@2@ may be
+   :samp:`@1@replaceable@1@mode@2@replaceable@2@` may be
    one of the following:
 
-   - @1@option@1@preserve@2@option@2@: preserve original object streams
+   - :samp:`preserve`: preserve original object streams
      (default)
 
-   - @1@option@1@disable@2@option@2@: don't write any object streams
+   - :samp:`disable`: don't write any object streams
 
-   - @1@option@1@generate@2@option@2@: use object streams wherever
+   - :samp:`generate`: use object streams wherever
      possible
 
-@1@option@1@--preserve-unreferenced@2@option@2@
+:samp:`--preserve-unreferenced`
    Tells qpdf to preserve objects that are not referenced when writing
    the file. Ordinarily any object that is not referenced in a traversal
    of the document from the trailer dictionary will be discarded. This
@@ -1562,10 +1562,10 @@ following options are available:
    indirect differently from the original file, and the original file
    may have gaps in its numbering.
 
-   See also @1@option@1@--preserve-unreferenced-resources@2@option@2@,
+   See also :samp:`--preserve-unreferenced-resources`,
    which does something completely different.
 
-@1@option@1@--remove-unreferenced-resources=@1@replaceable@1@option@2@replaceable@2@@2@option@2@
+:samp:`--remove-unreferenced-resources=@1@replaceable@1@option@2@replaceable@2@`
    The @1@replaceable@1@option@2@replaceable@2@ may be ``auto``,
    ``yes``, or ``no``. The default is ``auto``.
 
@@ -1592,14 +1592,14 @@ following options are available:
    be removing. If you encounter that case, please report it as bug at
    https://github.com/qpdf/qpdf/issues/.
 
-@1@option@1@--preserve-unreferenced-resources@2@option@2@
+:samp:`--preserve-unreferenced-resources`
    This is a synonym for
-   @1@option@1@--remove-unreferenced-resources=no@2@option@2@.
+   :samp:`--remove-unreferenced-resources=no`.
 
-   See also @1@option@1@--preserve-unreferenced@2@option@2@, which does
+   See also :samp:`--preserve-unreferenced`, which does
    something completely different.
 
-@1@option@1@--newline-before-endstream@2@option@2@
+:samp:`--newline-before-endstream`
    Tells qpdf to insert a newline before the ``endstream`` keyword, not
    counted in the length, after any stream content even if the last
    character of the stream was a newline. This may result in two
@@ -1608,7 +1608,7 @@ following options are available:
    at least prevents it from removing compliance on already compliant
    files.
 
-@1@option@1@--linearize-pass1=@1@replaceable@1@file@2@replaceable@2@@2@option@2@
+:samp:`--linearize-pass1=@1@replaceable@1@file@2@replaceable@2@`
    Write the first pass of linearization to the named file. The
    resulting file is not a valid PDF file. This option is useful only
    for debugging ``QPDFWriter``'s linearization code. When qpdf
@@ -1617,7 +1617,7 @@ following options are available:
    and the linearization dictionary. Ordinarily, the first pass is
    discarded. This option enables it to be captured.
 
-@1@option@1@--coalesce-contents@2@option@2@
+:samp:`--coalesce-contents`
    When a page's contents are split across multiple streams, this option
    causes qpdf to combine them into a single stream. Use of this option
    is never necessary for ordinary usage, but it can help when working
@@ -1625,7 +1625,7 @@ following options are available:
    with QDF mode or content normalization to make it easier to look at
    all of a page's contents at once.
 
-@1@option@1@--flatten-annotations=@1@replaceable@1@option@2@replaceable@2@@2@option@2@
+:samp:`--flatten-annotations=@1@replaceable@1@option@2@replaceable@2@`
    This option collapses annotations into the pages' contents with
    special handling for form fields. Ordinarily, an annotation is
    rendered separately and on top of the page. Combining annotations
@@ -1637,13 +1637,13 @@ following options are available:
    annotations. The @1@replaceable@1@option@2@replaceable@2@ parameter
    may be any of the following:
 
-   - @1@option@1@all@2@option@2@: include all annotations that are not
+   - :samp:`all`: include all annotations that are not
      marked invisible or hidden
 
-   - @1@option@1@print@2@option@2@: only include annotations that
+   - :samp:`print`: only include annotations that
      indicate that they should appear when the page is printed
 
-   - @1@option@1@screen@2@option@2@: omit annotations that indicate
+   - :samp:`screen`: omit annotations that indicate
      they should not appear on the screen
 
    Note that form fields are special because the annotations that are
@@ -1655,14 +1655,14 @@ following options are available:
    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
-   @1@option@1@--generate-appearances@2@option@2@ option below.
+   :samp:`--generate-appearances` option below.
 
-@1@option@1@--generate-appearances@2@option@2@
+:samp:`--generate-appearances`
    If a file contains interactive form fields and indicates that the
    appearances are out of date with the values of the form, 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 @1@option@1@--flatten-annotations@2@option@2@
+   before using the :samp:`--flatten-annotations`
    option. Most of these are not a problem with well-behaved PDF files.
    The limitations are as follows:
 
@@ -1690,61 +1690,61 @@ following options are available:
    application to save your filled-in form before processing it with
    qpdf.
 
-@1@option@1@--optimize-images@2@option@2@
+:samp:`--optimize-images`
    This flag causes qpdf to recompress all images that are not
    compressed with DCT (JPEG) using DCT compression as long as 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
-   @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
+   :samp:`--verbose`. See also the
+   :samp:`--oi-min-width`,
+   :samp:`--oi-min-height`, and
+   :samp:`--oi-min-area` options. By default, starting
    in qpdf 8.4, inline images are converted to regular images and
-   optimized as well. Use @1@option@1@--keep-inline-images@2@option@2@
+   optimized as well. Use :samp:`--keep-inline-images`
    to prevent inline images from being included.
 
-@1@option@1@--oi-min-width=@1@replaceable@1@width@2@replaceable@2@@2@option@2@
+:samp:`--oi-min-width=@1@replaceable@1@width@2@replaceable@2@`
    Avoid optimizing images whose width is below the specified amount. If
    omitted, the default is 128 pixels. Use 0 for no minimum.
 
-@1@option@1@--oi-min-height=@1@replaceable@1@height@2@replaceable@2@@2@option@2@
+:samp:`--oi-min-height=@1@replaceable@1@height@2@replaceable@2@`
    Avoid optimizing images whose height is below the specified amount.
    If omitted, the default is 128 pixels. Use 0 for no minimum.
 
-@1@option@1@--oi-min-area=@1@replaceable@1@area-in-pixels@2@replaceable@2@@2@option@2@
+:samp:`--oi-min-area=@1@replaceable@1@area-in-pixels@2@replaceable@2@`
    Avoid optimizing images whose pixel count (width × height) is below
    the specified amount. If omitted, the default is 16,384 pixels. Use 0
    for no minimum.
 
-@1@option@1@--externalize-inline-images@2@option@2@
+:samp:`--externalize-inline-images`
    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 @1@option@1@--ii-min-bytes@2@option@2@ to change the
+   selected. Use :samp:`--ii-min-bytes` to change the
    size threshold. This option is implicitly selected 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
+   :samp:`--optimize-images` is selected. Use
+   :samp:`--keep-inline-images` to exclude inline images
    from image optimization.
 
-@1@option@1@--ii-min-bytes=@1@replaceable@1@bytes@2@replaceable@2@@2@option@2@
+:samp:`--ii-min-bytes=@1@replaceable@1@bytes@2@replaceable@2@`
    Avoid converting inline images whose size is below the specified
    minimum size to regular images. If omitted, the default is 1,024
    bytes. Use 0 for no minimum.
 
-@1@option@1@--keep-inline-images@2@option@2@
+:samp:`--keep-inline-images`
    Prevent inline images from being included in image optimization. This
-   option has no affect when @1@option@1@--optimize-images@2@option@2@
+   option has no affect when :samp:`--optimize-images`
    is not specified.
 
-@1@option@1@--remove-page-labels@2@option@2@
+:samp:`--remove-page-labels`
    Remove page labels from the output file.
 
-@1@option@1@--qdf@2@option@2@
+:samp:`--qdf`
    Turns on QDF mode. For additional information on QDF, please see `QDF
-   Mode <#ref.qdf>`__. Note that @1@option@1@--linearize@2@option@2@
+   Mode <#ref.qdf>`__. Note that :samp:`--linearize`
    disables QDF mode.
 
-@1@option@1@--min-version=@1@replaceable@1@version@2@replaceable@2@@2@option@2@
+:samp:`--min-version=@1@replaceable@1@version@2@replaceable@2@`
    Forces the PDF version of the output file to be at least
    @1@replaceable@1@version@2@replaceable@2@. In other words, if the
    input file has a lower version than the specified version, the
@@ -1762,11 +1762,11 @@ following options are available:
    version ``1.7.8`` represents version 1.7 at extension level 8. Note
    that minimal syntax checking is done on the command line.
 
-@1@option@1@--force-version=@1@replaceable@1@version@2@replaceable@2@@2@option@2@
+:samp:`--force-version=@1@replaceable@1@version@2@replaceable@2@`
    This option forces the PDF version to be the exact version specified
    *even when the file may have content that is not supported in that
    version*. The version number is interpreted in the same way as with
-   @1@option@1@--min-version@2@option@2@ so that extension levels can be
+   :samp:`--min-version` 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, 256-bit keys are disabled if
@@ -1793,9 +1793,9 @@ understands and is not already compressed using a good 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
-@1@option@1@--stream-data=compress@2@option@2@.
+:samp:`--stream-data=compress`.
 
-When @1@option@1@--normalize-content=y@2@option@2@ is specified, qpdf
+When :samp:`--normalize-content=y` 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 who wish to
@@ -1811,9 +1811,9 @@ string, name, or inline image. Note that files 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
-@1@option@1@--qdf --normalize-content=n@2@option@2@ for a QDF file
+:samp:`--qdf --normalize-content=n` for a QDF file
 without content normalization, or alternatively
-@1@option@1@--stream-data=uncompress@2@option@2@ for a regular non-QDF
+:samp:`--stream-data=uncompress` 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 the purpose of
@@ -1824,22 +1824,22 @@ the PDF specification at version 1.5, corresponding to Acrobat 6. Some
 older PDF viewers may not support files with 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: @1@option@1@preserve@2@option@2@,
-@1@option@1@disable@2@option@2@, and @1@option@1@generate@2@option@2@.
+modes: :samp:`preserve`,
+:samp:`disable`, and :samp:`generate`.
 
-In @1@option@1@preserve@2@option@2@ mode, the relationship to objects
+In :samp:`preserve` mode, the relationship to objects
 and the streams that contain them is preserved from the original file.
-In @1@option@1@disable@2@option@2@ mode, all objects are written as
+In :samp:`disable` 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 @1@option@1@generate@2@option@2@ mode, qpdf will
+be supported.) In :samp:`generate` 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.
 
-The @1@option@1@--qdf@2@option@2@ flag turns on QDF mode, which changes
+The :samp:`--qdf` 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 be overridden by
@@ -1862,7 +1862,7 @@ automated test suites for software that uses the qpdf library. When any
 of the options in this section are specified, no output file should be
 given. The following options are available:
 
-@1@option@1@--deterministic-id@2@option@2@
+:samp:`--deterministic-id`
    Causes generation of a deterministic value for /ID. This prevents use
    of timestamp and output file name information in the /ID generation.
    Instead, at some slight additional runtime cost, the /ID field is
@@ -1872,138 +1872,138 @@ given. The following options are available:
    caching results or for generation of some test data. Use of this flag
    is not compatible with creation of encrypted files.
 
-@1@option@1@--static-id@2@option@2@
+:samp:`--static-id`
    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
-   @1@option@1@--deterministic-id@2@option@2@ option.
+   :samp:`--deterministic-id` option.
 
-@1@option@1@--static-aes-iv@2@option@2@
+:samp:`--static-aes-iv`
    Causes use of a static initialization vector for AES-CBC. This is
    intended for testing only so that output files can be reproducible.
    Never use it for production files. This option in particular is not
    secure since it significantly weakens the encryption.
 
-@1@option@1@--no-original-object-ids@2@option@2@
+:samp:`--no-original-object-ids`
    Suppresses inclusion of original object ID comments in QDF files.
    This can be useful when generating QDF files for test purposes,
    particularly when comparing them to determine whether two PDF files
    have identical content.
 
-@1@option@1@--show-encryption@2@option@2@
+:samp:`--show-encryption`
    Shows document encryption parameters. Also shows the document's user
    password if the owner password is given.
 
-@1@option@1@--show-encryption-key@2@option@2@
+:samp:`--show-encryption-key`
    When encryption information is being displayed, as when
-   @1@option@1@--check@2@option@2@ or
-   @1@option@1@--show-encryption@2@option@2@ is given, display the
+   :samp:`--check` or
+   :samp:`--show-encryption` 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 @1@option@1@--password@2@option@2@ if the
-   @1@option@1@--password-is-hex-key@2@option@2@ is specified. Note
+   argument to :samp:`--password` if the
+   :samp:`--password-is-hex-key` 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 enables retrieval of that
    key.
 
-@1@option@1@--check-linearization@2@option@2@
+:samp:`--check-linearization`
    Checks file integrity and linearization status.
 
-@1@option@1@--show-linearization@2@option@2@
+:samp:`--show-linearization`
    Checks and displays all data in the linearization hint tables.
 
-@1@option@1@--show-xref@2@option@2@
+:samp:`--show-xref`
    Shows the contents of the cross-reference table in a human-readable
    form. This is especially useful for files with cross-reference
    streams which are stored in a binary format.
 
-@1@option@1@--show-object=trailer|obj[,gen]@2@option@2@
+:samp:`--show-object=trailer|obj[,gen]`
    Show the contents of the given object. This is especially useful for
    inspecting objects that are inside of object streams (also known as
    "compressed objects").
 
-@1@option@1@--raw-stream-data@2@option@2@
-   When used along with the @1@option@1@--show-object@2@option@2@
+:samp:`--raw-stream-data`
+   When used along with the :samp:`--show-object`
    option, if the object is a stream, shows the raw stream data instead
    of object's contents.
 
-@1@option@1@--filtered-stream-data@2@option@2@
-   When used along with the @1@option@1@--show-object@2@option@2@
+:samp:`--filtered-stream-data`
+   When used along with the :samp:`--show-object`
    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 issued.
 
-@1@option@1@--show-npages@2@option@2@
+:samp:`--show-npages`
    Prints the number of pages in the input file on a line by itself.
    Since the number of pages appears by itself on a line, this option
    can be useful for scripting if you need to know the number of pages
    in a file.
 
-@1@option@1@--show-pages@2@option@2@
+:samp:`--show-pages`
    Shows the object and generation number for each page dictionary
    object and for each content stream associated with the page. Having
    this information makes it more convenient to inspect objects from a
    particular page.
 
-@1@option@1@--with-images@2@option@2@
-   When used along with @1@option@1@--show-pages@2@option@2@, also shows
+:samp:`--with-images`
+   When used along with :samp:`--show-pages`, 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 discussed in a comment in the
    source code.)
 
-@1@option@1@--json@2@option@2@
+:samp:`--json`
    Generate a JSON representation of the file. This is described in
    depth in `QPDF JSON <#ref.json>`__
 
-@1@option@1@--json-help@2@option@2@
+:samp:`--json-help`
    Describe the format of the JSON output.
 
-@1@option@1@--json-key=key@2@option@2@
+:samp:`--json-key=key`
    This option is repeatable. If specified, only top-level keys
    specified will be included in the JSON output. If not specified, all
    keys will be shown.
 
-@1@option@1@--json-object=trailer|obj[,gen]@2@option@2@
+:samp:`--json-object=trailer|obj[,gen]`
    This option is repeatable. If specified, only specified objects will
    be shown in the "``objects``" key of the JSON output. If absent, all
    objects will be shown.
 
-@1@option@1@--check@2@option@2@
+:samp:`--check`
    Checks file structure and well as encryption, linearization, and
    encoding of stream data. A file for which
-   @1@option@1@--check@2@option@2@ reports no errors may still have
+   :samp:`--check` reports no errors may still have
    errors in stream data content but should otherwise be structurally
-   sound. If @1@option@1@--check@2@option@2@ any errors, qpdf will exit
+   sound. If :samp:`--check` any errors, qpdf will exit
    with a status of 2. There are some recoverable conditions that
-   @1@option@1@--check@2@option@2@ detects. These are issued as warnings
+   :samp:`--check` 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 2.0.4). When
-   @1@option@1@--check@2@option@2@ is combined with other options,
+   :samp:`--check` is combined with other options,
    checks are always performed before any other options are processed.
-   For erroneous files, @1@option@1@--check@2@option@2@ will cause qpdf
+   For erroneous files, :samp:`--check` will cause qpdf
    to attempt to recover, after which other options are effectively
    operating on the recovered file. Combining
-   @1@option@1@--check@2@option@2@ with other options in this way can be
+   :samp:`--check` with other options in this way can be
    useful for manually recovering severely damaged files. Note that
-   @1@option@1@--check@2@option@2@ produces no output to standard output
+   :samp:`--check` 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 :file:`/dev/null` and just
    check for a 0 exit code.
 
-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
+The :samp:`--raw-stream-data` and
+:samp:`--filtered-stream-data` options are ignored
+unless :samp:`--show-object` 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.
 
-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
+If :samp:`--filtered-stream-data` is given and
+:samp:`--normalize-content=y` 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.
@@ -2055,23 +2055,23 @@ would contain strings of even numbers of 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
-@1@option@1@--password-mode=bytes@2@option@2@ to suppress qpdf's
+:samp:`--password-mode=bytes` to suppress qpdf's
 automatic behavior.
 
-The @1@option@1@--password-mode@2@option@2@ option, as described earlier
+The :samp:`--password-mode` 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
-@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
+:samp:`--password-mode=bytes`. Another reason to use
+:samp:`--password-mode=bytes` 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
-@1@option@1@bytes@2@option@2@ password mode can enable you to do this.
+:samp:`bytes` password mode can enable you to do this.
 
 When qpdf attempts to decrypt a file with a password that contains
 non-ASCII characters, it will generate a list of alternative passwords
@@ -2089,7 +2089,7 @@ recovery methods should make qpdf transparently open most 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
-@1@option@1@--suppress-password-recovery@2@option@2@ option. One reason
+:samp:`--suppress-password-recovery` option. One reason
 to do that is to ensure that you know the exact password that was used
 to encrypt the file.
 
@@ -2105,7 +2105,7 @@ will be addressed in a future version of qpdf. The ``QPDFWriter``
 methods that enable encryption on the output file accept passwords as
 strings of bytes.
 
-Please note that the @1@option@1@--password-is-hex-key@2@option@2@
+Please note that the :samp:`--password-is-hex-key`
 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 forensic
@@ -2315,12 +2315,12 @@ cryptography algorithm, and MD5, which is a weak hashing algorithm. 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
-@1@option@1@--allow-weak-crypto@2@option@2@ option.
+:samp:`--allow-weak-crypto` option.
 
 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
-@1@option@1@--allow-weak-crypto@2@option@2@ flag and also to require
+:samp:`--allow-weak-crypto` flag and also to require
 explicit steps when using the C++ library to enable use of insecure
 cryptography.
 
@@ -2387,7 +2387,7 @@ Compatibility
 
 Documentation
    The :command:`qpdf` command can be invoked with the
-   @1@option@1@--json-help@2@option@2@ option. This will output a JSON
+   :samp:`--json-help` 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 specific
@@ -2470,7 +2470,7 @@ There are a few limitations to be aware of with the JSON structure:
   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
-  @1@option@1@--show-object@2@option@2@ option does not have this
+  :samp:`--show-object` option does not have this
   limitation and will reveal the string as encoded in the original
   file.
 
@@ -2486,9 +2486,9 @@ be aware of:
 - 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
-  @1@option@1@--json-keys@2@option@2@, the keys that are not listed
+  :samp:`--json-keys`, the keys that are not listed
   will be excluded entirely except for those that
-  @1@option@1@--json-help@2@option@2@ says are always present.
+  :samp:`--json-help` says are always present.
 
 - In a few places, there are keys with names containing
   ``pageposfrom1``. The values of these keys are null or an integer. If
@@ -2504,7 +2504,7 @@ be aware of:
 
 - The image information included in the ``page`` section of the JSON
   output includes the key "``filterable``". Note that the value of this
-  field may depend on the @1@option@1@--decode-level@2@option@2@ that
+  field may depend on the :samp:`--decode-level` that
   you invoke qpdf with. The JSON output includes a top-level key
   "``parameters``" that indicates the decode level used for computing
   whether a stream was filterable. For example, jpeg images will be
@@ -3630,8 +3630,8 @@ Implementation Notes
 --------------------
 
 There are three modes for writing object streams:
-@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
+:samp:`disable`, :samp:`preserve`, and
+:samp:`generate`. 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 streams such that
@@ -3642,7 +3642,7 @@ ourselves by grouping 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
-@1@option@1@preserve@2@option@2@.
+:samp:`preserve`.
 
 We do not support creation of hybrid files. When we write files, even in
 preserve mode, we will lose any xref tables and merge any appended
@@ -3697,7 +3697,7 @@ For a detailed list of changes, please see the file
   - Handling of Weak Cryptography Algorithms
 
     - From the qpdf CLI, the
-      @1@option@1@--allow-weak-crypto@2@option@2@ is now required to
+      :samp:`--allow-weak-crypto` 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, doing so will require explicit
@@ -3716,7 +3716,7 @@ For a detailed list of changes, please see the file
       (with no resource dictionary).
 
     - Fix crash that could occur under certain conditions when using
-      @1@option@1@--pages@2@option@2@ with files that had form
+      :samp:`--pages` with files that had form
       fields.
 
   - Library Enhancements
@@ -3735,7 +3735,7 @@ For a detailed list of changes, please see the file
   - CLI Enhancements
 
     - Improve diagnostics around parsing
-      @1@option@1@--pages@2@option@2@ command-line options
+      :samp:`--pages` command-line options
 
   - Packaging Changes
 
@@ -3747,7 +3747,7 @@ For a detailed list of changes, please see the file
 
     - When generating a file while preserving object streams,
       unreferenced objects are correctly removed unless
-      @1@option@1@--preserve-unreferenced@2@option@2@ is specified.
+      :samp:`--preserve-unreferenced` is specified.
 
   - Library Enhancements
 
@@ -3810,19 +3810,19 @@ For a detailed list of changes, please see the file
 
     - Operations that work on combining pages are much better about
       protecting form fields. In particular,
-      @1@option@1@--split-pages@2@option@2@ and
-      @1@option@1@--pages@2@option@2@ now preserve interaction form
+      :samp:`--split-pages` and
+      :samp:`--pages` now preserve interaction form
       functionality by copying the relevant form field information
       from the original files. Additionally, if you use
-      @1@option@1@--pages@2@option@2@ to select only some pages from
+      :samp:`--pages` to select only some pages from
       the original input file, unused form fields are removed, which
       prevents lots of unused annotations from being retained.
 
     - By default, :command:`qpdf` 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 @1@option@1@--allow-insecure@2@option@2@ option,
-      specified inside the @1@option@1@--encrypt@2@option@2@ options,
+      use. The :samp:`--allow-insecure` option,
+      specified inside the :samp:`--encrypt` 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 creation of
@@ -3864,7 +3864,7 @@ For a detailed list of changes, please see the file
       Files/Attachments Options <#ref.attachments>`__ for details.
 
     - Page splitting and merging operations, as well as
-      @1@option@1@--flatten-rotation@2@option@2@, are better behaved
+      :samp:`--flatten-rotation`, 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
@@ -3877,12 +3877,12 @@ For a detailed list of changes, please see the file
       that is out of spec but that works in most viewers anyway).
 
     - The option
-      @1@option@1@--password-file=@1@replaceable@1@filename@2@replaceable@2@@2@option@2@
+      :samp:`--password-file=@1@replaceable@1@filename@2@replaceable@2@`
       can now be used to read the decryption password from a file.
       You can use ``-`` 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
-      @1@option@1@@file@2@option@2@ for this purpose.
+      :samp:`@file` for this purpose.
 
     - Add some information about attachments to the json output, and
       added ``attachments`` as an additional json key. The
@@ -3893,12 +3893,12 @@ For a detailed list of changes, please see the file
       extraction of attachments. More detailed information can be
       obtained by following the reference to the file spec object.
 
-    - 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@
+    - Add numeric option to :samp:`--collate`. If
+      :samp:`--collate=@1@replaceable@1@n@2@replaceable@2@`
       is given, take pages in groups of
       @1@replaceable@1@n@2@replaceable@2@ from the given files.
 
-    - It is now valid to provide @1@option@1@--rotate=0@2@option@2@
+    - It is now valid to provide :samp:`--rotate=0`
       to clear rotation from a page.
 
   - Library Enhancements
@@ -3976,7 +3976,7 @@ For a detailed list of changes, please see the file
 
   - Bug Fixes
 
-    - The @1@option@1@--flatten-rotation@2@option@2@ option applies
+    - The :samp:`--flatten-rotation` option applies
       transformations to any annotations that may be on the page.
 
     - If a form XObject lacks a resources dictionary, consider any
@@ -3999,7 +3999,7 @@ For a detailed list of changes, please see the file
 10.1.0: January 5, 2021
   - CLI Enhancements
 
-    - Add @1@option@1@--flatten-rotation@2@option@2@ command-line
+    - Add :samp:`--flatten-rotation` 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
@@ -4119,7 +4119,7 @@ For a detailed list of changes, please see the file
   - Bug Fixes
 
     - When concatenating content streams, as with
-      @1@option@1@--coalesce-contents@2@option@2@, there were cases
+      :samp:`--coalesce-contents`, 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.
@@ -4136,23 +4136,23 @@ For a detailed list of changes, please see the file
       already ignored the user's locale for numeric conversion.
 
     - Fix several instances in which warnings were not suppressed in
-      spite of @1@option@1@--no-warn@2@option@2@ and/or errors or
+      spite of :samp:`--no-warn` and/or errors or
       warnings were written to standard output rather than standard
       error.
 
     - Fixed a memory leak that could occur under specific
       circumstances when
-      @1@option@1@--object-streams=generate@2@option@2@ was used.
+      :samp:`--object-streams=generate` was used.
 
     - Fix various integer overflows and similar conditions found by
       the OSS-Fuzz project.
 
   - Enhancements
 
-    - New option @1@option@1@--warning-exit-0@2@option@2@ causes qpdf
+    - New option :samp:`--warning-exit-0` causes qpdf
       to exit with a status of ``0`` rather than ``3`` if there are
       warnings but no errors. Combine with
-      @1@option@1@--no-warn@2@option@2@ to completely ignore
+      :samp:`--no-warn` to completely ignore
       warnings.
 
     - Performance improvements have been made to
@@ -4163,7 +4163,7 @@ For a detailed list of changes, please see the file
 
   - Build Changes
 
-    - The option @1@option@1@--disable-rpath@2@option@2@ is now
+    - The option :samp:`--disable-rpath` is now
       supported by qpdf's :command:`./configure`
       script. Some distributions' packaging standards recommended the
       use of this option.
@@ -4265,7 +4265,7 @@ For a detailed list of changes, please see the file
       :command:`qpdf --json-help` for details.
 
     - Add new option
-      @1@option@1@--remove-unreferenced-resources@2@option@2@ which
+      :samp:`--remove-unreferenced-resources` which
       takes ``auto``, ``yes``, or ``no`` as arguments. The new
       ``auto`` mode, which is the default, performs a fast heuristic
       over a PDF file when splitting pages to determine whether the
@@ -4276,9 +4276,9 @@ For a detailed list of changes, please see the file
       Options <#ref.advanced-transformation>`__ for a more detailed
       discussion.
 
-    - The @1@option@1@--preserve-unreferenced-resources@2@option@2@
+    - The :samp:`--preserve-unreferenced-resources`
       is now just a synonym for
-      @1@option@1@--remove-unreferenced-resources=no@2@option@2@.
+      :samp:`--remove-unreferenced-resources=no`.
 
     - If the ``QPDF_EXECUTABLE`` environment variable is set when
       invoking :command:`qpdf --bash-completion` or
@@ -4370,8 +4370,8 @@ For a detailed list of changes, please see the file
 
   - CLI Enhancements
 
-    - Added options @1@option@1@--is-encrypted@2@option@2@ and
-      @1@option@1@--requires-password@2@option@2@ for testing whether
+    - Added options :samp:`--is-encrypted` and
+      :samp:`--requires-password` 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 on
@@ -4380,7 +4380,7 @@ For a detailed list of changes, please see the file
     - Added ``encrypt`` key to JSON options. With the exception of
       the reconstructed user password for older encryption formats,
       this provides the same information as
-      @1@option@1@--show-encryption@2@option@2@ but in a consistent,
+      :samp:`--show-encryption` but in a consistent,
       parseable format. See output of :command:`qpdf
       --json-help` for details.
 
@@ -4388,7 +4388,7 @@ For a detailed list of changes, please see the file
 
     - In QDF mode, be sure not to write more than one XRef stream to
       a file, even when
-      @1@option@1@--preserve-unreferenced@2@option@2@ is used.
+      :samp:`--preserve-unreferenced` is used.
       :command:`fix-qdf` assumes that there is only
       one XRef stream, and that it appears at the end of the file.
 
@@ -4437,7 +4437,7 @@ For a detailed list of changes, please see the file
 
   - CLI Enhancements
 
-    - Addition of the @1@option@1@--show-crypto@2@option@2@ option in
+    - Addition of the :samp:`--show-crypto` option in
       support of selectable crypto providers, as described in `Crypto
       Providers <#ref.crypto>`__.
 
@@ -4452,7 +4452,7 @@ For a detailed list of changes, please see the file
   - Bug Fix
 
     - Fix the name of the temporary file used by
-      @1@option@1@--replace-input@2@option@2@ so that it doesn't
+      :samp:`--replace-input` so that it doesn't
       require path splitting and works with paths include
       directories.
 
@@ -4505,22 +4505,22 @@ For a detailed list of changes, please see the file
 
   - CLI Enhancements
 
-    - The @1@option@1@--replace-input@2@option@2@ option may be given
+    - The :samp:`--replace-input` 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
-      @1@option@1@--replace-input@2@option@2@ in `Basic
+      :samp:`--replace-input` in `Basic
       Options <#ref.basic-options>`__ for more details.
 
-    - The @1@option@1@--recompress-flate@2@option@2@ instructs
+    - The :samp:`--recompress-flate` instructs
       :command:`qpdf` to recompress streams that are
       already compressed with ``/FlateDecode``. Useful with
-      @1@option@1@--compression-level@2@option@2@.
+      :samp:`--compression-level`.
 
     - The
-      @1@option@1@--compression-level=@1@replaceable@1@level@2@replaceable@2@@2@option@2@
+      :samp:`--compression-level=@1@replaceable@1@level@2@replaceable@2@`
       sets the zlib compression level used for any streams compressed
       by ``/FlateDecode``. Most effective when combined with
-      @1@option@1@--recompress-flate@2@option@2@.
+      :samp:`--recompress-flate`.
 
   - Library Enhancements
 
@@ -4614,8 +4614,8 @@ For a detailed list of changes, please see the file
       a file with linearization warnings but not errors, it now
       properly exits with exit code 3 instead of 2.
 
-    - The @1@option@1@--completion-bash@2@option@2@ and
-      @1@option@1@--completion-zsh@2@option@2@ options now work
+    - The :samp:`--completion-bash` and
+      :samp:`--completion-zsh` options now work
       properly when qpdf is invoked as an AppImage.
 
     - Calling ``QPDFWriter::set*EncryptionParameters`` on a
@@ -4630,7 +4630,7 @@ For a detailed list of changes, please see the file
   - Build Changes
 
     - On platforms that support it, qpdf now builds with
-      @1@option@1@-fvisibility=hidden@2@option@2@. If you build qpdf
+      :samp:`-fvisibility=hidden`. 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 shared
@@ -4679,7 +4679,7 @@ For a detailed list of changes, please see the file
       qpdf than the library, which may indicate a problem with the
       installation.
 
-    - New option @1@option@1@--remove-page-labels@2@option@2@ will
+    - New option :samp:`--remove-page-labels` will
       remove page labels before generating output. This used to
       happen if you ran :command:`qpdf --empty --pages ..
       --`, but the behavior changed in qpdf 8.3.0. This
@@ -4687,7 +4687,7 @@ For a detailed list of changes, please see the file
       get it again.
 
     - New option
-      @1@option@1@--keep-files-open-threshold=@1@replaceable@1@count@2@replaceable@2@@2@option@2@
+      :samp:`--keep-files-open-threshold=@1@replaceable@1@count@2@replaceable@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 fewer than
@@ -4706,7 +4706,7 @@ For a detailed list of changes, please see the file
       during page splitting operations.
 
     - Revert change that included preservation of outlines
-      (bookmarks) in @1@option@1@--split-pages@2@option@2@. The way
+      (bookmarks) in :samp:`--split-pages`. 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 more
@@ -4759,17 +4759,17 @@ For a detailed list of changes, please see the file
         depth in `Unicode Passwords <#ref.unicode-passwords>`__.
 
     - 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
+      :samp:`--externalize-inline-images`,
+      :samp:`--ii-min-bytes`, and
+      :samp:`--keep-inline-images` control qpdf's
       handling of inline images and possible conversion of them to
       regular images. By default,
-      @1@option@1@--optimize-images@2@option@2@ now also applies to
+      :samp:`--optimize-images` now also applies to
       inline images. These options are discussed in `Advanced
       Transformation Options <#ref.advanced-transformation>`__.
 
-    - Add options @1@option@1@--overlay@2@option@2@ and
-      @1@option@1@--underlay@2@option@2@ for overlaying or
+    - Add options :samp:`--overlay` and
+      :samp:`--underlay` for overlaying or
       underlaying pages of other files onto output pages. See
       `Overlay and Underlay Options <#ref.overlay-underlay>`__ for
       details.
@@ -4779,33 +4779,33 @@ For a detailed list of changes, please see the file
       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
-      @1@option@1@--suppress-password-recovery@2@option@2@ option.
+      :samp:`--suppress-password-recovery` option.
       See `Unicode Passwords <#ref.unicode-passwords>`__ for a full
       discussion.
 
-    - Add the @1@option@1@--password-mode@2@option@2@ option to
+    - Add the :samp:`--password-mode` option to
       fine-tune how qpdf interprets password arguments, especially
       when they contain non-ASCII characters. See `Unicode
       Passwords <#ref.unicode-passwords>`__ for more information.
 
-    - In the @1@option@1@--pages@2@option@2@ option, it is now
+    - In the :samp:`--pages` 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.
 
-    - In the @1@option@1@--pages@2@option@2@ option, allow use of "."
+    - In the :samp:`--pages` option, allow use of "."
       as a shortcut for the primary input file. That way, you can do
       :command:`qpdf in.pdf --pages . 1-2 -- out.pdf`
       instead of having to repeat :file:`in.pdf`
       in the command.
 
     - When encrypting with 128-bit and 256-bit encryption, new
-      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
+      encryption options :samp:`--assemble`,
+      :samp:`--annotate`,
+      :samp:`--form`, and
+      :samp:`--modify-other` allow more fine-grained
       granularity in configuring options. Before, the
-      @1@option@1@--modify@2@option@2@ option only configured certain
+      :samp:`--modify` option only configured certain
       predefined groups of permissions.
 
   - Bug Fixes and Enhancements
@@ -4816,7 +4816,7 @@ For a detailed list of changes, please see the file
       file's internal structure shared these 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
-      @1@option@1@--preserve-unreferenced-resources@2@option@2@
+      :samp:`--preserve-unreferenced-resources`
       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
@@ -4831,7 +4831,7 @@ For a detailed list of changes, please see the file
       from files that have duplicate Page objects in the pages tree.
 
     - Using older option
-      @1@option@1@--stream-data=compress@2@option@2@ with object
+      :samp:`--stream-data=compress` with object
       streams, object streams and xref streams were not compressed.
 
     - When the tokenizer returns inline image tokens, delimiters
@@ -4919,7 +4919,7 @@ For a detailed list of changes, please see the file
   - Build Improvements
 
     - Add new configure option
-      @1@option@1@--enable-avoid-windows-handle@2@option@2@, which
+      :samp:`--enable-avoid-windows-handle`, which
       causes the preprocessor symbol ``AVOID_WINDOWS_HANDLE`` to be
       defined. When defined, qpdf will avoid referencing the Windows
       ``HANDLE`` type, which is disallowed with certain versions of
@@ -4944,11 +4944,11 @@ For a detailed list of changes, please see the file
 
     - Page numbers (also known as page labels) are now preserved when
       merging and splitting files with the
-      @1@option@1@--pages@2@option@2@ and
-      @1@option@1@--split-pages@2@option@2@ options.
+      :samp:`--pages` and
+      :samp:`--split-pages` options.
 
     - Bookmarks are partially preserved when splitting pages with the
-      @1@option@1@--split-pages@2@option@2@ option. Specifically, the
+      :samp:`--split-pages` 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
@@ -4958,50 +4958,50 @@ For a detailed list of changes, please see the file
       operations.
 
     - 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
+      :samp:`--collate`. When specified, the
+      semantics of :samp:`--pages` change from
       concatenation to collation. See `Page Selection
       Options <#ref.page-selection>`__ for examples and discussion.
 
     - Generation of information in JSON format, primarily to
       facilitate use of qpdf from languages other than C++. Add 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
+      options :samp:`--json`,
+      :samp:`--json-key`, and
+      :samp:`--json-object` to generate a JSON
       representation of the PDF file. Run :command:`qpdf
       --json-help` to get a description of the JSON
       format. For more information, see `QPDF JSON <#ref.json>`__.
 
-    - The @1@option@1@--generate-appearances@2@option@2@ flag will
+    - The :samp:`--generate-appearances` 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
       doesn't know how to regenerate the appearances of the filled-in
       fields.
 
-    - The @1@option@1@--flatten-annotations@2@option@2@ flag can be
+    - The :samp:`--flatten-annotations` flag can be
       used to *flatten* 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
-      @1@option@1@--generate-appearances@2@option@2@ when using this
+      :samp:`--generate-appearances` when using this
       flag since annotations for outdated form fields are not
       flattened as that would cause loss of information.
 
-    - The @1@option@1@--optimize-images@2@option@2@ flag tells qpdf
+    - The :samp:`--optimize-images` 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 @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
+      additional options :samp:`--oi-min-width`,
+      :samp:`--oi-min-height`, and
+      :samp:`--oi-min-area` prevent recompression of
       images whose width, height, or pixel area (width × height) are
       below a specified threshold.
 
-    - 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 :samp:`--show-object` option can now be
+      given as :samp:`--show-object=trailer` to show
       the trailer dictionary.
 
   - Bug Fixes and Enhancements
@@ -5024,7 +5024,7 @@ For a detailed list of changes, please see the file
       Instead, it issues a normal warning or error.
 
     - Ordinarily qpdf treats an argument of the form
-      @1@option@1@@file@2@option@2@ to mean that command-line options
+      :samp:`@file` to mean that command-line options
       should be read from :file:`file`. Now, if
       :file:`file` does not exist but
       :file:`@file` does, qpdf will treat
@@ -5135,7 +5135,7 @@ For a detailed list of changes, please see the file
       your packaging system automatically refreshes libtool or
       autoconf files, it could cause this check to fail. To avoid
       this problem, pass
-      @1@option@1@--disable-check-autofiles@2@option@2@ to
+      :samp:`--disable-check-autofiles` to
       :command:`configure`.
 
     - If you would like to have qpdf completion enabled
@@ -5148,16 +5148,16 @@ For a detailed list of changes, please see the file
   - Command-line Enhancements
 
     - Add
-      @1@option@1@--keep-files-open=@1@replaceable@1@[yn]@2@replaceable@2@@2@option@2@
+      :samp:`--keep-files-open=@1@replaceable@1@[yn]@2@replaceable@2@`
       to override default determination of whether to keep files open
       when merging. Please see the discussion of
-      @1@option@1@--keep-files-open@2@option@2@ in `Basic
+      :samp:`--keep-files-open` in `Basic
       Options <#ref.basic-options>`__ for additional details.
 
 8.2.0: August 16, 2018
   - Command-line Enhancements
 
-    - Add @1@option@1@--no-warn@2@option@2@ option to suppress
+    - Add :samp:`--no-warn` 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.
@@ -5177,7 +5177,7 @@ For a detailed list of changes, please see the file
     - Bug fix: end of line characters were not properly handled
       inside strings in some cases.
 
-    - Bug fix: using @1@option@1@--progress@2@option@2@ on very small
+    - Bug fix: using :samp:`--progress` on very small
       files could cause an infinite loop.
 
   - API enhancements
@@ -5217,7 +5217,7 @@ For a detailed list of changes, please see the file
       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
-      @1@option@1@--preserve-unreferenced-resources@2@option@2@. For
+      :samp:`--preserve-unreferenced-resources`. For
       additional details, please see `Advanced Transformation
       Options <#ref.advanced-transformation>`__.
 
@@ -5226,19 +5226,19 @@ For a detailed list of changes, please see the file
       that may exceed the operating system's limit for the maximum
       number of open files.
 
-    - The @1@option@1@--rotate@2@option@2@ option's syntax has been
+    - The :samp:`--rotate` option's syntax has been
       extended to make the page range optional. If you specify
-      @1@option@1@--rotate=@1@replaceable@1@angle@2@replaceable@2@@2@option@2@
+      :samp:`--rotate=@1@replaceable@1@angle@2@replaceable@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 was scanned upside
       down.
 
     - When merging multiple files, the
-      @1@option@1@--verbose@2@option@2@ option now prints information
+      :samp:`--verbose` option now prints information
       about each file as it operates on that file.
 
-    - When the @1@option@1@--progress@2@option@2@ option is
+    - When the :samp:`--progress` 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
@@ -5294,7 +5294,7 @@ For a detailed list of changes, please see the file
       it thinks it is through writing its output. Client programs can
       use this to implement reasonably accurate progress meters. The
       :command:`qpdf` command line tool uses this to
-      implement its @1@option@1@--progress@2@option@2@ option.
+      implement its :samp:`--progress` option.
 
     - New methods ``QPDFObjectHandle::newUnicodeString`` and
       ``QPDFObject::unparseBinary`` have been added to allow for more
@@ -5352,10 +5352,10 @@ For a detailed list of changes, please see the file
     `Running QPDF <#ref.using>`__.
 
     - The option
-      @1@option@1@--linearize-pass1=@1@replaceable@1@file@2@replaceable@2@@2@option@2@
+      :samp:`--linearize-pass1=@1@replaceable@1@file@2@replaceable@2@`
       has been added for debugging qpdf's linearization code.
 
-    - The option @1@option@1@--coalesce-contents@2@option@2@ can be
+    - The option :samp:`--coalesce-contents` can be
       used to combine content streams of a page whose contents are an
       array of streams into a single stream.
 
@@ -5404,7 +5404,7 @@ For a detailed list of changes, please see the file
     password when opening encrypted files, and will 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 @1@option@1@--password-is-hex-key@2@option@2@ in
+    the discussion of :samp:`--password-is-hex-key` in
     `Basic Options <#ref.basic-options>`__ or the comments around
     ``QPDF::setPasswordIsHexKey`` in
     :file:`QPDF.hh` for additional details.
@@ -5442,8 +5442,8 @@ For a detailed list of changes, please see the file
       or RunLength encoding. Library API enhancements and
       command-line options have been added to control this behavior.
       See command-line options
-      @1@option@1@--compress-streams@2@option@2@ and
-      @1@option@1@--decode-level@2@option@2@ and methods
+      :samp:`--compress-streams` and
+      :samp:`--decode-level` and methods
       ``QPDFWriter::setCompressStreams`` and
       ``QPDFWriter::setDecodeLevel``.
 
@@ -5469,27 +5469,27 @@ For a detailed list of changes, please see the file
       input using ``@file`` or ``@-`` syntax. Please see `Basic
       Invocation <#ref.invocation>`__.
 
-    - @1@option@1@--rotate@2@option@2@: request page rotation
+    - :samp:`--rotate`: request page rotation
 
-    - @1@option@1@--newline-before-endstream@2@option@2@: ensure that
+    - :samp:`--newline-before-endstream`: ensure that
       a newline appears before every ``endstream`` keyword in the
       file; used to prevent qpdf from breaking PDF/A compliance on
       already compliant files.
 
-    - @1@option@1@--preserve-unreferenced@2@option@2@: preserve
+    - :samp:`--preserve-unreferenced`: preserve
       unreferenced objects in the input PDF
 
-    - @1@option@1@--split-pages@2@option@2@: break output into chunks
+    - :samp:`--split-pages`: break output into chunks
       with fixed numbers of pages
 
-    - @1@option@1@--verbose@2@option@2@: print the name of each
+    - :samp:`--verbose`: print the name of each
       output file that is created
 
-    - @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
+    - :samp:`--compress-streams` and
+      :samp:`--decode-level` replace
+      :samp:`--stream-data` for improving granularity
       of controlling compression and decompression of stream data.
-      The @1@option@1@--stream-data@2@option@2@ option will remain
+      The :samp:`--stream-data` option will remain
       available.
 
     - When running :command:`qpdf --check` with other
@@ -5500,8 +5500,8 @@ For a detailed list of changes, please see the file
       reference table, or other similar operations.
 
     - Process :command:`--pages` 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
+      options like :samp:`--show-pages` or
+      :samp:`--split-pages` can operate on the file
       after page splitting/merging has occurred.
 
   - API Changes. All new API calls are documented in their respective
@@ -5534,7 +5534,7 @@ For a detailed list of changes, please see the file
       ``QPDFWriter`` methods.
 
 6.0.0: November 10, 2015
-  - Implement @1@option@1@--deterministic-id@2@option@2@ command-line
+  - Implement :samp:`--deterministic-id` command-line
     option and ``QPDFWriter::setDeterministicID`` as well as C API
     function ``qpdf_set_deterministic_ID`` for generating a
     deterministic ID for non-encrypted files. When this option is
@@ -5618,11 +5618,11 @@ For a detailed list of changes, please see the file
     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
-    @1@option@1@--enable-insecure-random@2@option@2@ option to
+    :samp:`--enable-insecure-random` option to
     :command:`./configure`.
 
   - The :command:`qpdf` command-line tool now issues a
-    warning when @1@option@1@-accessibility=n@2@option@2@ is specified
+    warning when :samp:`-accessibility=n` 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 only by the
@@ -5647,12 +5647,12 @@ For a detailed list of changes, please see the file
     :file:`QPDFObjectHandle.hh` for additional
     notes.
 
-  - Add @1@option@1@--show-npages@2@option@2@ command-line option to
+  - Add :samp:`--show-npages` command-line option to
     the :command:`qpdf` command to show the number of
     pages in a file.
 
   - Allow omission of the page range within
-    @1@option@1@--pages@2@option@2@ for the
+    :samp:`--pages` for the
     :command:`qpdf` command. When omitted, the page
     range is implicitly taken to be all the pages in the file.
 
@@ -5701,7 +5701,7 @@ For a detailed list of changes, please see the file
     - Warning flags have been moved into a separate variable in
       :file:`autoconf.mk`
 
-    - The configure flag @1@option@1@--enable-werror@2@option@2@ work
+    - The configure flag :samp:`--enable-werror` work
       for Microsoft compilers
 
     - All MSVC CRT security warnings have been resolved.
@@ -5837,12 +5837,12 @@ For a detailed list of changes, please see the file
       ``QPDFWriter``.
 
     - Removed the method ``decodeStreams``. This method was used by
-      the @1@option@1@--check@2@option@2@ option of the
+      the :samp:`--check` option of the
       :command:`qpdf` 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
-      @1@option@1@--check@2@option@2@ option now causes qpdf to go
+      :samp:`--check` 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.
@@ -5951,7 +5951,7 @@ For a detailed list of changes, please see the file
   - 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
-    @1@option@1@--disable-ld-version-script@2@option@2@ to
+    :samp:`--disable-ld-version-script` to
     :command:`./configure`.
 
   - The file :file:`libqpdf.pc` is now installed
@@ -5972,7 +5972,7 @@ For a detailed list of changes, please see the file
     terminal anymore by default. Instead, find them in
     :file:`build/qtest.log`. For packagers who are
     building with an autobuilder, you can add the
-    @1@option@1@--enable-show-failed-test-output@2@option@2@ option to
+    :samp:`--enable-show-failed-test-output` option to
     :command:`./configure` to restore the old behavior.
 
 2.3.1: December 28, 2011
@@ -6180,7 +6180,7 @@ For a detailed list of changes, please see the file
     permissions, it does make them available so that applications that
     use qpdf can enforce permissions.
 
-  - The @1@option@1@--check@2@option@2@ option to
+  - The :samp:`--check` option to
     :command:`qpdf` has been extended to include some
     additional information.
 
-- 
cgit v1.2.3-54-g00ecf