mirror of
https://github.com/qpdf/qpdf.git
synced 2024-09-28 04:59:05 +00:00
Doc updates from m-holger
This commit is contained in:
parent
dd3b2cedd3
commit
c95f02115c
@ -27,7 +27,7 @@ executable is available from inside the C++ library using the
|
|||||||
- The ``QPDFJob`` C++ API
|
- The ``QPDFJob`` C++ API
|
||||||
|
|
||||||
If you can understand how to use the :command:`qpdf` CLI, you can
|
If you can understand how to use the :command:`qpdf` CLI, you can
|
||||||
understand the ``QPDFJob`` class and the json file. qpdf guarantees
|
understand the ``QPDFJob`` class and the JSON file. qpdf guarantees
|
||||||
that all of the above methods are in sync. Here's how it works:
|
that all of the above methods are in sync. Here's how it works:
|
||||||
|
|
||||||
.. list-table:: QPDFJob Interfaces
|
.. list-table:: QPDFJob Interfaces
|
||||||
@ -55,8 +55,8 @@ keys are command-line flags converted to camelCase. Positional
|
|||||||
arguments have some corresponding key, which you can find by running
|
arguments have some corresponding key, which you can find by running
|
||||||
``qpdf`` with the :qpdf:ref:`--job-json-help` flag. For example, input
|
``qpdf`` with the :qpdf:ref:`--job-json-help` flag. For example, input
|
||||||
and output files are named by positional arguments on the CLI. In the
|
and output files are named by positional arguments on the CLI. In the
|
||||||
JSON, they are ``"inputFile"`` and ``"outputFile"``. The following are
|
JSON, they appear in the ``"inputFile"`` and ``"outputFile"`` keys.
|
||||||
equivalent:
|
The following are equivalent:
|
||||||
|
|
||||||
.. It would be nice to have an automated test that these are all the
|
.. It would be nice to have an automated test that these are all the
|
||||||
same, but we have so few live examples that it's not worth it for
|
same, but we have so few live examples that it's not worth it for
|
||||||
@ -135,7 +135,7 @@ C++ code:
|
|||||||
return 0;
|
return 0;
|
||||||
}
|
}
|
||||||
|
|
||||||
It is also possible to mix and match command-line options and json
|
It is also possible to mix and match command-line options and JSON
|
||||||
from the CLI. For example, you could create a file called
|
from the CLI. For example, you could create a file called
|
||||||
:file:`my-options.json` containing the following:
|
:file:`my-options.json` containing the following:
|
||||||
|
|
||||||
@ -174,7 +174,7 @@ This section describes some of the design rationale and history behind
|
|||||||
Documentation of ``QPDFJob`` is divided among three places:
|
Documentation of ``QPDFJob`` is divided among three places:
|
||||||
|
|
||||||
- "HOW TO ADD A COMMAND-LINE ARGUMENT" in :file:`README-maintainer`
|
- "HOW TO ADD A COMMAND-LINE ARGUMENT" in :file:`README-maintainer`
|
||||||
provides a quick reminder for how to add a command-line argument
|
provides a quick reminder of how to add a command-line argument
|
||||||
|
|
||||||
- The source file :file:`generate_auto_job` has a detailed explanation
|
- The source file :file:`generate_auto_job` has a detailed explanation
|
||||||
about how ``QPDFJob`` and ``generate_auto_job`` work together
|
about how ``QPDFJob`` and ``generate_auto_job`` work together
|
||||||
@ -182,11 +182,11 @@ Documentation of ``QPDFJob`` is divided among three places:
|
|||||||
- This chapter of the manual has other details.
|
- This chapter of the manual has other details.
|
||||||
|
|
||||||
Prior to qpdf version 10.6.0, the qpdf CLI executable had a lot of
|
Prior to qpdf version 10.6.0, the qpdf CLI executable had a lot of
|
||||||
functionality built into the executable that was not callable from the
|
functionality built into it that was not callable from the library as
|
||||||
library as such. This created a number of problems:
|
such. This created a number of problems:
|
||||||
|
|
||||||
- Some of the logic in :file:`qpdf.cc` was pretty complex, such as
|
- Some of the logic in :file:`qpdf.cc` was pretty complex, such as
|
||||||
image optimization, generating json output, and many of the page
|
image optimization, generating JSON output, and many of the page
|
||||||
manipulations. While those things could all be coded using the C++
|
manipulations. While those things could all be coded using the C++
|
||||||
API, there would be a lot of duplicated code.
|
API, there would be a lot of duplicated code.
|
||||||
|
|
||||||
@ -212,7 +212,7 @@ Here are a few notes on some design decisions about QPDFJob and its
|
|||||||
various interfaces.
|
various interfaces.
|
||||||
|
|
||||||
- Bare command-line options (flags with no parameter) map to config
|
- Bare command-line options (flags with no parameter) map to config
|
||||||
functions that take no options and to json keys whose values are
|
functions that take no options and to JSON keys whose values are
|
||||||
required to be the empty string. The rationale is that we can later
|
required to be the empty string. The rationale is that we can later
|
||||||
change these bare options to options that take an optional parameter
|
change these bare options to options that take an optional parameter
|
||||||
without breaking backward compatibility in the CLI or the JSON.
|
without breaking backward compatibility in the CLI or the JSON.
|
||||||
@ -244,5 +244,5 @@ various interfaces.
|
|||||||
Config class, adding a config member variable to ``ArgParser`` in
|
Config class, adding a config member variable to ``ArgParser`` in
|
||||||
:file:`QPDFJob_argv.cc` and ``Handlers`` in :file:`QPDFJob_json.cc`,
|
:file:`QPDFJob_argv.cc` and ``Handlers`` in :file:`QPDFJob_json.cc`,
|
||||||
and make sure that manually implemented handlers are consistent with
|
and make sure that manually implemented handlers are consistent with
|
||||||
each other. It is best under the cases to explicit test cases for
|
each other. It is best to add explicit test cases for all the
|
||||||
all the various ways to get to the option.
|
various ways to get to the option.
|
||||||
|
Loading…
Reference in New Issue
Block a user