[pdftex] Ambiguity in pdfTeX user manual syntax description

[Douglas McKenna]

Dear pdfTeX user manual maintainers,


In my pdfTeX user manual, version 1.40.15, (circa 2014), the "General definitions and syntax rules" section on page 17 defines

⟨open-action spec⟩ → openaction ⟨action spec⟩

where "openaction" on the right hand side of the production rule appears to be a literal. The documentation for \pdfcatalog syntax on page 20 properly references the left side using

\pdfcatalog ⟨general text⟩ [ ⟨open-action spec⟩ ]

But in the last paragraph on that page, first sentence, it says

The ⟨openaction⟩ is the action …

This is ambiguous, because ⟨openaction⟩ is not defined in angle brackets in the General definitions section, but is used as a literal token. Should this sentence start with

The ⟨open-action spec⟩ is the action …

or does <openaction> in that sentence refer to the literal token "openaction" used in the General definitions section?

Thanks.


- Doug McKenna
Mathemaesthetics, Inc.

[Karl Berry]

Hi Doug,

Should this sentence start with
The œò§èopen-action specœò§é is the action œôóŠ

Certainly yes. Well, it could be yet better written than that, but
that's the basic correction. I will fix the manual.

I.e., if the TeX source says
\pdfcatalog /PageMode openaction /UseOutlines
the semantic open action written into the PDF file will be /UseOutlines. Etc.

(At least, I assume so -- I can't say I've actually tried it.)
The "openaction" literal is just a literal, as I'm sure you figured
all along :).

I see a variety of other fixes and improvements, e.g., the current text
refers to Table 4, but now the list of actions is Table 5 (in the
current manual, maybe not in the old version you're looking at).

Thanks,
Karl

P.S. How goes literac and jsbox?

[Karl Berry]

I was wrong in what I said; the /PageMode is entirely independent
from the "open-action spec".

I think the way the syntax was shown was unnecessarily baroque. It
seems that the idea is that "openaction <action spec>" can optionally
follow the \pdfcatalog <general text>, where <action spec> is the same
as for, e.g., \pdfstartlink.

The samplepdf.tex file gives an example:

\pdfcatalog{ % Catalog dictionary of PDF output.
/PageMode /UseOutlines %
/URI (http://www.fi.muni.cz/) %
%...
}
openaction goto page 1 {/Fit} % the action to be activated when
% opening the document; this is the
% same as <action spec> for links...

I've tinkered with the manual accordingly. Thanks for the report. -k