search

pdf-association / pdf-issues

Industry-based resolutions for issues and errata reported against any PDF-related specification
https://pdf-issues.pdfa.org/
62 stars 2 forks source link

Edit "Path-Painting operators" for clarity #434

Open robinwatts opened 1 month ago

robinwatts commented 1 month ago

Section 8.5.3 Path-painting operators

Nowhere in this section of the spec does it state that all the path-painting operators other than W and W* clear the current path after they are rendered.

This information is given, but in section 8.5.2.1 within the "Path construction operators" section. This is fine if you're reading through the spec from end to end, but is extremely unclear if you just look up the operators themselves.

A possible fix for this would to amend the text in 8.5.3.1 from:

"The path-painting operators end a path object, causing it to be painted on the current page in the manner that the operator specifies."

to be something like:

"The path-painting operators end a path object, causing it to be painted on the current page in the manner that the operator specifies, and then the current path is reset to being undefined."

An further (or alternative) improvement would be to amend the entries within Table 59 to each include "Reset the current path to undefined."

petervwyatt commented 1 month ago

The second para in 8.5.2.1 states this as an explicit requirement "After the current path has been painted, it shall become no longer defined; there is then no current path until a new one is begun with the m or re operator". The following paragraph in 8.5.2.1 then discusses when there is no current point, errors, etc. as does 8.5.3.1 (slightly duplicated but no misalignment that I can see).

So I think this is OK albeit badly arranged,

robinwatts commented 1 month ago

Yes. The information is there, but as I say, only in 8.5.2.1 Path construction operators.

Come to the spec cold, and lookup, say, the 'f' operator. You'll look it up and be refered to 8.5.3. No mention of the side effect there at all.

It seems reasonable to assume that what a Path-painting operator does should be specified in the section that's dedicated to telling you what Path-painting operators do, not in the section that tells you what Path-construction operators do!

petervwyatt commented 4 weeks ago

If someone comes to the spec cold and only reads an H3 / 8.5.2 "Path construction operators" then they'll be in a whole world of pain in many other ways too! And the same also goes for all the legacy Adobe PDF specs.

This kind of issue is throughout many of the legacy portions of the PDF spec. We now take a very firm stance never to duplicate requirements as that is a maintenance issue or (worse) confusing should the wording be subtly different. At most, we would add a reference to the section, but in this case, the H3 clauses are both adjacent and under the single H2 parent "Path construction and painting" so you should reasonably expect someone to read in the neighbourhood.

In the long term, we have desires to fix this holistically throughout the PDF spec, but that involves major surgery and a major effort well beyond errata. My Graphic Operators Cheat Sheet Path Construction section already summarises the current point information, but based on this errata I have updated the Path Painting section to now be explicit about the current path becoming undefined when painted. A new improved set of Cheat Sheets will be available very soon.

So closing this errata as "no fix" to ISO 32000-2 as we now provide cheat sheet summaries in a hope to bring highly condensed information from across the PDF spec into a single spot for reference - and with the very strong assumption that users of the cheat sheets have already fully read the PDF spec!

robinwatts commented 3 weeks ago

OK. All excellent points. One last suggestion before I give up on this then :)

At most, we would add a reference to the section...

In line with that, could we add a sentence/note to 8.5.3.1 saying: "While these operators are primarily path-painting ones, they also serve a purpose in path-construction as they may affect the current graphics path. See section 8.5.2.1 Path-construction operators for more details."

This keeps the change small, avoids any duplication (as it merely points to where the information may be found), and addresses my concerns.

If not now, then maybe in any future version of the spec.

petervwyatt commented 3 weeks ago

Reopened issue to see if PDF TWG would be interested in adding a line as per @robinwatts comment suggestion above.