[
https://issues.apache.org/jira/browse/PDFBOX-6230?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18139720#comment-18139720
]
Christian Appl commented on PDFBOX-6230:
----------------------------------------
[~tilman]
I would agree to it - most probably oversights. COSIncrement includes the
containing dictionary of a changed direct object or array, and a changed
indirect object is written without its ancestors being marked. So the old
sentence is outdated, and dropping the parent-marking example is fine.
Two corrections to the new wording, though:
- The walk starts at the trailer, not at the catalog. (See COSWriter and just
for the sake of clarity.)
- It only descends into objects that have already been loaded (or whose
COSObject is marked). An object whose path from the trailer was never loaded is
still not found; for that case, the objectsToWrite variant remains the way to
go.
*In COSWriter and PDDocument:*
"PDFBox traverses the document catalog and collects updated objects." ->
"Starting at the trailer, PDFBox walks the objects that have already been
loaded and collects updated objects."
"callers do not need to mark every object along the path from the catalog." ->
"callers do not need to mark every object along the path from the trailer. An
object whose path from the trailer has never been loaded is not found; pass it
as objectsToWrite."
"The incremental writer traverses the document graph from the catalog,
including non-flat page trees. It is not necessary to mark each ancestor solely
to make a changed page reachable to the incremental writer." ->
"Pages obtained through the page tree (e.g. getPage(int)) are reached by the
incremental writer, also in a non-flat page tree; their ancestors need not be
marked."
*Plus it probably is worth fixing the related additional oversights:*
The objectsToWrite Javadocs (COSWriter constructor,
PDDocument.saveIncremental(OutputStream, Set)) still carry the old "no path"
sentence.
*Also in COSWriter (objectsToWrite-Constructor) and
PDDocument.saveIncremental(OutputStream, Set):*
"This allows to include objects even if there is no path of objects that have
isNeedToBeUpdated() set so the incremental update gets smaller." ->
"The given objects are written in addition to those the incremental writer
collects; use this for objects it does not reach."
> Documentation is misleading/outdated around incremental writing
> ---------------------------------------------------------------
>
> Key: PDFBOX-6230
> URL: https://issues.apache.org/jira/browse/PDFBOX-6230
> Project: PDFBox
> Issue Type: Bug
> Components: PDModel
> Affects Versions: 3.0.8 PDFBox
> Reporter: Jakob Heher
> Priority: Minor
> Labels: documentation
> Original Estimate: 2h
> Remaining Estimate: 2h
>
> The documentation on
> [PDDocument::saveIncremental|https://javadoc.io/static/org.apache.pdfbox/pdfbox/3.0.8/org/apache/pdfbox/pdmodel/PDDocument.html#saveIncremental-java.io.OutputStream-]
> and
> [COSWriter::COSWriter|https://javadoc.io/static/org.apache.pdfbox/pdfbox/3.0.8/org/apache/pdfbox/pdfwriter/COSWriter.html#COSWriter-java.io.OutputStream-org.apache.pdfbox.io.RandomAccessRead-]
> specifies:
> {quote}There must be a path of objects that have
> [{{COSUpdateInfo.isNeedToBeUpdated()}}|https://javadoc.io/static/org.apache.pdfbox/pdfbox/3.0.8/org/apache/pdfbox/cos/COSUpdateInfo.html#isNeedToBeUpdated--]
> set, starting from the document catalog.
> {quote}
>
> However, I believe this to be incorrect, since COSIncrement includes a
> (transitive) parent if there is a direct child (of a direct child of...) that
> requires an update:
> [https://github.com/apache/pdfbox/blob/3.0.8/pdfbox/src/main/java/org/apache/pdfbox/cos/COSIncrement.java#L114]
> This was added in
> [https://github.com/apache/pdfbox/commit/23e85be12c8968cbb68ce99b6071f2a12bf7a5f4]
> in response to PDFBOX-5263, I believe.
> Was the documentation update simply missed here, or is there something I am
> missing?
--
This message was sent by Atlassian Jira
(v10.3.26#10030026)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
