Repository navigation
PDF Spec 14 Page Piece
Part of: PDF-Spec-14-Document-Interchange
Navigation: PDF-Spec-14-Metadata | PDF-Spec-Index | PDF-Spec-14-Structure
A structure element dictionary may include one or more marked-content sequences as content items by referring to them in its K entry (see Table 323). This reference may have two forms:
- A dictionary object called a marked-content reference. Table 324 shows the contents of this type of dictionary, which shall specify the marked-content identifier, as well other information identifying the stream in which the sequence is contained. Example 2 illustrates the use of a marked-content reference to the marked-content sequence shown in Example 3.
- An integer that specifies the marked-content identifier. This may 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 dictionary. Example 3 shows a structure element that has three children: a markedcontent sequence specified by a marked-content identifier, as well as two other structure elements.
% Structure element % Structure type % Parent in structure hierarchy << /Type /MCR % Page containing marked-content sequence % Marked-content identifier
EXAMPLE 2 1 0 obj << /Type /StructElem /S /P /P … /K /Pg 2 0 R /MCID 0 >> >> endobj
Table 324 - Entries in a marked-content reference dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Required) The type of PDF object that this dictionary describes; shall be MCR for a marked-content reference. |
| Pg | dictionary | (Optional; shall be an indirect reference) The page object representing the page on which the graphics objects in the marked-content sequence shall be rendered. This entry overrides any Pg entry in the structure element containing the marked-content reference; it shall be required if the structure element has no such entry. |
| Stm | stream | (Optional; shall be an indirect reference) The content stream containing the marked-content sequence. This entry should be present only if the marked-content sequence resides in a content stream other than the content stream for the page (see 8.10, 'Form XObjects' and 12.5.5, 'Appearance Streams'). If this entry is absent, the marked-content sequence shall be 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; shall be an indirect reference) The PDF object owning the stream identified by Stems annotation to which an appearance stream belongs. |
| MCID | integer | (Required) The marked-content identifier of the marked-content sequence within its content stream. |
EXAMPLE 3 1 0 obj << /Type /StructElem /S /MixedContainer
/P …
% Containing structure element
% Structure type % 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 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 may also contain marked content sequences that are content items of structure elements. The content of form XObjects may be incorporated into structure elements in one of the following ways:
- A Do operator that paints a form XObject may be part of a marked-content sequence that shall be associated with a structure element (see Example 4). In this case, the entire form XObject shall be 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 shall not in turn contain any marked-content sequences associated with this or other structure elements.
- The content stream of a form XObject may contain one or more marked-content sequences that shall be associated with structure elements (see Example 5). The form XObject may have arbitrary substructure, containing any number of marked-content sequences associated with logical structure elements. However, any Do operator that paints the form XObject should not be part of a logical structure content item.
A form XObject that is painted with multiple invocations of the Do operator may be incorporated into the document's logical structure only by the first method, with each invocation of Do individually associated with a structure element.
EXAMPLE 4 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 EXAMPLE 5 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 … EMC % End of marked-content sequence … endstream endobj
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 shall be identified in the structure element's K entry by an object reference dictionary (see Table 325).
- NOTE 1 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 subclause.
- NOTE 2 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.)
Table 325 - Entries in an object reference dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Required) The type of PDF object that this dictionary describes; shall be OBJR for an object reference. |
| Pg | dictionary | (Optional; shall be an indirect reference ) The page object of the page on which the object shall be rendered. This entry overrides any Pg entry in the structure element containing the object reference; it shall be used if the structure element has no such entry. |
| Obj | (any) | (Required; shall be an indirect reference ) The referenced object. |
Because a stream may not 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 different mechanism, the structural parent tree , shall be provided for this purpose. For consistency, content items that are entire PDF objects, such as XObjects, also shall use the parent tree to refer to their parent structure elements.
The parent tree is a number tree (see 7.9.7, 'Number Trees'), accessed from the ParentTree entry in a document's structure tree root (Table 322). The tree shall contain 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 shall be an integer given as the value of the StructParent or StructParents entry in the object (see Table 326). The values of these entries shall be as follows:
- For an object identified as a content item by means of an object reference (see 14.7.4.3, 'PDF Objects as Content Items'), the value shall be an indirect reference to the parent structure element.
- For a content stream containing marked-content sequences that are content items, the value shall be an array of indirect references to the sequences' parent structure elements. The array element corresponding to each sequence shall be 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 structural 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 shall hold 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, the current value of ParentTreeNextKey shall be used as its key. The value shall be 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 represented in the tree shall contain a special dictionary entry, StructParent or StructParents (see Table 326). 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 structure element. Its value shall be the integer key under which the entry corresponding to the object shall be found in the structural parent tree.
Table 326 - 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. At most one of these two entries shall be present in a given object. An object may 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 may 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 in the parent tree shall be a reference to the parent structure element (see Example 1).
EXAMPLE 1 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 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 shall be 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 shall not be 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 shall be found by using the sequence's marked-content identifier as an index into this array (see Example 2).
EXAMPLE 2 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 …
A conforming product that processes logical structure may attach additional information, called attributes , to any structure element. The attribute information shall be held in one or more attribute objects associated with the structure element. An attribute object shall be a dictionary or stream that includes an O entry (see Table 327) identifying the conforming product that owns the attribute information. Other entries shall represent the attributes: the keys shall be attribute names, and values shall be the corresponding attribute values. To facilitate the interchange of content among conforming products, PDF defines a set of standard structure attributes identified by specific standard owners; see 14.8.5, 'Standard Structure Attributes.' In addition, (PDF 1.6) attributes may be used to represent user properties (see 14.7.5.4, 'User Properties').
Table 327 - Entry common to all attribute object dictionaries
| Key | Type | Value |
|---|---|---|
| O | name | (Required) The name of the conforming product owning the attribute data. The name shall conform to the guidelines described in Annex E. |
Any conforming product may attach attributes to any structure element, even one created by another conforming product. Multiple conforming products may attach attributes to the same structure element. The A entry in the structure element dictionary (see Table 323) shall hold either a single attribute object or an array of such objects, together with revision numbers for coordinating attributes created by different conforming products (see 14.7.5.3, 'Attribute Revision Numbers'). A conforming product creating or destroying the second attribute object for a structure element shall be responsible 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 shall be defined for the attribute objects in an A array, but new objects should be added at the end of the array so that the first array element is the one belonging to the conforming product that originally created the structure element.
If many structure elements share the same set of attribute values, they may be defined as an attribute class sharing the identical attribute object. Structure elements shall refer to the class by name. The association between class names and attribute objects shall be defined by a dictionary called the class map , that shall be kept in the ClassMap entry of the structure tree root (see Table 322). Each key in the class map shall be a name object denoting the name of a class. The corresponding value shall be 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 mechanism for storing attribute information in a more compact form; they have no inheritance properties like those of true object-oriented classes.
The C entry in a structure element dictionary (see Table 323) shall contain a class name or an array of class names (typically accompanied by revision numbers as well; see 14.7.5.3, 'Attribute Revision Numbers'). For each class named in the C entry, the corresponding attribute object or objects shall be 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 shall take precedence.
% Entry for page object 2; array element at index 0 % points back to parent structure element
When a conforming product modifies a structure element or its contents, the change may affect the validity of attribute information attached to that structure element by other conforming products. A system of revision numbers shall allow conforming products to detect such changes and update their own attribute information accordingly, as described in this sub-clause.
A structure element shall have a revision number, that shall be stored in the R entry in the structure element dictionary (see Table 323) or default to 0 if no R entry is present. Initially, the revision number shall be 0. When a conforming product modifies the structure element or any of its content items, it may signal the change by incrementing the revision number.
- NOTE 1 The revision number is unrelated to the generation number associated with an indirect object (see 7.3.10, 'Indirect Objects').
- NOTE 2 If their is no R entry and the revision number is to be incremented from the default value of 0 to 1, an R entry must be created in the structure element dictionary in order to record the 1.
Each attribute object attached to a structure element shall have an associated revision number. The revision number shall be stored in the array that associates the attribute object with the structure element or if not stored in the array that associates the attribute object with the structure element shall default to 0.
- Each attribute object in a structure element's A array shall be represented by a single or a pair of array elements, the first or only element shall contain the attribute object itself and the second (when present) shall contain the integer revision number associated with it in this structure element.
- The structure element's C array shall contain a single or a pair of elements for each attribute class, the first or only shall contain the class name and the second (when present) shall contain the associated 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 shall have a revision number of 0 and is represented by a single entry in the array.
- NOTE 3 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). Since an attribute object reference is distinct from an integer, that distinction is used to determine whether the attribute object is represented in the array by a single or a pair of entries.
- NOTE 4 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 object's revision number with that of the structure element, an application can determine whether the contents of the attribute object are still current or whether they have been outdated by more recent changes in the underlying structure element.
Changes in an attribute object shall not change the revision number of the associated structure element, which shall change only when the structure element itself or any of its content items is modified.
Occasionally, a conforming product 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 conforming product may choose to delete all unknown attribute objects from its A and C arrays. These two actions shall be mutually exclusive: the conforming product should either increment the structure element's revision number or remove its attribute objects, but not both.
- NOTE 5 Any conforming product creating attribute objects needs to be prepared for the possibility that they can be deleted at any time by another conforming product.
Most structure attributes (see 14.8.5, 'Standard Structure Attributes') specify information that is reflected in the element's appearance; for example, BackgroundColor or BorderStyle .
Some conforming writers, 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 another. For example, several transistors might have the same appearance but different attributes such as type and part number.
User properties (PDF 1.6) may be used to contain such information. Any graphical object that corresponds to a structure element may have associated user properties, specified by means of an attribute object dictionary that shall have a value of UserProperties for the O entry (see Table 328).
Table 328 - Additional entries in an attribute object dictionary for user properties
| Key | Type | Value |
|---|---|---|
| O | name | (Required) The attribute owner. Shall be UserProperties . |
| P | array | (Required) An array of dictionaries, each of which represents a user property (see Table 329). |
The P entry shall be an array specifying the user properties. Each element in the array shall be a user property dictionary representing an individual property (see Table 329). The order of the array elements shall specify attributes in order of importance.
Table 329 - 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. While the value of this entry shall be any type of PDF object, conforming writers should use only text string, number, and boolean values. Conforming readers should display text, number and boolean values to users but need not display values of other types; however, they should not treat other values as errors. |
| F | text string | (Optional) A formatted representation of the value of V , that shall be used for special formatting; for example '($123.45)' for the number -123.45. If this entry is absent, conforming readers should use a default format. |
| H | boolean | (Optional) If true , the attribute shall be hidden; that is, it shall not be shown in any user interface element that presents the attributes of an object. Default value: false . |
PDF documents that contain user properties shall provide a UserProperties entry with a value of true in the document's mark information dictionary (see Table 321). This entry allows conforming readers to quickly determine whether it is necessary to search the structure tree for elements containing user properties.
EXAMPLE
The following example shows a structure element containing user properties called Part Name, Part Number, Supplier, and Price.
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
The next Example 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 14.8.4, 'Standard Structure Types') by means of the role map specified in the structure tree root. Objects 302 through 304 have attached attributes (see 14.7.5, 'Structure Attributes,' and 14.8.5, 'Standard Structure Attributes').
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
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 /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 /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 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 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
% Parent of marked-content sequence 0 % Parent of marked-content sequence 1 % Array of parent elements for second page % Parent of marked-content sequence 0 % Parent of marked-content sequence 1 % Parent of marked-content sequence 2 [ ( Chap1 ) ( Sec1.3 ) ]
>> /K [ 1 2 ] >> endobj 305 0 obj << /O /Layout /EndIndent 0 /StartIndent 0 /WritingMode /LrTb /TextAlign /Start >> endobj 400 0 obj << /Nums [ 0 401 0 R 1 402 0 R ] >> endobj 401 0 obj [ 302 0 R 303 0 R ] endobj 402 0 obj [ 303 0 R 304 0 R 304 0 R ] endobj 403 0 obj << /Kids [ 404 0 R ] >> endobj 404 0 obj << /Limits /Names [ ( Chap1 ) 301 0 R ( Sec1.1 ) 302 0 R ( Sec1.2 ) 303 0 R ( Sec1.3 ) 304 0 R ] >> endobj
Tagged PDF (PDF 1.4) is a stylized use of PDF that builds on the logical structure framework described in 14.7, 'Logical Structure.' It defines a set of standard structure types and attributes that allow page content (text, graphics, and images) to be extracted and reused for other purposes. A tagged PDF document is one that conforms to the rules described in this sub-clause. A conforming writer is not required to produce tagged PDF documents; however, if it does, it shall conform to these rules.
NOTE 1 It is intended for use by tools that perform the following types of operations:
- Simple extraction of text and graphics for pasting into other applications
% Marked-content sequences 1 and 2 % Attribute class % Owned by Layout % Parent tree % Parent elements for first page % Parent elements for second page % Array of parent elements for first page % ID tree root node % Reference to leaf node % ID tree leaf node % Least and greatest keys in tree % Mapping from element identifiers % to structure elements
- Automatic reflow of text and associated graphics to fit a page of a different size than was assumed for the original layout
- Processing text for such purposes as searching, indexing, and spell-checking
- Conversion to other common file formats (such as HTML, XML, and RTF) with document structure and basic styling information preserved
- Making content accessible to users with visual impairments (see 14.9, 'Accessibility Support')
A tagged PDF document shall conform to the following rules:
- Page content (14.8.2, 'Tagged PDF and Page Content'). Tagged PDF defines a set of rules for representing text in the page content so that characters, words, and text order can be determined reliably. All text shall be represented in a form that can be converted to Unicode. Word breaks shall be represented explicitly. Actual content shall be distinguished from artifacts of layout and pagination. Content shall be given in an order related to its appearance on the page, as determined by the conforming writer.
- A basic layout model (14.8.3, 'Basic Layout Model'). A set of rules for describing the arrangement of structure elements on the page.
- Structure types (14.8.4, 'Standard Structure Types'). A set of standard structure types define the meaning of structure elements, such as paragraphs, headings, articles, and tables.
- Structure attributes (14.8.5, 'Standard Structure Attributes'). Standard structure attributes preserve styling information used by the conforming writer in laying out content on the page.
A Tagged PDF document shall also contain a mark information dictionary (see Table 321) with a value of true for the Marked entry.
- NOTE 2 The types and attributes defined for Tagged PDF are intended to provide a set of standard fallback roles and minimum guaranteed attributes to enable conforming readers to perform operations such as those mentioned previously. Conforming writers are free to define additional structure types as long as they also provide a role mapping to the nearest equivalent standard types, as described in 14.7.3, 'Structure Types.' Likewise, conforming writers can define additional structure attributes using any of the available extension mechanisms.
Like all PDF documents, a Tagged PDF document consists of a sequence of self-contained pages, each of which shall be described by one or more page content streams (including any subsidiary streams such as form XObjects and annotation appearances). Tagged PDF defines some further rules for organizing and marking content streams so that additional information can be derived from them:
- Distinguishing between the author's original content and artifacts of the layout process (see 14.8.2.2, 'Real Content and Artifacts').
- Specifying a content order to guide the layout process if the conforming reader reflows the page content (see 14.8.2.3, 'Page Content Order').
- Representing text in a form from which a Unicode representation and information about font characteristics can be unambiguously derived (see 14.8.2.4, 'Extraction of Character Properties').
- Representing word breaks unambiguously (see 14.8.2.5, 'Identifying Word Breaks').
- Marking text with information for making it accessible to users with visual impairments (see 14.9, 'Accessibility Support').
The graphics objects in a document can be divided into two classes:
- The real content of a document comprises objects representing material originally introduced by the document's author.
- Artifacts are graphics objects that are not part of the author's original content but rather are generated by the conforming writer in the course of pagination, layout, or other strictly mechanical processes.
- NOTE Artifacts may also be used to describe areas of the document where the author uses a graphical background, with the goal of enhancing the visual experience. In such a case, the background is not required for understanding the content.
The document's logical structure encompasses all graphics objects making up the real content and describes how those objects relate to one another. It does not include graphics objects that are mere artifacts of the layout and production process.
A document's real content includes not only the page content stream and subsidiary form XObjects but also associated annotations that meet all of the following conditions:
- The annotation has an appearance stream (see 12.5.5, 'Appearance Streams') containing a normal ( N ) appearance.
- The annotation's Hidden flag (see 12.5.3, 'Annotation Flags') is not set.
- The annotation is included in the document's logical structure (see 14.7, 'Logical Structure').
An artifact shall be explicitly distinguished from real content by enclosing it in a marked-content sequence with the tag Artifact:
| /Artifact | /Artifact propertyList | |
|---|---|---|
| BMC | BDC | |
| … | or | … |
| EMC | EMC |
The first form shall be used to identify a generic artifact; the second shall be used for those that have an associated property list. Table 330 shows the properties that can be included in such a property list.
- NOTE 1 To aid in text reflow, artifacts should be defined with property lists whenever possible. Artifacts lacking a specified bounding box are likely to be discarded during reflow.
Table 330 - Property list entries for artifacts
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of artifact that this property list describes; if present, shall be one of the names Pagination , Layout , Page , or (PDF 1.7) Background . |
| BBox | rectangle | (Optional; required for background artifacts) An array of four numbers in default user space units giving the coordinates of the left, bottom, right, and top edges, respectively, of the artifact's bounding box (the rectangle that completely encloses its visible extent). |
Table 330 - Property list entries for artifacts (continued)
| Key | Type | Value |
|---|---|---|
| Attached | array | (Optional; pagination and full-page background artifacts only) An array of name objects containing one to four of the names Top, Bottom, Left, and Right, specifying the edges of the page, if any, to which the artifact is logically attached. Page edges shall be defined by the page's crop box (see 14.11.2, 'Page Boundaries'). The ordering of names within the array is immaterial. Including both Left and Right or both Top and Bottom indicates a full-width or full-height artifact, respectively. Use of this entry for background artifacts shall be limited to full-page artifacts. Background artifacts that are not full-page take their dimensions from their parent structural element. |
| Subtype | name | (Optional; PDF 1.7) The subtype of the artifact. This entry should appear only when the Type entry has a value of Pagination. Standard values are Header, Footer, and Watermark. Additional values may be specified for this entry, provided they comply with the naming conventions described in Annex E. |
The following types of artifacts can be specified by the Type entry:
- Pagination artifacts . Ancillary page features such as running heads and folios (page numbers).
- Layout artifacts . Purely cosmetic typographical or design elements such as footnote rules or background screens.
- Page artifacts . Production aids extraneous to the document itself, such as cut marks and colour bars.
- Background artifacts . Images, patterns or coloured blocks that either run the entire length and/or width of the page or the entire dimensions of a structural element. Background artifacts typically serve as a background for content shown either on top of or placed adjacent to that background.
A background artifact can further be classified as visual content that serves to enhance the user experience, that lies under the actual content, and that is not required except to retain visual fidelity.
- NOTE 2 Examples of this include a coloured background, pattern, blend, or image that resides under main body text. In the case of white text on a black background, the black background is absolutely necessary to be able to read the white text; however, the background itself is merely there to enhance the visual experience. However, a draft or other identifying watermark is classified as a pagination artifact because it does not serve to enhance the experience; rather, it serves as a running artifact typically used on every page in the document. As a further example, a Figure differs from a background artifact in that removal of the graphics objects from a Figure would detract from the overall contextual understanding of the Figure as an entity.
- Tagged conforming readers may have their own ideas about what page content to consider relevant. A text-to-speech engine, for instance, probably should not speak running heads or page numbers when the page is turned. In general, conforming readers can do any of the following:
- Disregard elements of page content (for example, specific types of artifacts) that are not of interest
- Treat some page elements as terminals that are not to be examined further (for example, to treat an illustration as a unit for reflow purposes)
- Replace an element with alternate text (see 14.9.3, 'Alternate Descriptions')
- NOTE 3 Depending on their goals, different conforming readers can make different decisions in this regard. The purpose of Tagged PDF is not to prescribe what the conforming reader should do, but to provide sufficient declarative and descriptive information to allow it to make appropriate choices about how to process the content.
To support conforming readers in providing accessibility to users with disabilities, Tagged PDF documents should use the natural language specification ( Lang ), alternate description ( Alt ), replacement text ( ActualText ), and abbreviation expansion text ( E ) facilities described in 14.9, 'Accessibility Support.'
In addition to objects that are explicitly marked as artifacts and excluded from the document's logical structure, the running text of a page may contain other elements and relationships that are not logically part of the document's real content, but merely incidental results of the process of laying out that content into a document. They may include the following elements:
- Hyphenation . Among the artifacts introduced by text layout is the hyphen marking the incidental division of a word at the end of a line. In Tagged PDF, such an incidental word division shall be represented by a soft hyphen character, which the Unicode mapping algorithm (see 'Unicode Mapping in Tagged PDF' in 14.8.2.4, 'Extraction of Character Properties') translates to the Unicode value U+00AD. (This character is distinct from an ordinary hard hyphen , whose Unicode value is U+002D.) The producer of a Tagged PDF document shall distinguish explicitly between soft and hard hyphens so that the consumer does not have to guess which type a given character represents.
NOTE 1 In some languages, the situation is more complicated: there may be multiple hyphen characters, and hyphenation may change the spelling of words. See the Example in 14.9.4, 'Replacement Text.'
- Text discontinuities . The running text of a page, as expressed in page content order (see 14.8.2.3, 'Page Content Order'), may contain places where the normal progression of text suffers a discontinuity. Conforming readers may recognize such discontinuities by examining the document's logical structure.
- NOTE 2 For example, the page may contain the beginnings of two separate articles (see 12.4.3, 'Articles'), each of which is continued onto a later page of the document. The last words of the first article appearing on the page should not be run together with the first words of the second article.
- Hidden page elements . For a variety of reasons, elements of a document's logical content may be invisible on the page: they may be clipped, their colour may match the background, or they may be obscured by other, overlapping objects. For the purposes of Tagged PDF, page content shall be considered to include all text and illustrations in their entirety, regardless of whether they are visible when the document is displayed or printed.
- NOTE 3 For example, formerly invisible elements may become visible when a page is reflowed, or a text-to-speech engine may choose to speak text that is not visible to a sighted reader.
When dealing with material on a page-by-page basis, some Tagged PDF conforming readers may choose to process elements in page content order , determined by the sequencing of graphics objects within a page's content stream and of characters within a text object, rather than in the logical structure order defined by a depth-first traversal of the page's logical structure hierarchy. The two orderings are logically distinct and may or may not coincide. In particular, any artifacts the page may contain shall be included in the page content order but not in the logical structure order, since they are not considered part of the document's logical structure. The conforming writer is responsible for establishing both an appropriate page content order for each page and an appropriate logical structure hierarchy for the entire document.
Because the primary requirement for page content order is to enable reflow to maintain elements in proper reading sequence, it should normally (for Western writing systems) proceed from top to bottom (and, in a multiple-column layout, from column to column), with artifacts in their correct relative places. In general, all parts of an article that appear on a given page should be kept together, even if the article flows to scattered locations on the page. Illustrations or footnotes may be interspersed with the text of the associated article or may appear at the end of its content (or, in the case of footnotes, at the end of the entire page's logical content).
In some situations, conforming writer may be unable to determine correct page content order for part of a document's contents. In such cases, tag suspects (PDF 1.6) can be used. The conforming writer shall identify suspect content by using marked content (see 14.6, 'Marked Content') with a tag of TagSuspect, as shown in next Example. The marked content shall have a properties dictionary with an entry whose name is TagSuspect
and whose value is Ordering , which indicates that the ordering of the enclosed marked content does not meet Tagged PDF specifications.
NOTE This can occur, for example, if content was extracted from another application, or if there are ambiguities or missing information in text output.
Documents containing tag suspects shall contain a Suspects entry with a value of true in the mark information dictionary (see Table 321).
Annotations associated with a page are not interleaved within the page's content stream but shall be placed in the Annots array in its page object (see 7.7.3.3, 'Page Objects'). Consequently, the correct position of an annotation in the page content order is not readily apparent but shall be determined from the document's logical structure.
Both page content (marked-content sequences) and annotations may be treated as content items that are referenced from structure elements (see 14.7.4, 'Structure Content'). Structure elements of type Annot ( PDF 1.5 ), Link, or Form (see 14.8.4.4, 'Inline-Level Structure Elements,' and 14.8.4.5, 'Illustration Elements') explicitly specify the association between a marked-content sequence and a corresponding annotation. In other cases, if the structure element corresponding to an annotation immediately precedes or follows (in the logical structure order) a structure element corresponding to a marked-content sequence, the annotation is considered to precede or follow the marked-content sequence, respectively, in the page content order.
NOTE If necessary, a conforming writer may introduce an empty marked-content sequence solely to serve as a structure element for the purpose of positioning adjacent annotations in the page content order.
NOTE 1 In writing systems that are read from right to left (such as Arabic or Hebrew), one might expect that the glyphs in a font would have their origins at the lower right and their widths (rightward horizontal displacements) specified as negative. For various technical and historical reasons, however, many such fonts follow the same conventions as those designed for Western writing systems, with glyph origins at the lower left and positive widths, as shown in Figure 39. Consequently, showing text in such right-to-left writing systems requires either positioning each glyph individually (which is tedious and costly) or representing text with show strings (see 9.2, 'Organization and Use of Fonts') whose character codes are given in reverse order. When the latter method is used, the character codes' correct page content order is the reverse of their order within the show string.
The marked-content tag ReversedChars informs the conforming reader that show strings within a markedcontent sequence contain characters in the reverse of page content order. If the sequence encompasses multiple show strings, only the individual characters within each string shall be reversed; the strings themselves shall be in natural reading order.
EXAMPLE The sequence
/ReversedChars BMC ( olleH ) Tj -200 0 Td ( . dlrow ) Tj EMC
represents the text
Hello world .
The show strings may have a SPACE (U+0020) character at the beginning or end to indicate a word break (see 14.8.2.5, 'Identifying Word Breaks') but shall not contain interior SPACEs.
- NOTE 2 This limitation is not serious, since a SPACE provides an opportunity to realign the typography without visible effect, and it serves the valuable purpose of limiting the scope of reversals for word-processing conforming readers.
Navigation: PDF-Spec-14-Metadata | PDF-Spec-Index | PDF-Spec-14-Structure