PDF Reference sixth edition, Adobe Portable Document Format Version 1.7 (book 2) — page 7
843
SECTION 10.2
Metadata
10.2
Metadata
A PDF document may include general information, such as the document’s title,
author, and creation and modification dates. Such global information about the
document (as opposed to its content or structure) is called metadata and is in-
tended to assist in cataloguing and searching for documents in external databas-
es. A document’s metadata may also be added or changed by users or plug-in
extensions (see implementation note 160 in Appendix H). Beginning with PDF
1.4, metadata can also be specified for individual components of a document.
Metadata can be stored in a PDF document in either of the following ways:
• In a document information dictionary associated with the document (Section
10.2.1)
• In a metadata stream (PDF 1.4) associated with the document or a component
of the document (Section 10.2.2)
10.2.1
Document Information Dictionary
The optional Info entry in the trailer of a PDF file (see Section 3.4.4, “File Trailer”)
can hold a document information dictionary containing metadata for the docu-
ment; Table 10.2 shows its contents. Any entry whose value is not known should
be omitted from the dictionary rather than included with an empty string as its
value.
Some plug-in extensions may choose to permit searches on the contents of the
document information dictionary. To facilitate browsing and editing, all keys in
the dictionary are fully spelled out, not abbreviated. New keys should be chosen
with care so that they make sense to users.
The value associated with any key not specifically mentioned in Table 10.2 must
be a text string.
Note: Although consumer applications can store custom metadata in the document
information dictionary, it is inappropriate to store private content or structural in-
formation there. Such information should be stored in the document catalog instead
(see Section 3.6.1, “Document Catalog”).
844
CHAPTER 10
Document Interchange
TABLE 10.2 Entries in the document information dictionary
KEY
TYPE
VALUE
Title
text string
(Optional; PDF 1.1) The document’s title.
Author
text string
(Optional) The name of the person who created the document.
Subject
text string
(Optional; PDF 1.1) The subject of the document.
Keywords
text string
(Optional; PDF 1.1) Keywords associated with the document.
Creator
text string
(Optional) If the document was converted to PDF from another format, the
name of the application (for example, Adobe FrameMaker®) that created the
original document from which it was converted.
Producer
text string
(Optional) If the document was converted to PDF from another format, the
name of the application (for example, Acrobat Distiller) that converted it to
PDF.
CreationDate
date
(Optional) The date and time the document was created, in human-readable
form (see Section 3.8.3, “Dates”).
ModDate
date
(Required if PieceInfo is present in the document catalog; otherwise optional;
PDF 1.1) The date and time the document was most recently modified, in hu-
man-readable form (see Section 3.8.3, “Dates”).
Trapped
name
(Optional; PDF 1.3) A name object indicating whether the document has
been modified to include trapping information (see Section 10.10.5, “Trap-
ping Support”):
True
The document has been fully trapped; no further trapping is
needed. (This is the name True, not the boolean value true.)
False
The document has not yet been trapped; any desired
trapping must still be done. (This is the name False, not the
boolean value false.)
Unknown Either it is unknown whether the document has been
trapped or it has been partly but not yet fully trapped; some
additional trapping may still be needed.
Default value: Unknown.
The value of this entry may be set automatically by the software creating the
document’s trapping information, or it may be known only to a human oper-
ator and entered manually.
845
SECTION 10.2
Metadata
Example 10.1 shows a typical document information dictionary.
Example 10.1
1 0 obj
<< /Title ( PostScript Language Reference, Third Edition )
/Author ( Adobe Systems Incorporated )
/Creator ( Adobe FrameMaker 5 . 5 . 3 for Power Macintosh® )
/Producer ( Acrobat Distiller 3 . 01 for Power Macintosh )
/CreationDate ( D : 19970915110347 - 08 ' 00 ' )
/ModDate ( D : 19990209153925 - 08 ' 00 ' )
>>
endobj
10.2.2
Metadata Streams
Metadata, both for an entire document and for components within a document,
can be stored in PDF streams called metadata streams (PDF 1.4). Metadata
streams have the following advantages over the document information dictio-
nary:
• PDF-based workflows often embed metadata-bearing artwork as components
within larger documents. Metadata streams provide a standard way of pre-
serving the metadata of these components for examination downstream. PDF-
aware applications should be able to derive a list of all metadata-bearing
document components from the PDF document itself.
• PDF documents are often made available on the Web or in other environments,
where many tools routinely examine, catalog, and classify documents. These
tools should be able to understand the self-contained description of the docu-
ment even if they do not understand PDF.
Besides the usual entries common to all stream dictionaries (see Table 3.4 on
page 62), the metadata stream dictionary contains the additional entries listed in
Table 10.3.
The contents of a metadata stream is the metadata represented in Extensible
Markup Language (XML). This information is visible as plain text to tools that
are not PDF-aware only if the metadata stream is both unfiltered and unencrypt-
ed.
846
CHAPTER 10
Document Interchange
TABLE 10.3 Additional entries in a metadata stream dictionary
KEY
TYPE
VALUE
Type
name
(Required) The type of PDF object that this dictionary describes; must be Metadata
for a metadata stream.
Subtype
name
(Required) The type of metadata stream that this dictionary describes; must be XML.
The format of the XML representing the metadata is defined as part of a frame-
work called the Extensible Metadata Platform (XMP) and described in the Adobe
document XMP: Extensible Metadata Platform (see the Bibliography). This
framework provides a way to use XML to represent metadata describing docu-
ments and their components and is intended to be adopted by a wider class of ap-
plications than just those that process PDF. It includes a method to embed XML
data within non-XML data files in a platform-independent format that can be
easily located and accessed by simple scanning rather than requiring the docu-
ment file to be parsed.
A metadata stream can be attached to a document through the Metadata entry in
the document catalog (see Chapter 3.6.1, “Document Catalog,” and also see
implementation note 161 in Appendix H). In addition, most PDF document
components represented as a stream or dictionary can have a Metadata entry (see
Table 10.4).
TABLE 10.4 Additional entry for components having metadata
KEY
TYPE
VALUE
Metadata
stream
(Optional; PDF 1.4) A metadata stream containing metadata for the component.
In general, a PDF stream or dictionary can have metadata attached to it as long as
the stream or dictionary represents an actual information resource, as opposed to
serving as an implementation artifact. Some PDF constructs are considered im-
plementational, and hence cannot have associated metadata.
For the remaining PDF constructs, there is sometimes ambiguity about exactly
which stream or dictionary should bear the Metadata entry. Such cases are to be
resolved so that the metadata is attached as close as possible to the object that
actually stores the data resource described. For example, metadata describing a
tiling pattern should be attached to the pattern stream’s dictionary, but a shading
should have metadata attached to the shading dictionary rather than to the shad-
847
SECTION 10.3
File Identifiers
ing pattern dictionary that refers to it. Similarly, metadata describing an ICCBased
color space should be attached to the ICC profile stream describing it, and meta-
data for fonts should be attached to font file streams rather than to font dictionar-
ies.
In tables describing document components in this book, the Metadata entry is
listed only for those in which it is most likely to be used. Keep in mind, however,
that this entry may appear in other components represented as streams or dictio-
naries.
In addition, metadata can also be associated with marked content within a con-
tent stream. This association is created by including an entry in the property list
dictionary whose key is Metadata and whose value is the metadata stream dictio-
nary. Because this construct refers to an object outside the content stream, the
property list must be referred to indirectly as a named resource (see Section
10.5.1, “Property Lists”).
10.3
File Identifiers
PDF files may contain references to other PDF files (see Section 3.10, “File Speci-
fications”). Simply storing a file name, however, even in a platform-independent
format, does not guarantee that the file can be found. Even if the file still exists
and its name has not been changed, different server software applications may
identify it in different ways. For example, servers running on DOS platforms must
convert all file names to 8 characters and a 3-character extension. Different serv-
ers may use different strategies for converting longer file names to this format.
External file references can be made more reliable by including a file identifier
(PDF 1.1) in the file and using it in addition to the normal platform-based file
designation. Matching the identifier in the file reference with the one in the file
confirms whether the correct file was found.
File identifiers are defined by the optional ID entry in a PDF file’s trailer dic-
tionary (see Section 3.4.4, “File Trailer”; see also implementation note 162 in
Appendix H). The value of this entry is an array of two byte strings. The first byte
string is a permanent identifier based on the contents of the file at the time it was
originally created and does not change when the file is incrementally updated.
The second byte string is a changing identifier based on the file’s contents at the
time it was last updated. When a file is first written, both identifiers are set to the
848
CHAPTER 10
Document Interchange
same value. If both identifiers match when a file reference is resolved, it is very
likely that the correct file has been found. If only the first identifier matches, a
different version of the correct file has been found.
To help ensure the uniqueness of file identifiers, it is recommend that they be
computed by means of a message digest algorithm such as MD5 (described in In-
ternet RFC 1321, The MD5 Message-Digest Algorithm; see the Bibliography), us-
ing the following information (see implementation note 163 in Appendix H):
• The current time
• A string representation of the file’s location, usually a pathname
• The size of the file in bytes
• The values of all entries in the file’s document information dictionary (see
Section 10.2.1, “Document Information Dictionary”)
10.4
Page-Piece Dictionaries
A page-piece dictionary (PDF 1.3) can be used to hold private application data.
The data can be associated with a page or form XObject by means of the optional
PieceInfo entry in the page object (see Table 3.27 on page 145) or form dictionary
(see Table 4.45 on page 358). Beginning with PDF 1.4, private data may also be
associated with the PDF document by means of the PieceInfo entry in the docu-
ment catalog (see Table 3.25 on page 139).
Applications can use this dictionary as a place to store private data in connection
with that document, page, or form. Such private data can convey information
meaningful to the application that produces it (such as information on object
grouping for a graphics editor or the layer information used by Adobe Photo-
shop®) but is typically ignored by general-purpose PDF viewer applications.
As Table 10.5 shows, a page-piece dictionary may contain any number of entries,
each keyed by the name of a distinct application or of a well-known data type rec-
ognized by a family of applications. The value associated with each key is an ap-
plication data dictionary containing the private data to be used by the application.
The Private entry may have a value of any data type, but typically it is a dictionary
containing all of the private data needed by the application other than the actual
content of the document, page, or form.
849
SECTION 10.4
Page-Piece Dictionaries
TABLE 10.5 Entries in a page-piece dictionary
KEY
TYPE
VALUE
any application name
dictionary
An application data dictionary (see Table 10.6).
or well-known data type
TABLE 10.6 Entries in an application data dictionary
KEY
TYPE
VALUE
LastModified
date
(Required) The date and time when the contents of the document,
page, or form were most recently modified by this application.
Private
(any)
(Optional) Any private data appropriate to the application, typically
in the form of a dictionary.
The LastModified entry indicates when this application last altered the content of
the page or form. If the page-piece dictionary contains several application data
dictionaries, their modification dates can be compared with those in the corre-
sponding entry of the page object or form dictionary (see Table 3.27 on page 145
and Table 4.45 on page 358), or the ModDate entry of the document information
dictionary (see Table 10.2), to ascertain which application data dictionary corre-
sponds to the current content of the page or form. Because some platforms may
use only an approximate value for the date and time or may not deal correctly
with differing time zones, modification dates are compared only for equality and
not for sequential ordering.
Note: It is possible for two or more application data dictionaries to have the same
modification date. Applications can use this capability to define multiple or extend-
ed versions of the same data format. For example, suppose that earlier versions of an
application use an application data dictionary named PictureEdit, and later ver-
sions of the same application extend the data to include additional items not previ-
ously used. The original data could continue to be kept in the PictureEdit dictionary
and the additional items placed in a new dictionary named PictureEditExtended.
This allows the earlier versions of the application to continue to work as before, and
later versions are able to locate and use the extended data items.
850
CHAPTER 10
Document Interchange
10.5
Marked Content
Marked-content operators (PDF 1.2) identify a portion of a PDF content stream as
a marked-content element of interest to a particular application or PDF plug-in
extension. Marked-content elements and the operators that mark them fall into
two categories:
• The MP and DP operators designate a single marked-content point in the con-
tent stream.
• The BMC, BDC, and EMC operators bracket a marked-content sequence of ob-
jects within the content stream. Note that this is a sequence not simply of bytes
in the content stream but of complete graphics objects. Each object is fully
qualified by the parameters of the graphics state in which it is rendered.
A graphics application, for example, might use marked content to identify a set of
related objects as a group to be processed as a single unit. A text-processing
application might use it to maintain a connection between a footnote marker in
the body of a document and the corresponding footnote text at the bottom of the
page. The PDF logical structure facilities use marked-content sequences to asso-
ciate graphical content with structure elements (see Section 10.6.3, “Structure
Content”). Table 10.7 summarizes the marked-content operators.
All marked-content operators except EMC take a tag operand indicating the role
or significance of the marked-content element to the processing application. All
such tags must be registered with Adobe Systems (see Appendix E) to avoid con-
flicts between different applications marking the same content stream. In addi-
tion to the tag operand, the DP and BDC operators specify a property list
containing further information associated with the marked content. Property lists
are discussed further in Section 10.5.1, “Property Lists.”
Marked-content operators may appear only between graphics objects in the con-
tent stream. They may not occur within a graphics object or between a graphics
state operator and its operands. Marked-content sequences may be nested one
within another, but each sequence must be entirely contained within a single con-
tent stream; it may not cross page boundaries, for example.
Note: The Contents entry of a page object (see “Page Objects” on page 144), which
may be either a single stream or an array of streams, is considered a single stream
with respect to marked-content sequences.
851
SECTION 10.5
Marked Content
TABLE 10.7 Marked-content operators
OPERANDS
OPERATOR DESCRIPTION
tag
MP
Designate a marked-content point. tag is a name object indicating the role or
significance of the point.
tag
properties
DP
Designate a marked-content point with an associated property list. tag is a name
object indicating the role or significance of the point. properties is either an in-
line dictionary containing the property list or a name object associated with it in
the Properties subdictionary of the current resource dictionary (see Section
10.5.1, “Property Lists”).
tag
BMC
Begin a marked-content sequence terminated by a balancing EMC operator. tag
is a name object indicating the role or significance of the sequence.
tag
properties
BDC
Begin a marked-content sequence with an associated property list, terminated
by a balancing EMC operator. tag is a name object indicating the role or signifi-
cance of the sequence. properties is either an inline dictionary containing the
property list or a name object associated with it in the Properties subdictionary
of the current resource dictionary (see Section 10.5.1, “Property Lists”).
—
EMC
End a marked-content sequence begun by a BMC or BDC operator.
When the marked-content operators BMC, BDC, and EMC are combined with the
text object operators BT and ET (see Section 5.3, “Text Objects”), each pair of
matching operators (BMC… EMC, BDC… EMC, or BT… ET) must be properly (sep-
arately) nested. Therefore, the sequences
BMC
BT
BT
BMC
…
and
…
ET
EMC
EMC
ET
are valid, but
BMC
BT
BT
BMC
…
and
…
EMC
ET
BT
EMC
are not valid.
852
CHAPTER 10
Document Interchange
10.5.1
Property Lists
The marked-content operators DP and BDC associate a property list with a
marked-content element within a content stream. The property list is a dictionary
containing private information meaningful to the program (application or plug-
in extension) creating the marked content. It is suggested that programs use the
dictionary entries in a consistent way; for example, the values associated with a
given key should always be of the same type (or small set of types).
If all of the values in a property list dictionary are direct objects, the dictionary
may be written inline in the content stream as a direct object. If any of the values
are indirect references to objects outside the content stream, the property list
dictionary must instead be defined as a named resource in the Properties sub-
dictionary of the current resource dictionary (see Section 3.7.2, “Resource Dic-
tionaries”) and referenced by name as the properties operand of the DP or BDC
operator.
10.5.2
Marked Content and Clipping
Some PDF path and text objects are defined purely for their effect on the current
clipping path, without the objects actually being painted on the page. This occurs
when a path object is defined using the operator sequence W n or W* n (see
Section 4.4.3, “Clipping Path Operators”) or when a text object is painted in text
rendering mode 7 (see Section 5.2.5, “Text Rendering Mode”). Such clipped,
unpainted path or text objects are called clipping objects. When a clipping object
falls within a marked-content sequence, it is not considered part of the sequence
unless the entire sequence consists only of clipping objects. In Example 10.2, for
instance, the marked-content sequence tagged Clip includes the text string
( Clip me ) but not the rectangular path that defines the clipping boundary.
Example 10.2
/Clip BMC
100 100 10 10 re W n
% Clipping path
( Clip me ) Tj
% Object to be clipped
EMC
Only when a marked-content sequence consists entirely of clipping objects are
the clipping objects considered part of the sequence. In this case, the sequence is
known as a marked clipping sequence. Such sequences may be nested. In Example
853
SECTION 10.5
Marked Content
10.3, for instance, multiple lines of text are used to clip a subsequent graphics
object (in this case, a filled path). Each line of text is bracketed within a separate
marked clipping sequence, tagged Pgf. The entire series is bracketed in turn by an
outer marked clipping sequence, tagged Clip. Note, however, that the marked-
content sequence tagged ClippedText is not a marked clipping sequence, since it
contains a filled rectangular path that is not a clipping object. The clipping
objects belonging to the Clip and Pgf sequences are therefore not considered part
of the ClippedText sequence.
Example 10.3
/ClippedText BMC
/Clip
<<… >>
BDC
BT
7 Tr
% Begin text clip mode
/Pgf BMC
( Line 1 ) Tj
EMC
/Pgf BMC
( Line ) '
(
2 ) Tj
EMC
ET
% Set current text clip
EMC
100 100 10 10 re f
% Filled path
EMC
The precise rules governing marked clipping sequences are as follows:
• A clipping object is a path object ended by the operator sequence W n or W* n or
a text object painted in text rendering mode 7.
• An invisible graphics object is a path object ended by the operator n only (with
no preceding W or W*) or a text object painted in text rendering mode 3.
• A visible graphics object is a path object ended by any operator other than n, a
text object painted in any text rendering mode other than 3 or 7, or any
XObject invoked by the Do operator.
• An empty marked-content element is a marked-content point or a marked-
content sequence that encloses no graphics objects.
854
CHAPTER 10
Document Interchange
• A marked clipping sequence is a marked-content sequence that contains at least
one clipping object and no visible graphics objects.
• Clipping objects and marked clipping sequences are considered part of an
enclosing marked-content sequence only if it is a marked clipping sequence.
• Invisible graphics objects and empty marked-content elements are always con-
sidered part of an enclosing marked-content sequence, regardless of whether it
is a marked clipping sequence.
• The q (save) and Q (restore) operators may not occur within a marked clipping
sequence.
Example 10.4 illustrates the application of these rules. Marked-content sequence
S4 is a marked clipping sequence because it contains a clipping object (clipping
path 2) and no visible graphics objects. Clipping path 2 is therefore considered
part of sequence S4. Marked-content sequences S1, S2, and S3 are not marked
clipping sequences, since they each include at least one visible graphics object.
Thus, clipping paths 1 and 2 are not part of any of these three sequences.
Example 10.4
/S1 BMC
/S2 BMC
/S3 BMC
0 0 m
100 100 l
0 100 l W n
% Clipping path 1
0 0 m
200 200 l
0 100 l f
% Filled path
EMC
/S4 BMC
0 0 m
300 300 l
0 100 l W n
% Clipping path 2
EMC
EMC
100 100 10 10 re f
% Filled path
EMC
In Example 10.5, marked-content sequence S1 is a marked clipping sequence
because the only graphics object it contains is a clipping path. Thus, the empty
855
SECTION 10.6
Logical Structure
marked-content sequence S3 and the marked-content point P1 are both part of
sequence S2, and S2, S3, and P1 are all part of sequence S1.
Example 10.5
/S1 BMC
… Clipping path…
/S2 BMC
/S3 BMC
EMC
/P1 DP
EMC
EMC
In Example 10.6, marked-content sequences S1 and S4 are marked clipping
sequences because the only object they contain is a clipping path. Hence the
clipping path is part of sequences S1 and S4; S3 is part of S2; and S2, S3, and S4 are
all part of S1.
Example 10.6
/S1 BMC
/S2 BMC
/S3 BMC
EMC
EMC
/S4 BMC
… Clipping path…
EMC
EMC
10.6
Logical Structure
PDF’s logical structure facilities (PDF 1.3) provide a mechanism for incorporating
structural information about a document’s content into a PDF file. Such in-
formation might include, for example, the organization of the document into
chapters and sections or the identification of special elements such as figures,
tables, and footnotes. The logical structure facilities are extensible, allowing
applications that produce PDF files to choose what structural information to
include and how to represent it, while enabling PDF consumers to navigate a file
without knowing the producer’s structural conventions.
856
CHAPTER 10
Document Interchange
PDF logical structure shares basic features with standard document markup
languages such as HTML, SGML, and XML. A document’s logical structure is
expressed as a hierarchy of structure elements, each represented by a dictionary
object. Like their counterparts in other markup languages, PDF structure
elements can have content and attributes. In PDF, rendered document content
takes over the role occupied by text in HTML, SGML, and XML.
A PDF document’s logical structure is stored separately from its visible content,
with pointers from each to the other. This separation allows the ordering and
nesting of logical elements to be entirely independent of the order and location of
graphics objects on the document’s pages.
The MarkInfo entry in the document catalog (see Section 3.6.1, “Document Cata-
log”) specifies a mark information dictionary, whose entries are shown in
Table 10.8. It provides additional information relevant to specialized uses of
structured PDF documents.
TABLE 10.8 Entries in the mark information dictionary
KEY
TYPE
VALUE
Marked
boolean
(Optional) A flag indicating whether the document conforms to Tagged PDF
conventions. Default value: false.
Note: If Suspects is true, the document may not completely conform to Tagged PDF
conventions.
UserProperties boolean
(Optional; PDF 1.6) A flag indicating the presence of structure elements that
contain user properties attributes (see “User Properties” on page 876). Default
value: false.
Suspects
boolean
(Optional; PDF 1.6) A flag indicating the presence of tag suspects (see “Page
Content Order” on page 889). Default value: false.
10.6.1
Structure Hierarchy
The logical structure of a document is described by a hierarchy of objects called
the structure hierarchy or structure tree. At the root of the hierarchy is a dictionary
object called the structure tree root, located by means of the StructTreeRoot entry
in the document catalog (see Section 3.6.1, “Document Catalog”). Table 10.9
shows the entries in the structure tree root dictionary. The K entry specifies the
immediate children of the structure tree root, which are structure elements.
857
SECTION 10.6
Logical Structure
Structure elements are represented by a dictionary, whose entries are shown in
Table 10.10. The K entry specifies the children of the structure element, which
can be zero or more items of the following kinds:
• Other structure elements
• References to content items, which are either marked-content sequences (see
Section 10.5, “Marked Content”) or complete PDF objects such as XObjects
and annotations. These content items represent the graphical content, if any,
associated with a structure element. Content items are discussed in detail in
Section 10.6.3, “Structure Content.”
TABLE 10.9 Entries in the structure tree root
KEY
TYPE
VALUE
Type
name
(Required) The type of PDF object that this dictionary describes; must be
StructTreeRoot for a structure tree root.
K
dictionary
(Optional) The immediate child or children of the structure tree root in the
or array
structure hierarchy. The value may be either a dictionary representing a sin-
gle structure element or an array of such dictionaries.
IDTree
name tree
(Required if any structure elements have element identifiers) A name tree that
maps element identifiers (see Table 10.10) to the structure elements they
denote.
ParentTree
number tree
(Required if any structure element contains content items) A number tree
(see Section 3.8.6, “Number Trees”) used in finding the structure elements
to which content items belong. Each integer key in the number tree corre-
sponds to a single page of the document or to an individual object (such as
an annotation or an XObject) that is a content item in its own right. The in-
teger key is given as the value of the StructParent or StructParents entry in
that object (see “Finding Structure Elements from Content Items” on page
868). The form of the associated value depends on the nature of the object:
• For an object that is a content item in its own right, the value is an indi-
rect reference to the object’s parent element (the structure element that
contains it as a content item).
• For a page object or content stream containing marked-content
sequences that are content items, the value is an array of references to the
parent elements of those marked-content sequences.
See “Finding Structure Elements from Content Items” on page 868 for fur-
ther discussion.
858
CHAPTER 10
Document Interchange
KEY
TYPE
VALUE
ParentTreeNextKey integer
(Optional) An integer greater than any key in the parent tree, to be used as a
key for the next entry added to the tree.
RoleMap
dictionary
(Optional) A dictionary that maps the names of structure types used in the
document to their approximate equivalents in the set of standard structure
types (see Section 10.7.3, “Standard Structure Types”).
ClassMap
dictionary
(Optional) A dictionary that maps name objects designating attribute class-
es to the corresponding attribute objects or arrays of attribute objects (see
“Attribute Classes” on page 873).
TABLE 10.10 Entries in a structure element dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if
present, must be StructElem for a structure element.
S
name
(Required) The structure type, a name object identifying the nature of the
structure element and its role within the document, such as a chapter,
paragraph, or footnote (see Section 10.6.2, “Structure Types”). Names of
structure types must conform to the guidelines described in Appendix E.
P
dictionary
(Required; must be an indirect reference) The structure element that is the
immediate parent of this one in the structure hierarchy.
ID
byte string
(Optional) The element identifier, a byte string designating this structure
element. The string must be unique among all elements in the docu-
ment’s structure hierarchy. The IDTree entry in the structure tree root
(see Table 10.9) defines the correspondence between element identifiers
and the structure elements they denote.
Pg
dictionary
(Optional; must be an indirect reference) A page object representing a
page on which some or all of the content items designated by the K entry
are rendered.
859
SECTION 10.6
Logical Structure
KEY
TYPE
VALUE
K
(various)
(Optional) The children of this structure element. The value of this entry
may be one of the following objects or an array consisting of one or more
of the following objects:
• A structure element dictionary denoting another structure element
• An integer marked-content identifier denoting a marked-content
sequence
• A marked-content reference dictionary denoting a marked-content
sequence
• An object reference dictionary denoting a PDF object
Each of these objects other than the first (structure element dictionary)
is considered to be a content item; see Section 10.6.3, “Structure Con-
tent” for further discussion of each of these forms of representation.
Note: If the value of K is a dictionary containing no Type entry, it is as-
sumed to be a structure element dictionary.
A
(various)
(Optional) A single attribute object or array of attribute objects associat-
ed with this structure element. Each attribute object is either a dictio-
nary or a stream. If the value of this entry is an array, each attribute
object in the array may be followed by an integer representing its revi-
sion number (see Section 10.6.4, “Structure Attributes,” and “Attribute
Revision Numbers” on page 874).
C
name or array
(Optional) An attribute class name or array of class names associated
with this structure element. If the value of this entry is an array, each
class name in the array may be followed by an integer representing its re-
vision number (see “Attribute Classes” on page 873 and “Attribute Revi-
sion Numbers” on page 874).
Note: If both the A and C entries are present and a given attribute is speci-
fied by both, the one specified by the A entry takes precedence.
R
integer
(Optional) The current revision number of this structure element (see
“Attribute Revision Numbers” on page 874). The value must be a non-
negative integer. Default value: 0.
T
text string
(Optional) The title of the structure element, a text string representing it
in human-readable form. The title should characterize the specific struc-
ture element, such as Chapter 1, rather than merely a generic element
type, such as Chapter.
860
CHAPTER 10
Document Interchange
KEY
TYPE
VALUE
Lang
text string
(Optional; PDF 1.4) A language identifier specifying the natural language
for all text in the structure element except where overridden by language
specifications for nested structure elements or marked content (see Sec-
tion 10.8.1, “Natural Language Specification”). If this entry is absent, the
language (if any) specified in the document catalog applies.
Alt
text string
(Optional) An alternate description of the structure element and its
children in human-readable form, which is useful when extracting the
document’s contents in support of accessibility to users with disabilities
or for other purposes (see Section 10.8.2, “Alternate Descriptions”).
E
text string
(Optional; PDF 1.5) The expanded form of an abbreviation.
ActualText
text string
(Optional; PDF 1.4) Text that is an exact replacement for the structure
element and its children. This replacement text (which should apply to
as small a piece of content as possible) is useful when extracting the doc-
ument’s contents in support of accessibility to users with disabilities or
for other purposes (see Section 10.8.3, “Replacement Text”).
10.6.2
Structure Types
Every structure element has a structure type, a name object that identifies the
nature of the structure element and its role within the document (such as a chap-
ter, paragraph, or footnote). To facilitate the interchange of content among PDF
applications, Adobe has defined a set of standard structure types; see Section
10.7.3, “Standard Structure Types.” Applications are not required to adopt them,
however, and may use any names for their structure types.
Where names other than the standard ones are used, a role map may be provided
in the structure tree root, mapping the structure types used in the document to
their nearest equivalents in the standard set. For example, a structure type named
Section used in the document might be mapped to the standard type Sect. The
equivalence need not be exact; the role map merely indicates an approximate
analogy between types, allowing applications other than the one creating a docu-
ment to handle its nonstandard structure elements in a reasonable way.
Note: The same structure type may occur as both a key and a value in the role map,
and circular chains of association are explicitly permitted. A single role map can
thus define a bidirectional mapping. An application using the role map should fol-
861
SECTION 10.6
Logical Structure
low the chain of associations until it either finds a structure type it recognizes or re-
turns to one it has already encountered.
Note: In PDF versions earlier than
1.5, standard element types were never
remapped. Beginning with PDF 1.5, an element name is always mapped to its corre-
sponding name in the role map, if there is one, even if the original name is one of the
standard types. This is done to allow the element, for example, to represent a tag
with the same name as a standard role, even though its use differs from the standard
role.
10.6.3
Structure Content
Any structure element may have associated graphical content, consisting of one
or more content items. Content items are graphical objects that exist in the docu-
ment independently of the structure tree but are associated with structure ele-
ments as described in the following sections. Content items are of two kinds:
• Marked-content sequences within content streams (see “Marked-Content Se-
quences as Content Items”)
• Complete PDF objects such as annotations and XObjects (see “PDF Objects as
Content Items”)
The K entry in a structure element dictionary (see Table 10.10) specifies the chil-
dren of the structure element, which can include any number of content items, as
well as child structure elements that may in turn have content items of their own.
Conceptually, content items must be leaf nodes of the structure tree; that is, they
cannot have other content items nested within them for purposes of logical struc-
ture. The hierarchical relationship among structure elements is represented en-
tirely by the K entries of the structure element dictionaries, not by nesting of the
associated content items. Therefore, the following restrictions apply:
• A marked-content sequence delimiting a structure content item may not have
another marked-content sequence for a content item nested within it (though
non-structural marked content is allowed).
• A structure content item may not invoke (with the Do operator) an XObject
that is itself a structure content item.
862
CHAPTER 10
Document Interchange
Marked-Content Sequences as Content Items
A sequence of graphics operators in a content stream can be specified as a con-
tent item of a structure element in the following way:
• The operators must be bracketed as a marked-content sequence between BDC
and EMC operators (see Section 10.5, “Marked Content”)
Note: Although the tag associated with a marked-content sequence is not directly
related to the document’s logical structure, it should be the same as the structure
type of the associated structure element.
• The marked-content sequence must have a property list (see Section 10.5.1,
“Property Lists”) containing an MCID entry, which is an integer marked-content
identifier that uniquely identifies the marked-content sequence within its con-
tent stream, as shown in the following example:
Example 10.7
2 0 obj
% Page object
<< /Type /Page
/Contents 3 0 R
% Content stream
…
>>
endobj
3 0 obj
% Page's content stream
<< /Length … >>
stream
…
/P << /MCID 0 >>
% Start of marked-content sequence
BDC
…
( Here is some text ) Tj
…
EMC
% End of marked-content sequence
…
endstream
endobj
Note: This example and the following examples omit required StructParents entries
in the objects used as content items (see “Finding Structure Elements from Content
Items” on page 868).
863
SECTION 10.6
Logical Structure
A structure element dictionary can include one or more marked-content se-
quences as content items by referring to them in its K entry (see Table 10.10). This
reference can have two forms:
• A dictionary object called a marked-content reference. Table 10.11 shows the
contents of this type of dictionary, which specifies the marked-content identifi-
er, as well other information identifying the stream in which the sequence is
contained. Example 10.8 illustrates the use of a marked-content reference to the
marked-content sequence shown in Example 10.7.
• An integer that specifies the marked-content identifier. This can be done in the
common case where the marked-content sequence is contained in the content
stream of the page that is specified in the Pg entry of the structure element dic-
tionary. Example 10.9 shows a structure element that has three children: a
marked-content sequence specified by a marked-content identifier, as well as
two other structure elements.
Example 10.8
1 0 obj
% Structure element
<< /Type /StructElem
/S /P
% Structure type
/P …
% Parent in structure hierarchy
/K << /Type /MCR
/Pg 2 0 R
% Page containing marked-content sequence
/MCID 0
% Marked-content identifier
>>
>>
endobj
TABLE 10.11 Entries in a marked-content reference dictionary
KEY
TYPE
VALUE
Type
name
(Required) The type of PDF object that this dictionary describes; must be MCR
for a marked-content reference.
Pg
dictionary
(Optional; must be an indirect reference) The page object representing the page
on which the graphics objects in the marked-content sequence are rendered.
This entry overrides any Pg entry in the structure element containing the
marked-content reference; it is required if the structure element has no such en-
try.
864
CHAPTER 10
Document Interchange
KEY
TYPE
VALUE
Stm
stream
(Optional; must be an indirect reference) The content stream containing the
marked-content sequence. This entry should be present only if the marked-con-
tent sequence resides in a content stream other than the content stream for the
page—for example, in a form XObject (see Section 4.9, “Form XObjects”) or an
annotation’s appearance stream (Section 8.4.4, “Appearance Streams”). If this en-
try is absent, the marked-content sequence is contained in the content stream of
the page identified by Pg (either in the marked-content reference dictionary or
in the parent structure element).
StmOwn
(any)
(Optional; must be an indirect reference) The PDF object owning the stream
identified by Stm—for example, the annotation to which an appearance stream
belongs.
MCID
integer
(Required) The marked-content identifier of the marked-content sequence with-
in its content stream.
Example 10.9
1 0 obj
% Containing structure element
<< /Type /StructElem
/S /MixedContainer
% Structure type
/P …
% Parent in structure hierarchy
/Pg 2 0 R
% Page containing marked-content sequence
/K [
4 0 R
% Three children: a structure element
0
% a marked-content identifier
5 0 R
% another structure element
]
>>
endobj
2 0 obj
% Page object
<< /Type /Page
/Contents 3 0 R
% Content stream
…
>>
endobj
865
SECTION 10.6
Logical Structure
3 0 obj
% Page's content stream
<< /Length … >>
stream
…
/P << /MCID 0 >>
% Start of marked-content sequence
BDC
( Here is some text ) Tj
…
EMC
% End of marked-content sequence
…
endstream
endobj
Content streams other than page contents can also contain marked content se-
quences that are content items of structure elements. The content of form XOb-
jects can be incorporated into structure elements in one of the following ways:
• A Do operator that paints a form XObject can be part of a marked-content se-
quence that is associated with a structure element (see Example 10.10). In this
case, the entire form XObject is considered to be part of the structure element’s
content, as if it were inserted into the marked-content sequence at the point of
the Do operator. The form XObject cannot in turn contain any marked-content
sequences associated with this or other structure elements.
• The content stream of a form XObject can contain one or more marked-con-
tent sequences that are associated with structure elements (see Example 10.11).
The form XObject can have arbitrary substructure, containing any number of
marked-content sequences associated with logical structure elements. Howev-
er, any Do operator that paints the form XObject should not be part of a logical
structure content item.
Note: A form XObject that is painted with multiple invocations of the Do operator
can be incorporated into the document’s logical structure only by the first method,
with each invocation of Do individually associated with a structure element.
866
CHAPTER 10
Document Interchange
Example 10.10
1 0 obj
% Structure element
<< /Type /StructElem
/S /P
% Structure type
/P …
% Parent in structure hierarchy
/Pg 2 0 R
% Page containing marked-content sequence
/K 0
% Marked-content identifier
>>
endobj
2 0 obj
% Page object
<< /Type /Page
/Resources
<< /XObject << /Fm4 4 0 R >>
% Resource dictionary
>>
% containing form XObject
/Contents 3 0 R
% Content stream
…
>>
endobj
3 0 obj
% Page's content stream
<< /Length … >>
stream
…
/P << /MCID 0 >>
% Start of marked-content sequence
BDC
/Fm4 Do
% Paint form XObject
EMC
% End of marked-content sequence
…
endstream
endobj
4 0 obj
% Form XObject
<< /Type /XObject
/Subtype /Form
/Length …
>>
stream
…
( Here is some text ) Tj
…
endstream
endobj
867
SECTION 10.6
Logical Structure
Example 10.11
1 0 obj
% Structure element
<< /Type /StructElem
/S /P
% Structure type
/P …
% Parent in structure hierarchy
/K << /Type /MCR
/Pg 2 0 R
% Page containing marked-content sequence
/Stm 4 0 R
% Stream containing marked-content sequence
/MCID 0
% Marked-content identifier
>>
>>
endobj
2 0 obj
% Page object
<< /Type /Page
/Resources
<< /XObject << /Fm4 4 0 R >>
% Resource dictionary
>>
% containing form XObject
/Contents 3 0 R
% Content stream
…
>>
endobj
3 0 obj
% Page's content stream
<< /Length … >>
stream
…
/Fm4 Do
% Paint form XObject
…
endstream
endobj
4 0 obj
% Form XObject
<< /Type /XObject
/Subtype /Form
/Length …
>>
stream
…
/P << /MCID 0 >>
% Start of marked-content sequence
BDC
…
( Here is some text )
Tj
…
868
CHAPTER 10
Document Interchange
EMC
% End of marked-content sequence
…
endstream
endobj
PDF Objects as Content Items
When a structure element’s content includes an entire PDF object, such as an
XObject or an annotation, that is associated with a page but not directly included
in the page’s content stream, the object is identified in the structure element’s K
entry by an object reference dictionary (see Table 10.12). Note that this form of
reference is used only for entire objects. If the referenced content forms only part
of the object’s content stream, it is instead handled as a marked-content sequence,
as described in the preceding section.
TABLE 10.12 Entries in an object reference dictionary
KEY
TYPE
VALUE
Type
name
(Required) The type of PDF object that this dictionary describes; must be OBJR for an
object reference.
Pg
dictionary
(Optional; must be an indirect reference) The page object representing the page on
which the object is rendered. This entry overrides any Pg entry in the structure ele-
ment containing the object reference; it is required if the structure element has no such
entry.
Obj
(any)
(Required; must be an indirect reference) The referenced object.
Note: If the referenced object is rendered on multiple pages, each rendering requires
a separate object reference. However, if it is rendered multiple times on the same
page, just a single object reference suffices to identify all of them. (If it is important
to distinguish between multiple renditions of the same XObject on the same page,
they should be accessed by means of marked-content sequences enclosing particular
invocations of the Do operator rather than through object references.)
Finding Structure Elements from Content Items
Because a stream cannot contain object references, there is no way for content
items that are marked-content sequences to refer directly back to their parent
structure elements (the ones to which they belong as content items). Instead, a
869
SECTION 10.6
Logical Structure
different mechanism, the structural parent tree, is provided for this purpose. For
consistency, content items that are entire PDF objects, such as XObjects, also use
the parent tree to refer to their parent structure elements.
The parent tree is a number tree (see Section 3.8.6, “Number Trees”), accessed
from the ParentTree entry in a document’s structure tree root (Table 10.9 on page
857). The tree contains an entry for each object that is a content item of at least
one structure element and for each content stream containing at least one
marked-content sequence that is a content item. The key for each entry is an inte-
ger given as the value of the StructParent or StructParents entry in the object (see
below). The values of these entries are as follows:
• For an object identified as a content item by means of an object reference (see
“PDF Objects as Content Items” on page 868), the value is an indirect reference
to the parent structure element.
• For a content stream containing marked-content sequences that are content
items, the value is an array of indirect references to the sequences’ parent struc-
ture elements. The array element corresponding to each sequence is found by
using the sequence’s marked-content identifier as a zero-based index into the
array.
Note: Because marked-content identifiers serve as indices into an array in the struc-
tural parent tree, their assigned values should be as small as possible to conserve
space in the array.
The ParentTreeNextKey entry in the structure tree root holds an integer value
greater than any that is currently in use as a key in the structural parent tree.
Whenever a new entry is added to the parent tree, it uses the current value of
ParentTreeNextKey as its key. The value is then incremented to prepare for the
next new entry to be added.
To locate the relevant parent tree entry, each object or content stream that is rep-
resented in the tree must contain a special dictionary entry, StructParent or
StructParents (see Table 10.13). Depending on the type of content item, this entry
may appear in the page object of a page containing marked-content sequences, in
the stream dictionary of a form or image XObject, in an annotation dictionary, or
in any other type of object dictionary that is included as a content item in a struc-
ture element. Its value is the integer key under which the entry corresponding to
the object is to be found in the structural parent tree.
870
CHAPTER 10
Document Interchange
TABLE 10.13 Additional dictionary entries for structure element access
KEY
TYPE
VALUE
StructParent
integer
(Required for all objects that are structural content items; PDF 1.3) The integer
key of this object’s entry in the structural parent tree.
StructParents
integer
(Required for all content streams containing marked-content sequences that are
structural content items; PDF 1.3) The integer key of this object’s entry in the
structural parent tree.
Note: At most one of these two entries may be present in a given object. An object
can be either a content item in its entirety or a container for marked-content
sequences that are content items, but not both.
For a content item identified by an object reference, the parent structure element
can thus be found by using the value of the StructParent entry in the item’s object
dictionary as a retrieval key in the structural parent tree (found in the ParentTree
entry of the structure tree root). The corresponding value retrieved from the
parent tree is a reference to the parent structure element (see Example 10.12).
Example 10.12
1 0 obj
% Parent structure element
<< /Type /StructElem
…
/K << /Type /OBJR
% Object reference
/Pg 2 0 R
% Page containing form XObject
/Obj 4 0 R
% Reference to form XObject
>>
>>
endobj
2 0 obj
% Page object
<< /Type /Page
/Resources
<< /XObject << /Fm4 4 0 R >>
% Resource dictionary
>>
% containing form XObject
/Contents 3 0 R
% Content stream
…
>>
endobj
871
SECTION 10.6
Logical Structure
3 0 obj
% Page's content stream
<< /Length … >>
stream
…
/Fm4 Do
% Paint form XObject
…
endstream
endobj
4 0 obj
% Form XObject
<< /Type /XObject
/Subtype /Form
/Length …
/StructParent 6
% Parent tree key
>>
stream
…
endstream
endobj
100 0 obj
% Parent tree (accessed from structure tree root)
<< /Nums [ 0 101 0 R
1 102 0 R
…
6 1 0 R
% Entry for page object 2; points back
…
% to parent structure element
]
>>
endobj
For a content item that is a marked-content sequence, the retrieval method is
similar but slightly more complicated. Because a marked-content sequence is not
an object in its own right, its parent tree key is found in the StructParents entry of
the page object or other content stream in which the sequence resides. The value
retrieved from the parent tree is not a reference to the parent structure element
itself but to an array of such references—one for each marked-content sequence
contained within that content stream. The parent structure element for the given
sequence is found by using the sequence’s marked-content identifier as an index
into this array (see Example 10.13).
872
CHAPTER 10
Document Interchange
Example 10.13
1 0 obj
% Parent structure element
<< /Type /StructElem
…
/Pg 2 0 R
% Page containing marked-content sequence
/K 0
% Marked-content identifier
>>
endobj
2 0 obj
% Page object
<< /Type /Page
/Contents 3 0 R
% Content stream
/StructParents 6
% Parent tree key
…
>>
endobj
3 0 obj
% Page's content stream
<< /Length … >>
stream
…
/P << /MCID 0 >>
% Start of marked-content sequence
BDC
( Here is some text )
TJ
…
EMC
% End of marked-content sequence
…
endstream
endobj
100 0 obj
% Parent tree (accessed from structure tree root)
<< /Nums [ 0 101 0 R
1 102 0 R
…
6 [ 1 0 R ]
% Entry for page object 2; array element at index 0
…
% points back to parent structure element
]
>>
endobj
873
SECTION 10.6
Logical Structure
10.6.4
Structure Attributes
An application or plug-in extension that processes logical structure can attach ad-
ditional information, called attributes, to any structure element. The attribute in-
formation is held in one or more attribute objects associated with the structure
element. An attribute object is a dictionary or stream that includes an O entry
(see Table 10.14) identifying the application or plug-in that owns the attribute
information. Other entries represent the attributes: the keys are attribute names,
and values are the corresponding attribute values. To facilitate the interchange of
content among PDF applications, Adobe has defined a set of standard structure
attributes identified by specific standard owners; see Section 10.7.4, “Standard
Structure Attributes.” In addition, PDF 1.6 introduces a use of attributes to repre-
sent user properties (see “User Properties” on page 876).
TABLE 10.14 Entry common to all attribute object dictionaries
KEY
TYPE
VALUE
O
name
(Required) The name of the application or plug-in extension owning the attribute data.
The name must conform to the guidelines described in Appendix E.
Any application can attach attributes to any structure element, even one created
by another application. Multiple applications can attach attributes to the same
structure element. The A entry in the structure element dictionary (see Table
10.10 on page 858) can hold either a single attribute object or an array of such
objects, together with revision numbers for coordinating attributes created by dif-
ferent owners (see “Attribute Revision Numbers” on page 874). An application
creating or destroying the second attribute object for a structure element is re-
sponsible for converting the value of the A entry from a single object to an array
or vice versa, as well as for maintaining the integrity of the revision numbers. No
inherent order is defined for the attribute objects in an A array, but it is consid-
ered good practice to add new objects at the end of the array so that the first ar-
ray element is the one belonging to the application that originally created the
structure element.
Attribute Classes
If many structure elements share the same set of attribute values, they can be
defined as an attribute class sharing the identical attribute object. Structure
elements refer to the class by name. The association between class names and
874
CHAPTER 10
Document Interchange
attribute objects is defined by a dictionary called the class map, kept in the
ClassMap entry of the structure tree root (see Table 10.9 on page 857). Each key
in the class map is a name object denoting the name of a class. The corresponding
value is an attribute object or an array of such objects.
Note: PDF attribute classes are unrelated to the concept of a class in object-oriented
programming languages such as Java and C++. Attribute classes are strictly a mech-
anism for storing attribute information in a more compact form; they have no in-
heritance properties like those of true object-oriented classes.
The C entry in a structure element dictionary (see Table 10.10 on page 858) con-
tains a class name or an array of class names (typically accompanied by revision
numbers as well; see “Attribute Revision Numbers,” below). For each class named
in the C entry, the corresponding attribute object or objects are considered to be
attached to the given structure element, along with those identified in the
element’s A entry. If both the A and C entries are present and a given attribute is
specified by both, the one specified by the A entry takes precedence.
Attribute Revision Numbers
When an application modifies a structure element or its contents, the change may
affect the validity of attribute information attached to that structure element by
other applications. A system of revision numbers allows applications to detect
such changes and update their own attribute information accordingly, as de-
scribed in this section.
A structure element has a revision number, stored in the R entry in the structure
element dictionary (see Table 10.10 on page 858). Initially, the revision number is
0 (the default value if no R entry is present). When an application modifies the
structure element or any of its content items, it may signal the change by
incrementing the revision number.
Note: The revision number is unrelated to the generation number associated with
an indirect object (see Section 3.2.9, “Indirect Objects”).
875
SECTION 10.6
Logical Structure
Each attribute object attached to a structure element may have an associated revi-
sion number. The revision number is stored in the array that associates the
attribute object with the structure element:
• Each attribute object in a structure element’s A array is represented by a pair of
array elements, the first containing the attribute object itself and the second
containing the integer revision number associated with it in this structure
element.
• The structure element’s C array contains a pair of elements for each attribute
class, the first containing the class name and the second containing the associ-
ated revision number.
The revision numbers are optional in both the A and C arrays. An attribute object
or class name that is not followed by an integer array element is understood to
have a revision number of 0.
Note: The revision number is not stored directly in the attribute object because a
single attribute object may be associated with more than one structure element
(whose revision numbers may differ).
When an attribute object is created or modified, its revision number is set to the
current value of the structure element’s R entry. By comparing the attribute ob-
ject’s revision number with that of the structure element, an application can de-
termine whether the contents of the attribute object are still current or whether
they have been outdated by more recent changes in the underlying structure ele-
ment.
Note: Changes in an attribute object do not change the revision number of the asso-
ciated structure element, which changes only when the structure element itself or
any of its content items is modified.
Occasionally, an application may make extensive changes to a structure element
that are likely to invalidate all previous attribute information associated with it. In
this case, instead of incrementing the structure element’s revision number, the ap-
plication may choose to delete all unknown attribute objects from its A and C ar-
rays. These two actions are mutually exclusive: the application should either
increment the structure element’s revision number or remove its attribute objects,
but not both. Note that any application creating attribute objects must be pre-
pared for the possibility that they may be deleted at any time by another applica-
tion.
876
CHAPTER 10
Document Interchange
User Properties
Most structure attributes (see Section 10.7.4, “Standard Structure Attributes”)
specify information that is reflected in the element’s appearance; for example,
BackgroundColor or BorderStyle. However, some PDF producers, such as CAD
applications, may use objects that have a standardized appearance, each of which
contains non-graphical information that distinguishes the objects from one an-
other. For example, several transistors might have the same appearance but dif-
ferent attributes such as type and part number.
User properties (PDF 1.6) can be used to contain such information. Any graphical
object that corresponds to a structure element may have associated user proper-
ties, specified by means of an attribute object dictionary with a value of
UserProperties for the O entry (see Table 10.15).
TABLE 10.15 Additional entries in an attribute object dictionary for user properties
KEY
TYPE
VALUE
O
name
(Required) The attribute owner. Must be UserProperties.
P
array
(Required) An array of dictionaries, each of which represents a user property (see
Table 10.16).
The P entry is an array specifying the user properties. Each element in the array is
a user property dictionary representing an individual property (see Table 10.16).
The order of the array elements is significant, allowing producers to specify at-
tributes in order of importance.
TABLE 10.16 Entries in a user property dictionary
KEY
TYPE
VALUE
N
text
(Required) The name of the user property.
V
any
(Required) The value of the user property.
Note: While the value of this entry is allowed to be any type of PDF object, PDF producers
are strongly encouraged to use only text string, number, and boolean values. PDF consumers
are not required to display values of other types to users; however, they should tolerate other
values and not treat them as errors.
F
text string
(Optional) A formatted representation of the value of V, used when special formatting is
required; for example “($123.45)” for the number -123.45. If this entry is absent, applica-
tions should use a default format.
877
SECTION 10.6
Logical Structure
KEY
TYPE
VALUE
H
boolean
(Optional) If true, the attribute is hidden; that is, it should not be shown in any user inter-
face element that presents the attributes of an object. Default value: false.
PDF documents that contain user properties must provide a UserProperties entry
with a value of true in the document’s mark information dictionary
(see
Table 10.8). This entry allows consumer applications to quickly determine
whether it is necessary to search the structure tree for elements containing user
properties.
Example 10.14 shows a structure element containing user properties called Part
Name, Part Number, Supplier, and Price.
Example 10.14
100 0 obj
<< /Type /StructElem
/S /Figure
% Structure type
/P 50 0 R
% Parent in structure tree
/A << /O /UserProperties
% Attribute object
/P [
% Array of user properties
<< /N (Part Name) /V (Framostat) >>
<< /N (Part Number) /V 11603 >>
<< /N (Supplier) /V (Just Framostats) /H true >>
% Hidden attribute
<< /N (Price) /V -37.99 /F ($37.99) >>
% Formatted value
]
>>
>>
endobj
10.6.5
Example of Logical Structure
Example 10.15 shows portions of a PDF file with a simple document structure.
The structure tree root (object 300) contains elements with structure types Chap
(object 301) and Para (object 304). The Chap element, titled Chapter 1, contains
elements with types Head1 (object 302) and Para (object 303).
These elements are mapped to the standard structure types specified in Tagged
PDF (see Section 10.7.3, “Standard Structure Types”) by means of the role map
specified in the structure tree root. Objects 302 through 304 have attached at-
tributes (see Section 10.6.4, “Structure Attributes”and Section 10.7.4, “Standard
Structure Attributes”).
878
CHAPTER 10
Document Interchange
The example also illustrates the structure of a parent tree (object 400) that maps
content items back to their parent structure elements and an ID tree (object 403)
that maps element identifiers to the structure elements they denote.
Example 10.15
1 0 obj
% Document catalog
<< /Type /Catalog
/Pages 100 0 R
% Page tree
/StructTreeRoot 300 0 R
% Structure tree root
>>
endobj
100 0 obj
% Page tree
<< /Type /Pages
/Kids [
101 1 R
% First page object
102 0 R
% Second page object
]
/Count 2
% Page count
>>
endobj
101 1 obj
% First page object
<< /Type /Page
/Parent 100 0 R
% Parent is the page tree
/Resources
<< /Font
<< /F1 6 0 R
% Font resources
/F12 7 0 R
>>
/ProcSet [ /PDF /Text ] % Procedure sets
>>
/MediaBox [ 0 0 612 792 ]
% Media box
/Contents 201 0 R
% Content stream
/StructParents 0
% Parent tree key
>>
endobj
201 0 obj
% Content stream for first page
<< /Length … >>
stream
1 1 1 rg
0 0 612 792 re f
BT
% Start of text object
879
SECTION 10.6
Logical Structure
/Head1 << /MCID 0 >>
% Start of marked-content sequence 0
BDC
0 0 0 rg
/F1 1 Tf
30 0 0 30 18 732 Tm
( This is a first level heading . Hello world : ) Tj
1.1333 TL
T*
( goodbye universe . ) Tj
EMC
% End of marked-content sequence 0
/Para << /MCID 1 >>
% Start of marked-content sequence 1
BDC
/F12 1 Tf
14 0 0 14 18 660.8 Tm
( This is the first paragraph, which spans pages . It has four fairly short and \
concise sentences . This is the next to last ) Tj
EMC
% End of marked-content sequence 1
ET
% End of text object
endstream
endobj
102 0 obj
% Second page object
<< /Type /Page
/Parent 100 0 R
% Parent is the page tree
/Resources
<< /Font
<< /F1 6 0 R
% Font resources
/F12 7 0 R
>>
/ProcSet [ /PDF /Text ] % Procedure sets
>>
/MediaBox [ 0 0 612 792 ]
% Media box
/Contents 202 0 R
% Content stream
/StructParents 1
% Parent tree key
>>
endobj
202 0 obj
% Content stream for second page
<< /Length … >>
stream
1 1 1 rg
0 0 612 792 re f
BT
% Start of text object
880
CHAPTER 10
Document Interchange
/Para << /MCID 0 >>
% Start of marked-content sequence 0
BDC
0 0 0 rg
/F12 1 Tf
14 0 0 14 18 732 Tm
( sentence . This is the very last sentence of the first paragraph . ) Tj
EMC
% End of marked-content sequence 0
/Para << /MCID 1 >>
% Start of marked-content sequence 1
BDC
/F12 1 Tf
14 0 0 14 18 570.8 Tm
( This is the second paragraph . It has four fairly short and concise sentences . \
This is the next to last ) Tj
EMC
% End of marked-content sequence 1
/Para << /MCID 2 >>
% Start of marked-content sequence 2
BDC
1.1429 TL
T*
( sentence . This is the very last sentence of the second paragraph . ) Tj
EMC
% End of marked-content sequence 2
ET
% End of text object
endstream
endobj
300 0 obj
% Structure tree root
<< /Type /StructTreeRoot
/K [
301 0 R
% Two children: a chapter
304 0 R
% and a paragraph
]
/RoleMap << /Chap /Sect
% Mapping to standard structure types
/Head1 /H
/Para /P
>>
/ClassMap
<< /Normal 305 0 R >>
% Class map containing one attribute class
/ParentTree 400 0 R
% Number tree for parent elements
/ParentTreeNextKey 2
% Next key to use in parent tree
/IDTree 403 0 R
% Name tree for element identifiers
>>
endobj
881
SECTION 10.6
Logical Structure
301 0 obj
% Structure element for a chapter
<< /Type /StructElem
/S /Chap
/ID
( Chap1 )
% Element identifier
/T ( Chapter 1 )
% Human-readable title
/P 300 0 R
% Parent is the structure tree root
/K [
302 0 R
% Two children: a section head
303 0 R
% and a paragraph
]
>>
endobj
302 0 obj
% Structure element for a section head
<< /Type /StructElem
/S /Head1
/ID
( Sec1.1 )
% Element identifier
/T ( Section 1.1 )
% Human-readable title
/P 301 0 R
% Parent is the chapter
/Pg 101 1 R
% Page containing content items
/A << /O /Layout
% Attribute owned by Layout
/SpaceAfter 25
/SpaceBefore 0
/TextIndent 12.5
>>
/K 0
% Marked-content sequence 0
>>
endobj
303 0 obj
% Structure element for a paragraph
<< /Type /StructElem
/S /Para
/ID
( Para1 )
% Element identifier
/P 301 0 R
% Parent is the chapter
/Pg 101 1 R
% Page containing first content item
/C /Normal
% Class containing this element’s attributes
/K [
1
% Marked-content sequence 1
<< /Type /MCR
% Marked-content reference to 2nd item
/Pg 102 0 R
% Page containing second item
/MCID 0
% Marked-content sequence 0
>>
]
>>
endobj
882
CHAPTER 10
Document Interchange
304 0 obj
% Structure element for another paragraph
<< /Type /StructElem
/S /Para
/ID
( Para2 )
% Element identifier
/P 300 0 R
% Parent is the structure tree root
/Pg 102 0 R
% Page containing content items
/C /Normal
% Class containing this element’s attributes
/A << /O /Layout
/TextAlign /Justify
% Overrides attribute provided by classmap
>>
/K [ 1 2 ]
% Marked-content sequences 1 and 2
>>
endobj
305 0 obj
% Attribute class
<< /O /Layout
% Owned by Layout
/EndIndent 0
/StartIndent 0
/WritingMode /LrTb
/TextAlign /Start
>>
endobj
400 0 obj
% Parent tree
<< /Nums [ 0 401 0 R
% Parent elements for first page
1 402 0 R
% Parent elements for second page
]
>>
endobj
401 0 obj
% Array of parent elements for first page
[
302 0 R
% Parent of marked-content sequence 0
303 0 R
% Parent of marked-content sequence 1
]
endobj
402 0 obj
% Array of parent elements for second page
[
303 0 R
% Parent of marked-content sequence 0
304 0 R
% Parent of marked-content sequence 1
304 0 R
% Parent of marked-content sequence 2
]
endobj
403 0 obj
% ID tree root node
<< /Kids [ 404 0 R ] >>
% Reference to leaf node
endobj
Большое спасибо!
Ваше мнение очень важно для нас.
Нет комментариевНе стесняйтесь поделиться с нами вашим ценным мнением.
Текст