OpenSystemsDevelopment / qpdf

Commit a3c890c0f84215f9d37a01bdadf93e4512987530

Authored by Jay Berkenbilt
1 parent 5c6808b4

TODO: plan for QPDFLogger

Inline Side-by-side
Showing 1 changed file with 46 additions and 31 deletions
... ... @@ -8,6 +8,10 @@ Before Release:
8 8 * Stay on top of https://github.com/pikepdf/pikepdf/pull/315
9 9 * Release qtest with updates to qtest-driver and copy back into qpdf
10 10  
  11 +Next:
  12 +* output capture
  13 +* QPDFPagesTree -- avoid ever flattening the pages tree.
  14 +
11 15 Pending changes:
12 16  
13 17 * Think about whether additional JSON use cases would be served by
... ... @@ -20,17 +24,10 @@ Pending changes:
20 24 json.rst" from June 5
21 25 (04ad60e5-3274-4a9e-abde-3de97640d370@www.fastmail.com)
22 26 * Good C API for json v2
23   -* QPDFPagesTree -- avoid ever flattening the pages tree.
24 27 * Check about runpath in the linux-bin distribution. I think the
25 28 appimage build specifically is setting the runpath, which is
26 29 actually desirable in this case. Make sure to understand and
27 30 document this. Maybe add a check for it in the build.
28   -* See if I can change all output and error messages issued by the
29   - library, when context is available, to have a pipeline rather than a
30   - FILE* or std::ostream. This makes it possible for people to capture
31   - output more flexibly. We could also add a generic pipeline that
32   - takes std::function<void(char const*, size_t)> or even a
33   - void(*)(char const*, unsigned long) for the C API.
34 31 * Make job JSON accept a single element and treat as an array of one
35 32 when an array is expected. This allows for making things repeatable
36 33 in the future without breaking compatibility and is needed for the
... ... @@ -46,10 +43,6 @@ Pending changes:
46 43 reveal additional details, --show-encryption could potentially retry
47 44 with this option if the first time doesn't work. Then, with the file
48 45 open, we can read the encryption dictionary normally.
49   -* Find all places in the code that write to std::cout, std::err,
50   - stdout, or stderr to make sure they obey default output stream
51   - settings for QPDF and QPDFJob. This probably includes adding a
52   - Pl_Ostream pipeline.
53 46 * Nice to have:
54 47 * In libtests, separate executables that need the object library
55 48 from those that strictly use public API. Move as many of the test
... ... @@ -62,6 +55,47 @@ Pending changes:
62 55  
63 56 Soon: Break ground on "Document-level work"
64 57  
  58 +Output Capture + QPDFJob
  59 +========================
  60 +
  61 +QPDFJob:
  62 +
  63 +* Expose the meanings of the return values of qpdfjob functions to the
  64 + C API.
  65 +* Allow users to supply a custom progress reporter for QPDFJob
  66 +
  67 +Output Capture
  68 +
  69 +See https://github.com/qpdf/qpdf/issues/691
  70 +
  71 +QPDFLogger maintains pipelines for info, warn, error, and save.
  72 +
  73 +There is a singleton, default QPDFLogger which all QPDF and QPDFJob
  74 +objects get on construction. In most cases, it is not necessary to
  75 +override this. Allow QPDFJob and QPDF to be passed a new logger
  76 +instance. QPDFJob should pass its QPDFLogger to all QPDF objects it
  77 +creates. The main uses cases for this would be for multithreading or
  78 +for having a library that uses QPDF privately and modifies logger
  79 +settings so that it wouldn't interfere with a downstream library or
  80 +application also using qpdf.
  81 +
  82 +There needs to be a C API to QPDFLogger. Use functions like this:
  83 +
  84 +void set_info((*f)(char* data, unsigned int len, void* udata), void* udata);
  85 +
  86 +We should probably deprecate the output/error setters in QPDF and
  87 +QPDFJob. In the meantime, document that they won't work anymore to set
  88 +different outputs with different QPDF objects. We may need to delete
  89 +rather than deprecate these methods.
  90 +
  91 +Find all places in the library that write to stdout/stderr/cout/cerr.
  92 +Also find places that raise exceptions if unable to warn. These should
  93 +use the global output writer.
  94 +
  95 +Figure out a good way to use the save pipeline for QPDFWriter as well
  96 +as saving attachments, showing stream data, etc.
  97 +
  98 +
65 99 QPDFPagesTree
66 100 =============
67 101  
... ... @@ -116,32 +150,13 @@ Possible future JSON enhancements
116 150 * Consider having warnings be included in the json in a "warnings" key
117 151 in json mode.
118 152  
  153 +
119 154 QPDFJob
120 155 =======
121 156  
122 157 Here are some ideas for QPDFJob that didn't make it into 10.6. Not all
123 158 of these are necessarily good -- just things to consider.
124 159  
125   -* replace mode: --replace-object, --replace-stream-raw,
126   - --replace-stream-filtered
127   - * update first paragraph of QPDF JSON in the manual to mention this
128   - * object numbers are not preserved by write, so object ID lookup
129   - has to be done separately for each invocation
130   - * you don't have to specify length for streams
131   - * you only have to specify filtering for streams if providing raw data
132   -
133   -* Allow users to supply a custom progress reporter for QPDFJob
134   -
135   -* Better interoperability with json output:
136   -
137   - * Make sure all the things that print stuff to stdout have json
138   - equivalents (check, showLinearizationData, etc.)
139   - * There should be a way to get json output other than having it
140   - print to stdout. It should be multi-language friendly and allow
141   - for large amounts of data, such as providing a callback that qpdf
142   - can write to (like a pipeline)
143   - * See also JSON v2
144   -
145 160 * How do we chain jobs? The idea would be that the input and/or output
146 161 of a QPDFJob could be a QPDF object rather than a file. For input,
147 162 it's pretty easy. For output, none of the output-specific options
... ...