From 0bd908b550603a6bcc399a825a170a1263378b22 Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Mon, 30 May 2022 16:38:17 -0400 Subject: Update documentation for qpdf JSON v2 --- libqpdf/qpdf/auto_job_help.hh | 72 +++++++++++++++++++++++-------------------- 1 file changed, 38 insertions(+), 34 deletions(-) (limited to 'libqpdf/qpdf') diff --git a/libqpdf/qpdf/auto_job_help.hh b/libqpdf/qpdf/auto_job_help.hh index a933497f..5146ddae 100644 --- a/libqpdf/qpdf/auto_job_help.hh +++ b/libqpdf/qpdf/auto_job_help.hh @@ -70,6 +70,9 @@ ap.addOptionHelp("--copyright", "help", "show copyright information", R"(Display ap.addOptionHelp("--show-crypto", "help", "show available crypto providers", R"(Show a list of available crypto providers, one per line. The default provider is shown first. )"); +ap.addOptionHelp("--job-json-help", "help", "show format of job JSON", R"(Describe the format of the QPDFJob JSON input used by +--job-json-file. +)"); ap.addHelpTopic("general", "general options", R"(General options control qpdf's behavior in ways that are not directly related to the operation it is performing. )"); @@ -87,11 +90,11 @@ ap.addOptionHelp("--verbose", "general", "print additional information", R"(Outp doing, including information about files created and operations performed. )"); -ap.addOptionHelp("--progress", "general", "show progress when writing", R"(Indicate progress when writing files. -)"); } static void add_help_2(QPDFArgParser& ap) { +ap.addOptionHelp("--progress", "general", "show progress when writing", R"(Indicate progress when writing files. +)"); ap.addOptionHelp("--no-warn", "general", "suppress printing of warning messages", R"(Suppress printing of warning messages. If warnings were encountered, qpdf still exits with exit status 3. Use --warning-exit-0 with --no-warn to completely ignore @@ -172,12 +175,12 @@ companion tool "fix-qdf" can be used to repair hand-edited QDF files. QDF is a feature specific to the qpdf tool. Please see the "QDF Mode" chapter in the manual. )"); -ap.addOptionHelp("--no-original-object-ids", "transformation", "omit original object IDs in qdf", R"(Omit comments in a QDF file indicating the object ID an object -had in the original file. -)"); } static void add_help_3(QPDFArgParser& ap) { +ap.addOptionHelp("--no-original-object-ids", "transformation", "omit original object IDs in qdf", R"(Omit comments in a QDF file indicating the object ID an object +had in the original file. +)"); ap.addOptionHelp("--compress-streams", "transformation", "compress uncompressed streams", R"(--compress-streams=[y|n] Setting --compress-streams=n prevents qpdf from compressing @@ -188,9 +191,11 @@ ap.addOptionHelp("--decode-level", "transformation", "control which streams to u When uncompressing streams, control which types of compression schemes should be uncompressed: -- none: don't uncompress anything. This is the default with --json-output. +- none: don't uncompress anything. This is the default with + --json-output. - generalized: uncompress streams compressed with a - general-purpose compression algorithm. This is the default. + general-purpose compression algorithm. This is the default + except when --json-output is given. - specialized: in addition to generalized, also uncompress streams compressed with a special-purpose but non-lossy compression scheme @@ -290,13 +295,13 @@ from the resulting set, not based on the original page numbers. ap.addHelpTopic("modification", "change parts of the PDF", R"(Modification options make systematic changes to certain parts of the PDF, causing the PDF to render differently from the original. )"); +} +static void add_help_4(QPDFArgParser& ap) +{ ap.addOptionHelp("--pages", "modification", "begin page selection", R"(--pages file [--password=password] [page-range] [...] -- Run qpdf --help=page-selection for details. )"); -} -static void add_help_4(QPDFArgParser& ap) -{ ap.addOptionHelp("--collate", "modification", "collate with --pages", R"(--collate[=n] Collate rather than concatenate pages specified with --pages. @@ -460,14 +465,14 @@ ap.addOptionHelp("--assemble", "encryption", "restrict document assembly", R"(-- Enable/disable document assembly (rotation and reordering of pages). This option is not available with 40-bit encryption. )"); +} +static void add_help_5(QPDFArgParser& ap) +{ ap.addOptionHelp("--extract", "encryption", "restrict text/graphic extraction", R"(--extract=[y|n] Enable/disable text/graphic extraction for purposes other than accessibility. )"); -} -static void add_help_5(QPDFArgParser& ap) -{ ap.addOptionHelp("--form", "encryption", "restrict form filling", R"(--form=[y|n] Enable/disable whether filling form fields is allowed even if @@ -638,6 +643,9 @@ ap.addOptionHelp("--remove-attachment", "attachments", "remove an embedded file" Remove an embedded file using its key. Get the key with --list-attachments. )"); +} +static void add_help_6(QPDFArgParser& ap) +{ ap.addHelpTopic("pdf-dates", "PDF date format", R"(When a date is required, the date should conform to the PDF date format specification, which is "D:yyyymmddhhmmssz" where "z" is either literally upper case "Z" for UTC or a timezone offset in @@ -650,9 +658,6 @@ Examples: - D:20210207161528-05'00' February 7, 2021 at 4:15:28 p.m. - D:20210207211528Z February 7, 2021 at 21:15:28 UTC )"); -} -static void add_help_6(QPDFArgParser& ap) -{ ap.addHelpTopic("add-attachment", "attach (embed) files", R"(The options listed below appear between --add-attachment and its terminating "--". )"); @@ -747,14 +752,14 @@ the linearization hint tables are correct. )"); ap.addOptionHelp("--show-linearization", "inspection", "show linearization hint tables", R"(Check and display all data in the linearization hint tables. )"); +} +static void add_help_7(QPDFArgParser& ap) +{ ap.addOptionHelp("--show-xref", "inspection", "show cross reference data", R"(Show the contents of the cross-reference table or stream (object locations in the file) in a human-readable form. This is especially useful for files with cross-reference streams, which are stored in a binary format. )"); -} -static void add_help_7(QPDFArgParser& ap) -{ ap.addOptionHelp("--show-object", "inspection", "show contents of an object", R"(--show-object={trailer|obj[,gen]} Show the contents of the given object. This is especially useful @@ -814,21 +819,20 @@ This option is repeatable. If given, only specified objects will be shown in the "objects" key of the JSON output. Otherwise, all objects will be shown. )"); -ap.addOptionHelp("--job-json-help", "json", "show format of job JSON", R"(Describe the format of the QPDFJob JSON input used by ---job-json-file. -)"); ap.addOptionHelp("--json-stream-data", "json", "how to handle streams in json output", R"(--json-stream-data={none|inline|file} -Control whether streams in json output should be omitted, -written inline (base64-encoded) or written to a file. If "file" -is chosen, the file will be the name of the input file appended -with -nnn where nnn is the object number. The prefix can be -overridden with --json-stream-prefix. +When used with --json-output, this option controls whether +streams in json output should be omitted, written inline +(base64-encoded) or written to a file. If "file" is chosen, the +file will be the name of the output file appended with -nnn where +nnn is the object number. The prefix can be overridden with +--json-stream-prefix. )"); ap.addOptionHelp("--json-stream-prefix", "json", "prefix for json stream data files", R"(--json-stream-prefix=file-prefix -When --json-stream-data=file is given, override the input file -name as the prefix for stream data files. Whatever is given here +When used with --json-output, --json-stream-data=file-prefix +sets the prefix for stream data files, overriding the default, +which is to use the output file name. Whatever is given here will be appended with -nnn to create the name of the file that will contain the data for the stream stream in object nnn. )"); @@ -836,19 +840,19 @@ ap.addOptionHelp("--json-output", "json", "serialize to JSON", R"(--json-output[ The output file will be qpdf JSON format at the given version. "version" may be a specific version or "latest" (the default). -Version 1 is not supported. See also --json-stream-data, +The only supported version is 2. See also --json-stream-data, --json-stream-prefix, and --decode-level. )"); ap.addOptionHelp("--json-input", "json", "input file is qpdf JSON", R"(Treat the input file as a JSON file in qpdf JSON format as -written by qpdf --json-output. See the "QPDF JSON Format" +written by qpdf --json-output. See the "qpdf JSON Format" section of the manual for information about how to use this option. )"); ap.addOptionHelp("--update-from-json", "json", "update a PDF from qpdf JSON", R"(--update-from-json=qpdf-json-file -Update a PDF file from a JSON file. Please see the "QPDF JSON -Format" section of the manual for information about how to use -this option. +Update a PDF file from a JSON file. Please see the "qpdf JSON" +chapter of the manual for information about how to use this +option. )"); } static void add_help_8(QPDFArgParser& ap) -- cgit v1.2.3-54-g00ecf