Manual: convert more lists to tables

Jay Berkenbilt
1 parent 3d2d75cf
Showing 1 changed file with 117 additions and 54 deletions
manual/encryption.rst
@@ -114,44 +114,69 @@ Algorithm parameters ``V`` and ``R``
   encrypting the file, handling keys, etc. It may have any of the
   following values:
  
-  - 1: The original algorithm, which encrypted files using 40-bit keys.
-
-  - 2: An extension of the original algorithm allowing longer keys.
-    Introduced in PDF 1.4.
-
-  - 3: An unpublished algorithm that permits file encryption key
-    lengths ranging from 40 to 128 bits. Introduced in PDF 1.4. qpdf
-    is believed to be able to read files with ``V`` = 3 but does not
-    write such files.
-
-  - 4: An extension of the algorithm that allows it to be
-    parameterized by additional rules for handling strings and
-    streams. Introduced in PDF 1.5.
-
-  - 5: An algorithm that allows specification of separate security
-    handlers for strings and streams as well as embedded files, and
-    which supports 256-bit keys. Introduced in PDF 1.7 extension level
-    3 and later extended in extension level 8. This is the encryption
-    system in the PDF 2.0 specification, ISO-32000.
+  .. list-table:: Encryption Algorithms: ``V``
+     :widths: 10 80
+     :header-rows: 1
+
+     - - V
+       - Meaning
+
+     - - 1
+       - The original algorithm, which encrypted files using 40-bit keys.
+
+     - - 2
+       - An extension of the original algorithm allowing longer keys.
+         Introduced in PDF 1.4.
+
+     - - 3
+       - An unpublished algorithm that permits file encryption key
+         lengths ranging from 40 to 128 bits. Introduced in PDF 1.4.
+         qpdf is believed to be able to read files with ``V`` = 3 but
+         does not write such files.
+
+     - - 4
+       - An extension of the algorithm that allows it to be
+         parameterized by additional rules for handling strings and
+         streams. Introduced in PDF 1.5.
+
+     - - 5
+       - An algorithm that allows specification of separate security
+         handlers for strings and streams as well as embedded files,
+         and which supports 256-bit keys. Introduced in PDF 1.7
+         extension level 3 and later extended in extension level 8.
+         This is the encryption system in the PDF 2.0 specification,
+         ISO-32000.
  
   ``R`` is a code specifying the revision of the standard handler. It
   is tightly coupled with the value of ``V``. ``R`` may have any of
   the following values:
  
-  - 2: ``V`` must be 1
+  .. list-table:: Relationship between ``R`` and ``V``
+     :widths: 10 80
+     :header-rows: 1
  
-  - 3: ``V`` must be 2 or 3
+     - - R
+       - Expected V
  
-  - 4: ``V`` must be 4
+     - - 2
+       - ``V`` must be 1
  
-  - 5: ``V`` must be 5; this extension was never fully specified and
-    existed for a short time in some versions of Acrobat.
-    :command:`qpdf` is able to read and write this format, but it
-    should not be used for any purpose other than testing
-    compatibility with the format.
+     - - 3
+       - ``V`` must be 2 or 3
  
-  - 6: ``V`` must be 5. This is the only value that is not deprecated
-    in the PDF 2.0 specification, ISO-32000.
+     - - 4
+       - ``V`` must be 4
+
+     - - 5
+       - ``V`` must be 5; this extension was never fully specified and
+         existed for a short time in some versions of Acrobat.
+         :command:`qpdf` is able to read and write this format, but it
+         should not be used for any purpose other than testing
+         compatibility with the format.
+
+     - - 6
+       - ``V`` must be 5. This is the only value that is not
+         deprecated in the PDF 2.0 specification, ISO-32000.
  
 Encryption Dictionary
   Encrypted PDF files have an encryption dictionary. There are several
@@ -203,12 +228,12 @@ However, the values of bits other than those in the table are ignored,
 so having incorrect values probably doesn't break anything in most
 cases. A value of 1 indicates that the permission is granted.
  
-.. list-table:: P Parameter
+.. list-table:: ``P`` Bit Values
    :widths: 10 80
    :header-rows: 1
  
-   - - bit
-     - meaning
+   - - Bit
+     - Meaning
  
    - - 3
      - for ``R`` = 2 printing; for ``R`` >= 3, printing at low
@@ -254,45 +279,83 @@ to ``P`` based on the various settings of different security options.
  
 - Start with all bits set except bits 1 and 2, which are cleared
  
-- For ``R`` = 2:
+- Clear bits and described in the table below:
+
+  .. list-table:: Command-line Arguments and ``P`` Bit Values
+     :widths: 20 25 45
+     :header-rows: 1
+
+     - - R
+       - Argument
+       - Bits Cleared
  
-  - ``--print=n``: clear bit 3
+     - - R = 2
+       - ``--print=n``
+       - 3
  
-  - ``--modify=n``: clear bit 4
+     - - R = 2
+       - ``--modify=n``
+       - 4
  
-  - ``--extract=n``: clear bit 5
+     - - R = 2
+       - ``--extract=n``
+       - 5
  
-  - ``--annotate=n``: clear bit 6
+     - - R = 2
+       - ``--annotate=n``
+       - 6
  
-- For ``R >= 3``:
+     - - R = 3
+       - ``--accessibility=n``
+       - 10
  
-  - ``--accessibility=n``: for ``R`` = 3, clear bit 10; otherwise,
-    ignore so bit 10 is always clear if ``R`` >= 4. qpdf allows
-    creating files with bit 10 clear so that it can be used to create
-    test files to ensure that a conforming reader ignores the value of
-    the bit. You should never intentionally clear accessibility.
+     - - R >= 4
+       - ``--accessibility=n``
+       - ignored
  
-  - ``--extract=n``: clear bit 5
+     - - R >= 3
+       - ``--extract=n``
+       - 5
  
-  - ``--print=none``: clear bits 3 and 12
+     - - R >= 3
+       - ``--print=none``
+       - 3, 12
  
-  - ``--print=low``: clear bit 12
+     - - R >= 3
+       - ``--print=low``
+       - 12
  
-  - ``--modify=none``: clear bits 4, 6, 9, and 11
+     - - R >= 3
+       - ``--modify=none``
+       - 4, 6, 9, 11
  
-  - ``--modify=assembly``: clear bits 4, 6, and 9
+     - - R >= 3
+       - ``--modify=assembly``
+       - 4, 6, 9
  
-  - ``--modify=form``: clear bits 4 and 6
+     - - R >= 3
+       - ``--modify=form``
+       - 4, 6
  
-  - ``--modify=annotate``: clear bit 4
+     - - R >= 3
+       - ``--modify=annotate``
+       - 4
  
-  - ``--assemble=n``: clear bit 11
+     - - R >= 3
+       - ``--assemble=n``
+       - 11
  
-  - ``--annotate=n``: clear bit 6
+     - - R >= 3
+       - ``--annotate=n``
+       - 6
  
-  - ``--form=n``: clear bit 9
+     - - R >= 3
+       - ``--form=n``
+       - 9
  
-  - ``--modify-other=n``: clear bit 4
+     - - R >= 3
+       - ``--modify-other=n``
+       - 4
  
 Options to :command:`qpdf`, both at the CLI and library level, allow
 more granular clearing of permission bits than do most tools,