Remove ref. from documentation references

Jay Berkenbilt
1 parent 426b4ce8
Showing 12 changed files with 118 additions and 118 deletions
manual/cli.rst
manual/design.rst
manual/installation.rst
manual/json.rst
manual/library.rst
manual/license.rst
manual/linearization.rst
manual/object-streams.rst
manual/overview.rst
manual/qdf.rst
manual/release-notes.rst
manual/weak-crypto.rst
-.. _ref.using:
+.. _using:
  
 Running QPDF
 ============
@@ -6,7 +6,7 @@ Running QPDF
 This chapter describes how to run the qpdf program from the command
 line.
  
-.. _ref.invocation:
+.. _invocation:
  
 Basic Invocation
 ----------------
@@ -26,7 +26,7 @@ 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 :samp:`--empty` would be if you were
-going to add pages from another source, as discussed in :ref:`ref.page-selection`.
+going to add pages from another source, as discussed in :ref:`page-selection`.
  
 If :samp:`@filename` appears as a word anywhere in the
 command-line, it will be read line by line, and each line will be
@@ -53,7 +53,7 @@ If you do this, qpdf will tell you about the
 Most options require an output file, but some testing or inspection
 commands do not. These are specifically noted.
  
-.. _ref.exit-status:
+.. _exit-status:
  
 Exit Status
 ~~~~~~~~~~~
@@ -80,7 +80,7 @@ Note that :command:`qpdf` never exists with status ``1``.
 If you get an exit status of ``1``, it was something else, like the
 shell not being able to find or execute :command:`qpdf`.
  
-.. _ref.shell-completion:
+.. _shell-completion:
  
 Shell Completion
 ----------------
@@ -100,7 +100,7 @@ to use completion with copy of qpdf that is built from source. You can
 specify a full path to the qpdf you want to use for completion in the
 ``QPDF_EXECUTABLE`` environment variable.
  
-.. _ref.basic-options:
+.. _basic-options:
  
 Basic Options
 -------------
@@ -119,7 +119,7 @@ needed transformations.
  
 :samp:`--show-crypto`
    Show a list of available crypto providers, each on a line by itself.
-   The default provider is always listed first. See :ref:`ref.crypto` for more information about crypto
+   The default provider is always listed first. See :ref:`crypto` for more information about crypto
    providers.
  
 :samp:`--completion-bash`
@@ -225,10 +225,10 @@ needed transformations.
    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 :ref:`ref.weak-crypto` for additional details.
+   files with weak cryptography when this flag is not given. See :ref:`weak-crypto` for additional details.
  
 :samp:`--encrypt options --`
-   Causes generation an encrypted output file. Please see :ref:`ref.encryption-options` for details on how to specify
+   Causes generation an encrypted output file. Please see :ref:`encryption-options` for details on how to specify
    encryption parameters.
  
 :samp:`--decrypt`
@@ -260,7 +260,7 @@ needed transformations.
    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 :ref:`ref.unicode-passwords` for a
+   this option. See :ref:`unicode-passwords` for a
    discussion
  
 :samp:`--password-mode={mode}`
@@ -271,7 +271,7 @@ needed transformations.
    :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
-   :ref:`ref.unicode-passwords`. The following modes
+   :ref:`unicode-passwords`. The following modes
    are supported:
  
    - :samp:`auto`: Automatically determine whether the
@@ -311,7 +311,7 @@ needed transformations.
 :samp:`--rotate=[+|-]angle[:page-range]`
    Apply rotation to specified pages. The
    :samp:`page-range` portion of the option value has
-   the same format as page ranges in :ref:`ref.page-selection`. If the page range is omitted, the
+   the same format as page ranges in :ref:`page-selection`. If the page range is omitted, the
    rotation is applied to all pages. The :samp:`angle`
    portion of the parameter may be either 0, 90, 180, or 270. If
    preceded by :samp:`+` or :samp:`-`,
@@ -358,14 +358,14 @@ needed transformations.
    :samp:`--keep-files-open` for details.
  
 :samp:`--pages options --`
-   Select specific pages from one or more input files. See :ref:`ref.page-selection` for details on how to do
+   Select specific pages from one or more input files. See :ref:`page-selection` for details on how to do
    page selection (splitting and merging).
  
 :samp:`--collate={n}`
    When specified, collate rather than concatenate pages from files
    specified with :samp:`--pages`. With a numeric
    argument, collate in groups of :samp:`{n}`.
-   The default is 1. See :ref:`ref.page-selection` for additional details.
+   The default is 1. See :ref:`page-selection` for additional details.
  
 :samp:`--flatten-rotation`
    For each page that is rotated using the ``/Rotate`` key in the page's
@@ -418,11 +418,11 @@ needed transformations.
    require the global data.
  
 :samp:`--overlay options --`
-   Overlay pages from another file onto the output pages. See :ref:`ref.overlay-underlay` for details on
+   Overlay pages from another file onto the output pages. See :ref:`overlay-underlay` for details on
    overlay/underlay.
  
 :samp:`--underlay options --`
-   Overlay pages from another file onto the output pages. See :ref:`ref.overlay-underlay` for details on
+   Overlay pages from another file onto the output pages. See :ref:`overlay-underlay` for details on
    overlay/underlay.
  
 Password-protected files may be opened by specifying a password. By
@@ -442,13 +442,13 @@ Prior to 8.4.0, in the case of passwords that contain characters that
 fall outside of 7-bit US-ASCII, qpdf left the burden of supplying
 properly encoded encryption and decryption passwords to the user.
 Starting in qpdf 8.4.0, qpdf does this automatically in most cases. For
-an in-depth discussion, please see :ref:`ref.unicode-passwords`. Previous versions of this manual
+an in-depth discussion, please see :ref:`unicode-passwords`. Previous versions of this manual
 described workarounds using the :command:`iconv` command.
 Such workarounds are no longer required or recommended with qpdf 8.4.0.
 However, for backward compatibility, qpdf attempts to detect those
 workarounds and do the right thing in most cases.
  
-.. _ref.encryption-options:
+.. _encryption-options:
  
 Encryption Options
 ------------------
@@ -610,7 +610,7 @@ with the following exceptions:
  
 The default for each permission option is to be fully permissive.
  
-.. _ref.page-selection:
+.. _page-selection:
  
 Page Selection Options
 ----------------------
@@ -814,7 +814,7 @@ would create a file with two copies of the first page of the input, and
 the two copies would share any objects in common. This includes fonts,
 images, and anything else the page references.
  
-.. _ref.overlay-underlay:
+.. _overlay-underlay:
  
 Overlay and Underlay Options
 ----------------------------
@@ -849,7 +849,7 @@ between the :samp:`--overlay` or
   overlay/underlay file is encrypted.
  
 - :samp:`--to=page-range`: a range of pages in the same
-  form at described in :ref:`ref.page-selection`
+  form at described in :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.
  
@@ -880,7 +880,7 @@ Here are some examples.
   underlay page 2 of :file:`footer.pdf` on all even
   output pages.
  
-.. _ref.attachments:
+.. _attachments:
  
 Embedded Files/Attachments Options
 ----------------------------------
@@ -975,7 +975,7 @@ timezone offset in the form :samp:`{-hh&#39;mm&#39;}` or
 :samp:`{+hh'mm'}`. Examples:
 ``D:20210207161528-05'00'``, ``D:20210207211528Z``.
  
-.. _ref.advanced-parsing:
+.. _advanced-parsing:
  
 Advanced Parsing Options
 ------------------------
@@ -1011,7 +1011,7 @@ this feature is if you are testing creation of hybrid PDF files and wish
 to see how a PDF consumer that doesn't understand object and
 cross-reference streams would interpret such a file.
  
-.. _ref.advanced-transformation:
+.. _advanced-transformation:
  
 Advanced Transformation Options
 -------------------------------
@@ -1097,7 +1097,7 @@ following options are available:
  
 :samp:`--normalize-content=[yn]`
    Enables or disables normalization of content streams. Content
-   normalization is enabled by default in QDF mode. Please see :ref:`ref.qdf` for additional discussion of QDF mode.
+   normalization is enabled by default in QDF mode. Please see :ref:`qdf` for additional discussion of QDF mode.
  
 :samp:`--object-streams={mode}`
    Controls handling of object streams. The value of
@@ -1304,7 +1304,7 @@ following options are available:
    Remove page labels from the output file.
  
 :samp:`--qdf`
-   Turns on QDF mode. For additional information on QDF, please see :ref:`ref.qdf`. Note that :samp:`--linearize`
+   Turns on QDF mode. For additional information on QDF, please see :ref:`qdf`. Note that :samp:`--linearize`
    disables QDF mode.
  
 :samp:`--min-version={version}`
@@ -1413,9 +1413,9 @@ documents are interspersed with comments that make it easier for the
 user to find things and also make it possible for
 :command:`fix-qdf` to work properly. QDF mode is intended
 for people, mostly developers, who wish to inspect or modify PDF files
-in a text editor. For details, please see :ref:`ref.qdf`.
+in a text editor. For details, please see :ref:`qdf`.
  
-.. _ref.testing-options:
+.. _testing-options:
  
 Testing, Inspection, and Debugging Options
 ------------------------------------------
@@ -1519,7 +1519,7 @@ given. The following options are available:
  
 :samp:`--json`
    Generate a JSON representation of the file. This is described in
-   depth in :ref:`ref.json`
+   depth in :ref:`json`
  
 :samp:`--json-help`
    Describe the format of the JSON output.
@@ -1571,7 +1571,7 @@ 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.
  
-.. _ref.unicode-passwords:
+.. _unicode-passwords:
  
 Unicode Passwords
 -----------------
-.. _ref.design:
+.. _design:
  
 Design and Library Notes
 ========================
  
-.. _ref.design.intro:
+.. _design.intro:
  
 Introduction
 ------------
@@ -33,7 +33,7 @@ This is by design as there seems to be a shortage of PDF validation
 tools out there. This was, in fact, one of the major motivations behind
 the initial creation of qpdf.
  
-.. _ref.design-goals:
+.. _design-goals:
  
 Design Goals
 ------------
@@ -118,9 +118,9 @@ full details, please see the header files
 :file:`QPDF.hh` and
 :file:`QPDFObjectHandle.hh`. There are also some
 additional helper classes that provide higher level API functions for
-certain document constructions. These are discussed in :ref:`ref.helper-classes`.
+certain document constructions. These are discussed in :ref:`helper-classes`.
  
-.. _ref.helper-classes:
+.. _helper-classes:
  
 Helper Classes
 --------------
@@ -219,7 +219,7 @@ remain in those classes even as alternatives are provided in helper
 classes. Going forward, new higher level interfaces will be provided
 using helper classes.
  
-.. _ref.implementation-notes:
+.. _implementation-notes:
  
 Implementation Notes
 --------------------
@@ -321,7 +321,7 @@ file.
   As the client continues to request objects, the same process is
   followed for each new requested object.
  
-.. _ref.casting:
+.. _casting:
  
 Casting Policy
 --------------
@@ -395,7 +395,7 @@ prevent this from being done. There are places in the code where
 adequate testing to assert that it is safe and will remain safe in
 qpdf's code.
  
-.. _ref.encryption:
+.. _encryption:
  
 Encryption
 ----------
@@ -467,7 +467,7 @@ created, even if the results are not useful to some readers. One use
 case for this would be for testing a PDF reader to ensure that it
 handles odd configurations of input files.
  
-.. _ref.random-numbers:
+.. _random-numbers:
  
 Random Number Generation
 ------------------------
@@ -484,7 +484,7 @@ details on how to do this, please refer to the top-level README.md file
 in the source distribution and to comments in
 :file:`QUtil.hh`.
  
-.. _ref.adding-and-remove-pages:
+.. _adding-and-remove-pages:
  
 Adding and Removing Pages
 -------------------------
@@ -497,7 +497,7 @@ individual pages and manipulation of the ``/Pages`` tree itself. For
 details, see ``addPage`` and surrounding methods in
 :file:`QPDF.hh`.
  
-.. _ref.reserved-objects:
+.. _reserved-objects:
  
 Reserving Object Numbers
 ------------------------
@@ -520,11 +520,11 @@ construct the references. When finished, you can call
 ``QPDF::replaceReserved`` to replace the reserved objects with the real
 ones. This functionality will never be needed by most applications, but
 it is used internally by QPDF when copying objects from other PDF files,
-as discussed in :ref:`ref.foreign-objects`. For an example of how to use reserved
+as discussed in :ref:`foreign-objects`. For an example of how to use reserved
 objects, search for ``newReserved`` in
 :file:`test_driver.cc` in qpdf's sources.
  
-.. _ref.foreign-objects:
+.. _foreign-objects:
  
 Copying Objects From Other PDF Files
 ------------------------------------
@@ -560,7 +560,7 @@ source ``QPDF`` object must remain valid until you have finished with
 the destination object. This is because the original object is still
 used to retrieve any referenced stream data from the copied object.
  
-.. _ref.rewriting:
+.. _rewriting:
  
 Writing PDF Files
 -----------------
@@ -568,9 +568,9 @@ Writing PDF Files
 The qpdf library supports file writing of ``QPDF`` objects to PDF files
 through the ``QPDFWriter`` class. The ``QPDFWriter`` class has two
 writing modes: one for non-linearized files, and one for linearized
-files. See :ref:`ref.linearization` for a description of
+files. See :ref:`linearization` for a description of
 linearization is implemented. This section describes how we write
-non-linearized files including the creation of QDF files (see :ref:`ref.qdf`.
+non-linearized files including the creation of QDF files (see :ref:`qdf`.
  
 This outline was written prior to implementation and is not exactly
 accurate, but it provides a correct "notional" idea of how writing
@@ -645,7 +645,7 @@ can be used to write out a new xref table. Finally we can write out the
 trailer dictionary with appropriately computed /ID (see spec, 8.3, File
 Identifiers), the cross reference table offset, and ``%%EOF``.
  
-.. _ref.filtered-streams:
+.. _filtered-streams:
  
 Filtered Streams
 ----------------
@@ -670,7 +670,7 @@ should write to whatever type of output is required. The ``QPDF`` class
 has an interface to write raw or filtered stream contents to a given
 pipeline.
  
-.. _ref.object-accessors:
+.. _object-accessors:
  
 Object Accessor Methods
 -----------------------
-.. _ref.installing:
+.. _installing:
  
 Building and Installing QPDF
 ============================
@@ -7,7 +7,7 @@ This chapter describes how to build and install qpdf. Please see also
 the :file:`README.md` and
 :file:`INSTALL` files in the source distribution.
  
-.. _ref.prerequisites:
+.. _prerequisites:
  
 System Requirements
 -------------------
@@ -68,7 +68,7 @@ documentation, you need ``pdflatex``, ``latexmk``, and a fairly complete
 LaTeX installation. Detailed requirements can be found in the Sphinx
 documentation.
  
-.. _ref.building:
+.. _building:
  
 Build Instructions
 ------------------
@@ -112,7 +112,7 @@ hand-crafted non-recursive Makefile that requires gnu make. If you&#39;re
 really interested, please read the comments in the top-level
 :file:`Makefile`.
  
-.. _ref.crypto:
+.. _crypto:
  
 Crypto Providers
 ----------------
@@ -131,7 +131,7 @@ Additional implementations may be added if needed. It is also possible
 for a developer to provide their own implementation without modifying
 the qpdf library.
  
-.. _ref.crypto.build:
+.. _crypto.build:
  
 Build Support For Crypto Providers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -192,7 +192,7 @@ build, and you can ignore
 :file:`libqpdf/build.mk` to get the list of source
 files you need to build.
  
-.. _ref.crypto.runtime:
+.. _crypto.runtime:
  
 Runtime Crypto Provider Selection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -211,7 +211,7 @@ to compare behavior of two different crypto providers while testing
 performance or reproducing a bug. It could also be useful for people who
 are implementing their own crypto providers.
  
-.. _ref.crypto.develop:
+.. _crypto.develop:
  
 Crypto Provider Information for Developers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -224,7 +224,7 @@ provider, you have to create a class derived from ``QPDFCryptoImpl`` and
 register it with ``QPDFCryptoProvider``. For additional information, see
 comments in :file:`include/qpdf/QPDFCryptoImpl.hh`.
  
-.. _ref.crypto.design:
+.. _crypto.design:
  
 Crypto Provider Design Notes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -298,7 +298,7 @@ Implementing the registration functions and internal storage of
 registered providers was also easier using C++-11's functional
 interfaces, which was another reason to require C++-11 at this time.
  
-.. _ref.packaging:
+.. _packaging:
  
 Notes for Packagers
 -------------------
@@ -311,7 +311,7 @@ some things you may want to keep in mind:
   However, qpdf still has a build-time dependency on perl.
  
 - Make sure you are getting the intended behavior with regard to crypto
-  providers. Read :ref:`ref.crypto.build` for details.
+  providers. Read :ref:`crypto.build` for details.
  
 - Passing :samp:`--enable-show-failed-test-output` to
   :command:`./configure` will cause any failed test
-.. _ref.json:
+.. _json:
  
 QPDF JSON
 =========
  
-.. _ref.json-overview:
+.. _json-overview:
  
 Overview
 --------
@@ -18,7 +18,7 @@ files programmatically from the command-line in languages that can&#39;t
 call or link with the qpdf library directly. Note that stream data can
 be extracted from PDF files using other qpdf command-line options.
  
-.. _ref.json-guarantees:
+.. _json-guarantees:
  
 JSON Guarantees
 ---------------
-.. _ref.using-library:
+.. _using-library:
  
 Using the QPDF Library
 ======================
  
-.. _ref.using.from-cxx:
+.. _using.from-cxx:
  
 Using QPDF from C++
 -------------------
@@ -34,7 +34,7 @@ individual ``QPDF`` object instance (including ``QPDF``,
 thread at a time. Multiple threads may simultaneously work with
 different instances of these and all other QPDF objects.
  
-.. _ref.using.other-languages:
+.. _using.other-languages:
  
 Using QPDF from other languages
 -------------------------------
@@ -65,9 +65,9 @@ Other Languages
    command-line tool can produce a JSON representation of the PDF file's
    non-content data. This can facilitate interacting programmatically
    with PDF files through qpdf's command line interface. For more
-   information, please see :ref:`ref.json`.
+   information, please see :ref:`json`.
  
-.. _ref.unicode-files:
+.. _unicode-files:
  
 A Note About Unicode File Names
 -------------------------------
-.. _ref.license:
+.. _license:
  
 License
 =======
-.. _ref.linearization:
+.. _linearization:
  
 Linearization
 =============
@@ -6,7 +6,7 @@ Linearization
 This chapter describes how ``QPDF`` and ``QPDFWriter`` implement
 creation and processing of linearized PDFS.
  
-.. _ref.linearization-strategy:
+.. _linearization-strategy:
  
 Basic Strategy for Linearization
 --------------------------------
@@ -22,7 +22,7 @@ was first tested against linearized files created by external tools
 (Acrobat and pdlin) and then used to validate files created by
 ``QPDFWriter`` itself.
  
-.. _ref.linearized.preparation:
+.. _linearized.preparation:
  
 Preparing For Linearization
 ---------------------------
@@ -34,7 +34,7 @@ tree). We also have to know which objects refer to which other objects,
 being concerned with page boundaries and a few other cases. We refer to
 this part of preparing the PDF file as
 *optimization*, discussed in
-:ref:`ref.optimization`. Note the, in this context, the
+:ref:`optimization`. Note the, in this context, the
 term *optimization* is a qpdf term, and the
 term *linearization* is a term from the PDF
 specification. Do not be confused by the fact that many applications
@@ -49,7 +49,7 @@ really only a few issues that need to be dealt with:
  
 - Filling in offsets and byte sizes
  
-.. _ref.optimization:
+.. _optimization:
  
 Optimization
 ------------
@@ -85,7 +85,7 @@ Note that pages and thumbnails have different object user types, so the
 above test on a page will not include objects referenced by the page's
 thumbnail dictionary and nothing else.
  
-.. _ref.linearization.writing:
+.. _linearization.writing:
  
 Writing Linearized Files
 ------------------------
@@ -131,7 +131,7 @@ Using this strategy, we can write linearized files to a non-seekable
 output stream with only a single pass to disk or wherever the output is
 going.
  
-.. _ref.linearization-data:
+.. _linearization-data:
  
 Calculating Linearization Data
 ------------------------------
@@ -147,7 +147,7 @@ object is encountered that has not already been queued. (This could
 happen only if there were a bug in the traversal code used to calculate
 the linearization data.)
  
-.. _ref.linearization-issues:
+.. _linearization-issues:
  
 Known Issues with Linearization
 -------------------------------
@@ -172,7 +172,7 @@ linearization appendix of the PDF specification.
   most of the information needed to create thumbnail hint tables. There
   are comments in the code about this.
  
-.. _ref.linearization-debugging:
+.. _linearization-debugging:
  
 Debugging Note
 --------------
-.. _ref.object-and-xref-streams:
+.. _object-and-xref-streams:
  
 Object and Cross-Reference Streams
 ==================================
@@ -6,7 +6,7 @@ Object and Cross-Reference Streams
 This chapter provides information about the implementation of object
 stream and cross-reference stream support in qpdf.
  
-.. _ref.object-streams:
+.. _object-streams:
  
 Object Streams
 --------------
@@ -27,7 +27,7 @@ if the file is encrypted, though this is not specifically disallowed by
 the specification.
  
 There are additional restrictions for linearized files. See
-:ref:`ref.object-streams-linearization` for details.
+:ref:`object-streams-linearization` for details.
  
 The PDF specification refers to objects in object streams as "compressed
 objects" regardless of whether the object stream is compressed.
@@ -62,7 +62,7 @@ is the object number and the byte offset of the object relative to the
 first object in the stream, followed by the objects themselves,
 concatenated.
  
-.. _ref.xref-streams:
+.. _xref-streams:
  
 Cross-Reference Streams
 -----------------------
@@ -111,7 +111,7 @@ which are these:
 The other fields in the xref stream, which may be indirect if desired,
 are the union of those from the xref table's trailer dictionary.
  
-.. _ref.xref-stream-data:
+.. _xref-stream-data:
  
 Cross-Reference Stream Data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -138,7 +138,7 @@ PDF 1.5 has three field types:
 It seems standard to have the first entry in the table be ``0 0 0``
 instead of ``0 0 ffff`` if there are no deleted objects.
  
-.. _ref.object-streams-linearization:
+.. _object-streams-linearization:
  
 Implications for Linearized Files
 ---------------------------------
@@ -161,7 +161,7 @@ When numbering objects, all shared objects within both the first and
 second halves of the linearized files must be numbered consecutively
 after all normal uncompressed objects in that half.
  
-.. _ref.object-stream-implementation:
+.. _object-stream-implementation:
  
 Implementation Notes
 --------------------
-.. _ref.overview:
+.. _overview:
  
 What is QPDF?
 =============
-.. _ref.qdf:
+.. _qdf:
  
 QDF Mode
 ========
-.. _ref.release-notes:
+.. _release-notes:
  
 Release Notes
 =============
@@ -34,7 +34,7 @@ For a detailed list of changes, please see the file
       error code of ``qpdf_e_object`` instead of
       ``qpdf_e_damaged_pdf``. Also, comments have been added to
       :file:`QPDFObjectHandle.hh` to explain in more detail what the
-      behavior is. See :ref:`ref.object-accessors` for a more in-depth
+      behavior is. See :ref:`object-accessors` for a more in-depth
       discussion.
  
     - Add ``Pl_Buffer::getMallocBuffer()`` to initialize a buffer
@@ -88,7 +88,7 @@ For a detailed list of changes, please see the file
       acknowledgment moving forward. For qpdf 10.4, this change only
       affects the command-line tool. Starting in qpdf 11, there will
       be small API changes to require explicit acknowledgment in
-      those cases as well. For additional information, see :ref:`ref.weak-crypto`.
+      those cases as well. For additional information, see :ref:`weak-crypto`.
  
   - Bug Fixes
  
@@ -243,7 +243,7 @@ For a detailed list of changes, please see the file
   - CLI Enhancements
  
     - Add new command line options for listing, saving, adding,
-      removing, and and copying file attachments. See :ref:`ref.attachments` for details.
+      removing, and and copying file attachments. See :ref:`attachments` for details.
  
     - Page splitting and merging operations, as well as
       :samp:`--flatten-rotation`, are better behaved
@@ -654,7 +654,7 @@ For a detailed list of changes, please see the file
       expensive process of finding and removing unreferenced
       resources is likely to be of benefit. For most files, this new
       default will result in a significant performance improvement
-      for splitting pages. See :ref:`ref.advanced-transformation` for a more detailed
+      for splitting pages. See :ref:`advanced-transformation` for a more detailed
       discussion.
  
     - The :samp:`--preserve-unreferenced-resources`
@@ -786,8 +786,8 @@ For a detailed list of changes, please see the file
     - A C++-11 compiler is now required to build qpdf.
  
     - A new crypto provider that uses gnutls for crypto functions is
-      now available and can be enabled at build time. See :ref:`ref.crypto` for more information about crypto
-      providers and :ref:`ref.crypto.build` for specific information about
+      now available and can be enabled at build time. See :ref:`crypto` for more information about crypto
+      providers and :ref:`crypto.build` for specific information about
       the build.
  
   - Library Enhancements
@@ -811,12 +811,12 @@ For a detailed list of changes, please see the file
       This includes the addition of new classes
       ``QPDFCryptoProvider`` and ``QPDFCryptoImpl`` and the
       recognition of the ``QPDF_CRYPTO_PROVIDER`` environment
-      variable. Crypto providers are described in depth in :ref:`ref.crypto`.
+      variable. Crypto providers are described in depth in :ref:`crypto`.
  
   - CLI Enhancements
  
     - Addition of the :samp:`--show-crypto` option in
-      support of selectable crypto providers, as described in :ref:`ref.crypto`.
+      support of selectable crypto providers, as described in :ref:`crypto`.
  
     - Allow ``:even`` or ``:odd`` to be appended to numeric ranges
       for specification of the even or odd pages from among the pages
@@ -885,7 +885,7 @@ For a detailed list of changes, please see the file
     - 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
-      :samp:`--replace-input` in :ref:`ref.basic-options` for more details.
+      :samp:`--replace-input` in :ref:`basic-options` for more details.
  
     - The :samp:`--recompress-flate` instructs
       :command:`qpdf` to recompress streams that are
@@ -906,7 +906,7 @@ For a detailed list of changes, please see the file
       conversion methods do range checking to ensure that the cast
       can be performed with no loss of information. Every use of
       ``static_cast`` in the library was inspected to see if it could
-      use one of these safe converters instead. See :ref:`ref.casting` for additional details.
+      use one of these safe converters instead. See :ref:`casting` for additional details.
  
     - Method ``QPDF::anyWarnings`` tells whether there have been any
       warnings without clearing the list of warnings.
@@ -1100,7 +1100,7 @@ For a detailed list of changes, please see the file
       previous releases when the passwords contain non-ASCII
       characters. In some cases, the behavior differs from previous
       releases. For a discussion of the current behavior, please see
-      :ref:`ref.unicode-passwords`. The
+      :ref:`unicode-passwords`. The
       incompatibilities are as follows:
  
       - On Windows, qpdf now receives all command-line options as
@@ -1131,7 +1131,7 @@ For a detailed list of changes, please see the file
         the PDF spec requires. While this is almost always the
         correct behavior, it is possible to override the behavior if
         there is some reason to do so. This is discussed in more
-        depth in :ref:`ref.unicode-passwords`.
+        depth in :ref:`unicode-passwords`.
  
     - New options
       :samp:`--externalize-inline-images`,
@@ -1140,12 +1140,12 @@ For a detailed list of changes, please see the file
       handling of inline images and possible conversion of them to
       regular images. By default,
       :samp:`--optimize-images` now also applies to
-      inline images. These options are discussed in :ref:`ref.advanced-transformation`.
+      inline images. These options are discussed in :ref:`advanced-transformation`.
  
     - Add options :samp:`--overlay` and
       :samp:`--underlay` for overlaying or
       underlaying pages of other files onto output pages. See
-      :ref:`ref.overlay-underlay` for
+      :ref:`overlay-underlay` for
       details.
  
     - When opening an encrypted file with a password, if the
@@ -1154,12 +1154,12 @@ For a detailed list of changes, please see the file
       passwords to try to compensate for possible character encoding
       errors. This behavior can be suppressed with the
       :samp:`--suppress-password-recovery` option.
-      See :ref:`ref.unicode-passwords` for a full
+      See :ref:`unicode-passwords` for a full
       discussion.
  
     - Add the :samp:`--password-mode` option to
       fine-tune how qpdf interprets password arguments, especially
-      when they contain non-ASCII characters. See :ref:`ref.unicode-passwords` for more information.
+      when they contain non-ASCII characters. See :ref:`unicode-passwords` for more information.
  
     - In the :samp:`--pages` option, it is now
       possible to copy the same page more than once from the same
@@ -1333,7 +1333,7 @@ For a detailed list of changes, please see the file
     - Page collation: add new option
       :samp:`--collate`. When specified, the
       semantics of :samp:`--pages` change from
-      concatenation to collation. See :ref:`ref.page-selection` for examples and discussion.
+      concatenation to collation. See :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
@@ -1342,7 +1342,7 @@ For a detailed list of changes, please see the file
       :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 :ref:`ref.json`.
+      format. For more information, see :ref:`json`.
  
     - The :samp:`--generate-appearances` flag will
       cause qpdf to generate appearances for form fields if the PDF
@@ -1500,7 +1500,7 @@ For a detailed list of changes, please see the file
   - Notes for Packagers
  
     - A new section has been added to the documentation with notes
-      for packagers. Please see :ref:`ref.packaging`.
+      for packagers. Please see :ref:`packaging`.
  
     - The qpdf detects out-of-date automatically generated files. If
       your packaging system automatically refreshes libtool or
@@ -1522,7 +1522,7 @@ For a detailed list of changes, please see the file
       :samp:`--keep-files-open={[yn]}`
       to override default determination of whether to keep files open
       when merging. Please see the discussion of
-      :samp:`--keep-files-open` in :ref:`ref.basic-options` for additional details.
+      :samp:`--keep-files-open` in :ref:`basic-options` for additional details.
  
 8.2.0: August 16, 2018
   - Command-line Enhancements
@@ -1588,7 +1588,7 @@ For a detailed list of changes, please see the file
       page splitting is very slow, the old behavior (and speed) can
       be enabled by specifying
       :samp:`--preserve-unreferenced-resources`. For
-      additional details, please see :ref:`ref.advanced-transformation`.
+      additional details, please see :ref:`advanced-transformation`.
  
     - When merging multiple PDF files, qpdf no longer leaves all the
       files open. This makes it possible to merge numbers of files
@@ -1633,7 +1633,7 @@ For a detailed list of changes, please see the file
       introduced. These are designed to provide a more convenient way
       of interacting with certain document features than using
       ``QPDFObjectHandle`` directly. For details on helpers, see
-      :ref:`ref.helper-classes`. Specific additional
+      :ref:`helper-classes`. Specific additional
       interfaces are described below.
  
     - Add two new document helper classes: ``QPDFPageDocumentHelper``
@@ -1718,7 +1718,7 @@ For a detailed list of changes, please see the file
  
   - Enhancements to the :command:`qpdf` Command-line
     Tool. All new options listed here are documented in more detail in
-    :ref:`ref.using`.
+    :ref:`using`.
  
     - The option
       :samp:`--linearize-pass1={file}`
@@ -1774,7 +1774,7 @@ For a detailed list of changes, please see the file
     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 :samp:`--password-is-hex-key` in
-    :ref:`ref.basic-options` or the comments around
+    :ref:`basic-options` or the comments around
     ``QPDF::setPasswordIsHexKey`` in
     :file:`QPDF.hh` for additional details.
  
@@ -1832,10 +1832,10 @@ For a detailed list of changes, please see the file
  
   - Enhancements to the :command:`qpdf` Command-line
     Tool. All new options listed here are documented in more detail in
-    :ref:`ref.using`.
+    :ref:`using`.
  
     - Command-line arguments can now be read from files or standard
-      input using ``@file`` or ``@-`` syntax. Please see :ref:`ref.invocation`.
+      input using ``@file`` or ``@-`` syntax. Please see :ref:`invocation`.
  
     - :samp:`--rotate`: request page rotation
  
@@ -2147,7 +2147,7 @@ For a detailed list of changes, please see the file
     ``QPDFWriter::setMinimumPDFVersion`` and
     ``QPDFWriter::forcePDFVersion`` that accept an extension level,
     and extended syntax for specifying forced and minimum versions on
-    the command line as described in :ref:`ref.advanced-transformation`. Corresponding functions
+    the command line as described in :ref:`advanced-transformation`. Corresponding functions
     have been added to the C API as well.
  
   - Minor fixes to prevent qpdf from referencing objects in the file
@@ -2294,17 +2294,17 @@ For a detailed list of changes, please see the file
  
   - Support for page selection (splitting and merging PDF files) has
     been added to the :command:`qpdf` command-line
-    tool. See :ref:`ref.page-selection`.
+    tool. See :ref:`page-selection`.
  
   - Options have been added to the :command:`qpdf`
     command-line tool for copying encryption parameters from another
-    file. See :ref:`ref.basic-options`.
+    file. See :ref:`basic-options`.
  
   - New methods have been added to the ``QPDF`` object for adding and
-    removing pages. See :ref:`ref.adding-and-remove-pages`.
+    removing pages. See :ref:`adding-and-remove-pages`.
  
   - New methods have been added to the ``QPDF`` object for copying
-    objects from other PDF files. See :ref:`ref.foreign-objects`
+    objects from other PDF files. See :ref:`foreign-objects`
  
   - A new method ``QPDFObjectHandle::parse`` has been added for
     constructing ``QPDFObjectHandle`` objects from a string
-.. _ref.weak-crypto:
+.. _weak-crypto:
  
 Weak Cryptography
 =================