PDF Configuration > Tagged PDF Output
  
Tagged PDF Output
Tags in PDF output supply information that can be used by screen readers to improve accessibility to written documentation by providing a recognizable, standardized structure. PTC Arbortext Layout Developer (PTC ALD) provides the option to create these PDF Tags in document source, and include them in PDF output. You can create PDF Tags that will conform to a specific version of PDF/Adobe Acrobat (or equivalent).
General Guidelines
The following general guidelines apply when creating PDF Tags:
Provide a Role Map
A PDF Role Map Stream (.Tr) must be created to provide mappings between the elements that appear in the source document and recognized structure element roles from the PDF specification, see Support for Tagged PDF Output in this topic . The Role Map Stream must be associated with the document using one of the following methods:
• Create/select the Role Map Stream in the Role Map field on the Printing tab of the Document Preferences dialog box.
• Associate the map programmatically via fdpref pdftag_rolemap “rolemap stream”.
* 
If no Role Map is specified for the document, any tags that do not match a standard structure type will be treated as paragraphs.
See PDF Role Map (.Tr) in this topic for information.
Define default Tag parameters
A PDF Tag Control Stream (.Tg) can be created to provide any tag parameters other than the standard document and stream tag parameters. The PDF Tag Control Stream for the document must be associated with the document using one of the following methods:
• Create/select the PDF Tag Control Stream in the Default Tag Settings field on the Printing tab of the Document Preferences dialog box.
• Associate the control stream programmatically via fdpref pdftag_defaults “pdf tag control stream”.
See PDF Tag Control Stream (.Tg) in this topic for information.
Specify the Document element
PTC ALD will automatically add a Document element when it prints PDF with PDF Tag support. The Document element surrounds the entire content of the PDF.
If you want to create a custom Document element, specify its details in the PDF Tag Control Stream associated with the document (see above). Either set the value of name to Document or reference a custom name that is mapped in the document’s Role Map Stream to the recognized role of Document. You can then add additional information such as a title to the Document element by adding this detail to the PDF Tag Control Stream.
The PDF Tag you want to use as the Document element must be specified using one of the following methods:
• Select the PDF Tag in the Document Tag field on the Printing tab of the Document Preferences dialog box.
• Specify the PDF Tag programmatically via fdpref pdftag_document “pdf tag name”.
* 
If name is not set to Document within the PDF Tag Control Stream, or the required name is not mapped to the Document role in the Role Map Stream, PTC ALD will create its own default Document element.
Specify a default element to wrap frame content
When formatting frames, the graphics and text stream contained in that frame will be output in the PDF Tag structure at the point reached by the previous content. This will usually create an undesirable structure as the content from various frames could intermingle. You have two options for controlling behavior to avoid this:
1. Specify a PDF Tag to wrap the contents of a content stream whenever it is used in a frame. There are two ways of making the association:
a. Select the PDF Tag in the Default Stream Tag field on the Printing tab of the Document Preferences dialog box.
b. Use the tpdftag macro with the syntax shown below to associate a PDF Tag with a particular content stream:
tpdftag ["content stream"][,"pdftag name"]
2. Specify a default PDF Tag Control Stream that should be associated with every content stream used in the document
Use the tpdftag macro with the syntax shown below to associate a PDF Tag Control Stream with a particular content stream:
tpdftag ["content stream"][,"pdftag name"[,"pdftag stream"]]
You can also make this setting programmatically via fdpref pdftag_streams “pdftag name”.
The PDF Tag name associated with the content stream will be used in preference to the document’s default control stream.
* 
If the text content of a frame is set to repeat, the structure will automatically be terminated once the frame’s content is printed.
Summary of Process to Create PDF Tags
1. Create a PDF Role Map Control Stream with ttagmk “PDF Role Map Name.Tr”
2. Edit the PDF Role Map Control Stream to add all the required entries to map the elements in the current document structure to defined Standard Structure Types from the PDF Specification. Associate this control stream with the document.
See PDF Role Map (.Tr)in this topic for information on the content of a PDF Role Map.
See Provide a Role Mapin this topic for information on how to associate the role map with your document.
3. Create a PDF Tag Control Stream with ttagmk “PDFTag Control Stream Name.Tg”
4. Add the required default PDF Tag definitions for the document to the PDF Tag Control Stream. Associate this control stream to the document.
See PDF Tag Control Stream (.Tg)in this topic for information on the content of a PDF Tag Control Stream.
See Define default Tag parameters in this topic for information on how to associate the PDF Tag Control Stream with your document.
5. Configure the PDF Tags settings in the Printing tab of the Document Preferences dialog box
6. Create a second PDF Tag Control Stream (optional — only if you’re using a control stream to define tags for content streams)
7. Add the required tag definitions for the content streams in the document to the PDF Tag Control Stream (optional — as above). Associate this control stream to the content streams.
See Specify a default element to wrap frame content in this topic for information on how to associate the PDF Tag Control Stream with your content stream(s).
8. Add fFormatting.pdfTagStart() and fFormatting.pdfTagEnd(), or <?pdftagstart> and <?pdftagend>, commands to all appropriate streams to build the required tagging structure.
For example, for a paragraph:
formatting.pdfTagStart(new fPDFTagElement("Para"));
or
<?pdftagstart "Para">
PTC ALD Tag Types Supporting Tagged PDF Output
PDF Role Map (.Tr)
A control stream that provides mappings between the elements that appear in the source document and recognized structure element roles from the PDF specification.
Beginning with PDF Version 1.5, an element name is always mapped to its corresponding 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.
An example of the syntax of a PDF Role Map is given below - this sample shows some mappings between an axdocbook document structure and some defined PDF Standard Structure Types:
Book=Document
Chapter=Art
Section=Sect
Para=P
Title=H
ItemizedList=L
OrderedList=L
ListItem=LI
Procedure=L
PDF Tag Control Stream (.Tg)
A control stream that allows the specification of one or more PDF Tags used in the document, and appropriate parameters for those Tags.
Use the tpdftagctrl macro without parameters to invoke the Define PDF Tag Control Stream dialog box, or edit the .Tg tag directly.
Each line of the control stream must be in the form parameter=value, and each line can only contain one parameter. An example of the syntax of a PDF Tag Control Stream is given below - this sample shows some PDF Tag parameters for a document:
name=Book
title=My Document
name=PDF
expandedText-Portable Document Format
The name parameter is the only required parameter:
Parameter
Description
name
Required
The name of the Structure Element instance in the control stream. This option is used to delineate tag definitions with the control stream.
The value of this parameter can be a name defined in the in the document’s PDF Role Map, or one of the predefined structure types.
When the role of the named element is set to Artifact, the following parameters can be specified within the control stream:
Artifact Elements
Parameter
Description
type
Optional
The type of artifact that this property list describes:
• Pagination
• Layout
• Page
• Background (PDF1.7)
subtype
Optional (PDF 1.7)
The subtype of the artifact. This entry applies only when the type entry has a value of Pagination.
Valid values are:
• Header
• Footer
• Watermark
bbox
Optional
This entry only applies when the type entry has a value of Background.
The value for this entry is a comma delimited list of four numbers in default user space units. The numbers provide the coordinates of the left, bottom, right, and top edges, respectively, of the artifact’s bounding box.
A bounding box is the rectangle that completely encloses its visible extent.
attached
Optional
This entry only applies for pagination and full page background artifacts.
The value for this entry is a comma delimited list of name objects containing one to four of the locations Top, Bottom, Left, and Right. The locations specify the edges of the page, if any, to which the artifact is logically attached.
When the role of the named element is set to something other than Artifact, the following parameters can be specified within the control stream:
All Other Structure Elements
Parameter
Description
lang
Optional (PDF 1.4)
The language identifier specifying the natural language for all text in the structure element, except where overridden by language specifications for nested structure elements.
The value must be a two character ISO 639 language code, for example EN, DE, JA. It may optionally be followed by a hyphen character and a two character ISO 3166 country code, for example EN-US, EN-GB.
actualText
Optional (PDF 1.4)
Text that is an exact replacement for the structure element and its children.
altText
Optional
An alternate description of the structure element and its children in human readable form.
expandedtext
Optional (PDF 1.5)
The expanded form of an abbreviation.
title
Optional
A text string in human readable form that represents the title of the structure element.
This parameter is not valid for Inline Level Structural Element Roles (ILSEs) Span, Quote, Note, Reference, BibEntry, Code, RB, RT, RP, WT, and WP.
Refer to Support for Tagged PDF Output in this topic for descriptions of supported ILSEs.
colSpan
Optional
The number of columns in the enclosing table that are spanned by the cell.
This parameter is only valid for the Block Level Structural Element Roles (BLSEs) TD and TH.
Refer to Support for Tagged PDF Output in this topic for descriptions of supported BLSEs.
rowSpan
Optional
The number of rows in the enclosing table that are spanned by the cell.
This parameter is only valid for the Block Level Structural Element Roles (BLSEs) TD and TH.
inline
Optional
The value of this parameter can be 0 or 1.
• 0 (default) - elements are written as Structure Elements
• 1 - elements are written inline
This parameter is only valid for the Inline Level Structural Element Roles (ILSEs) Span, Quote, Note, Reference, BibEntry, and Code.
UI Options Supporting Tagged PDF Output
• PDF Tags group on the Printing tab of the Document Preferences dialog box (tdpref).
Here you can specify default PDF Tags that define the document itself and its content streams, assign a role map to provide the element/PDF Tag mappings and specify the control stream that holds default PDF Tag parameter settings.
• General tab of PDF Options dialog box:
◦ Compatibility field: select the version of Adobe Acrobat to which the tagged PDF output will apply
◦ Generate Tagged PDF checkbox
◦ Default Document Language field
• Screen Draw Level dialog box (tdslevel):
◦ PDF Tag Start/End field: display PDF Tag settings in a document
• Assign PDF Tag dialog box (tpdftag):
Here you can associate a PDF Tag or PDF Tag Control Stream with a content stream
• Define PDF Tag Control Stream dialog box (tpdftagctrl)
Use this dialog to create or modify a PDF Tag Control Stream, which allows the specification of one or more PDF Tags used in the document, and appropriate parameters for those Tags.
Refer to PDF Tag Control Stream (.Tg) in this topic for a list of Artifact and Element parameters you can define in this dialog box.
FOM Objects Supporting Tagged PDF Output
• fPDFRoleMap - represents the PDF Role Map Control Stream
• fPDFTag - represents the PDF Tag Control Stream
• fPDFTagArtifact - represents a PDF Tag with the role of Artifact
• fPDFTagElement - represents all other PDF Tags
• fFormatting.pdfTagStart() and fFormatting.pdfTagEnd() methods - delimit a PDF Tag creation request in source
Macros and PIs Supporting Tagged PDF Output
• tpdftag macro — allows a PDF Tag or a PDF Tag Control Stream to be associated with a content stream
• tpdftagctrl macro — allows the creation or modification of a PDF Tag within a PDF Tag Control Stream
• <?pdftagstart> and <?pdftagend> PIs — create a new PDF Tag inline in the appropriate streams, using the details provided by a specified PDF Tag Control Stream
• Variables control tagged PDF support — set these within Super Print (sprint) Control Streams or when adding manual print control:
◦ p268_tagged - provide a value of 0 or 1 to specify whether to generate tagged PDF.
If 1, PDF tags will be generated according to settings within the document.
◦ _p268_lang - the language identifier for the default document language.
This must be a two character ISO 639 language code, for example EN, DE, JA. It may optionally be followed by a hyphen character and a two character ISO 3166 country code, for example EN-US, EN-GB.
◦ _p268_compatibility - the Adobe Acrobat version number for the required PDF version.
Support for Tagged PDF Output
Refer to PDF Reference Sixth Edition v1.7 for full implementation notes for provision of PDF Tags. There are limitations to the support provided by PTC ALD:
• Standard Structure Attributes are not supported.
• To use Custom Structure Types, a suitable PDF Role Map must be created and associated with the document before formatting.
• Pseudo Structure Types and Inline Level Structural Element Structural Roles (ILSEs) with inline=1 set are not allowed to span pages.
• When generating a tagged PDF which does not start at page 1 of the document or uses non-contiguous page ranges, PTC ALD will replicate the tag hierarchy present at the beginning of the page. Each non-contiguous range will be tagged independently.
• Incorrect use of the PDF Tags may generate exceptions during printing — the exceptions may results in no PDF output being generated.
The following tables describe the defined Roles provided for Structure Types in this release:
Pseudo Element Roles
Parameter
Description
Artifact
Objects that are not typically part of the desired content but information rated in the course of producing the output document, e.g. headers and footers, watermarks, etc.
Information contained within an Artifact will not appear in a document’s logical structure.
Grouping Element Roles
Parameter
Description
Document
A complete document. This is the root element of any structure tree containing multiple parts or multiple articles.
Part
A large scale division of a document
This type of element is appropriate for grouping articles or sections.
Art
(Article) A relatively self-contained body of text constituting a single narrative or exposition
Articles should not contain other articles as constituent elements.
Sect
(Section) A container for grouping related content elements
For example, a section might contain a heading, several introductory paragraphs, and two or more other child sections nested within it as subsections.
Div
(Division) A generic block-level element or group of elements
BlockQuote
(Block quotation) A portion of text consisting of one of more paragraphs attributed to someone other than the author of the surrounding text
Caption
A brief portion of text describing a table or figure
TOC
Table of contents
TOC1
Table of contents item
Index
Index
NonStruct
(Non-structural element) A grouping element having no inherent structural significance
It is used solely for grouping purposes.
Private
A grouping element containing private content belonging to the application producing it
Block Level Structural Element Roles (BLSEs)
Parameter
Description
P
Paragraph
H
Heading
H1–H6
Headings with specific levels, up to 6
L
List
LI
List item
Lbl
Label for a list item, e.g. number and punctuation
LBody
List body, i.e. the descriptive content of a list item
Table
Table
THead
Table header row group
TBody
Table body row group
TFoot
Table footer row group
TR
Table row
TD
Table data / cell
TH
Table header cell
Inline Level Structural Element Roles (ILSEs)
Parameter
Description
Span
A generic inline portion of text having no particular inherent characteristics
Quote
(Quotation) An inline portion of text attributed to someone other than the author of the surrounding text
Note
An item of explanatory text, such as a footnote or an endnote, that is referred to from within the body of the document
Reference
A citation to content elsewhere in the document
BibEntry
(Bibliography entry) A reference identifying the external source of some cited content
Code
A fragment of computer program text
Link
An association between a portion of the ILSE’s content and a corresponding link annotation or annotations
Annot
(Annotation) An association between a portion of the ILSE’s content and a corresponding PDF annotation
Ruby
A sidenote (annotation) written in smaller text size and placed adjacent to the base text to which it refers
RB
(Ruby base text) The full size text to which the ruby annotation is applied
RT
(Ruby annotation text) The smaller size text that is placed adjacent to the ruby base text
RP
(Ruby punctuation) Punctuation surrounding the ruby annotation
Warichu
A comment or annotation in a smaller text size that is formatted onto two smaller lines within the height of the containing text line and placed following (inline) the base text to which it refers
WT
(Warichu text) The smaller size text of a warichu comment that is formatted in two lines and placed between surrounding WP elements
WP
(Warichu punctuation) The punctuation that surrounds the WT text
Illustration Element Roles
Parameter
Description
Figure
An item of graphical content
Formula
A mathematical formula
Form
A widget annotation representing an interactive form field