Next Previous

Retired Document

Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.

Documentation-Set Tokens Schema Reference

This chapter describes the element structure of the Tokens.xml (tokens) file used in documentation sets.

The schema for the nodes file, TokensSchema.rng, is located in the DocSetAccess framework in <Xcode>/Library/PrivateFrameworks/DocSetAccess.framework.

Listing D-1 lists the topology of the elements of a nodes file.

Listing D-1 Tokens.xml element topology

Tokens

   Token

      TokenIdentifier

         Name

         APILanguage

         Type

         Scope

      Path

      NodeRef

      Anchor

      Abstract

      Declaration

      Parameters

          Parameter

             Name

             Abstract

      ReturnValue

      DeclaredIn

         HeaderPath

         FrameworkName

      Availability

         IntroducedInVersion

         RemovedAfterVersion

         DeprecatedInVersion

         DeprecationSummary

      RelatedTokens

         TokenIdentifier

      RelatedDocuments

         NodeRef

URL

      RelatedSampleCode

         NodeRef

URL

   File

      Token

   RelatedTokens

      TokenIdentifier

Tokens

The root element of a tokens file.

Tokens [version]

   Token

   File

   RelatedTokens

Attributes

Name	Type	Description
`version`	Decimal	The version number of the `NodesSchema.rng` file. The only supported version is 1.0.

Subelements

Cardinality	Element	Para
`1..*`	Token	Specifies a symbol.
	File	Identifies an HTML file and defines set of symbols that are documented in that file. See Grouping Tokens by File for details.
	RelatedTokens	Specifies a set of symbols in which each symbol is related to every other symbol in the set. See Specifying Related Tokens for details.

Token

Describes a single symbol, or token.

Token []

   TokenIdentifier

   Path

   NodeRef

   Anchor

   Abstract

   Parameters

   ReturnValue

   Declaration

   DeclaredIn

   Availability

   RelatedTokens

   RelatedDocuments

   RelatedSampleCode

This element:

Associates a symbol with its primary reference documentation.
Supplies additional information—such as availability, declaration, and so forth—about the symbol.

For usage information, see Defining a Symbol for Lookup.

Attributes

None.

Subelements

Cardinality	Element	Usage
`1`	TokenIdentifier	Identifies the symbol.
`0..1`	Path	Specifies the path to the HTML file containing the primary documentation. Must not be used when the token is located within a `File` element.
`0..1`	NodeRef	References the node representing the primary documentation for the symbol. Must not be used when the token is located within a `File` element. Can be used alone or in conjunction with a Path element (see Associating Symbols with API Reference Documentation for details).
`0..1`	Anchor	If you have a single HTML file that contains the primary reference documentation for more than one token, use this element to specify the location within that file of a particular token’s description.
`0..1`	Abstract	Provides a summary or brief description of the symbol.
`0..1`	Declaration	Specifies the symbol’s declaration statement.
`0..1`	Parameters	Specifies the list of parameters, if any, passed to the symbol.
`0..1`	ReturnValue	Specifies the value returned by the symbol, if any.
`0..1`	DeclaredIn	Specifies the header and framework in which the symbol is declared.
`0..1`	Availability	Specifies the product versions and computer architectures in which the token appears.
`0..1`	RelatedTokens	Specifies a set of symbols that are related to the token. The relationship is one way; there’s no inverse relationship from those symbols to this one.
`0..1`	RelatedDocuments	Specifies a list of documents that contain further information about the symbol. A token identifies its primary reference documentation through the Path, NodeRef, or File elements; do not use this element to specify the primary reference documentation.
`0..1`	RelatedSampleCode	Specifies a list of documents containing sample code that showcase the symbol’s usage.

TokenIdentifier

Uniquely identifies a symbol or token.

TokenIdentifier [] {tokenizedString}

   Name

   APILanguage

   Type

   Scope

There are two ways to specify a token identifier (use only one):

Using the Name, Type, APILanguage, and Scope subelements to individually specify the token's properties (Subelements).
Using an identifier that conforms to the apple_ref convention (Content), described in “Symbol Markers for HTML-Based Documentation” in HeaderDoc User Guide.

For more information, see Identifying Symbols.

Attributes

None.

Subelements

Each subelement specifies a specific component of a symbol identifier. See Defining Tokens Using Individual Properties for details.

Cardinality	Element	Usage
`1`	Name	Specifies the name of the symbol. For example: `arrayWithContentsOfFile:`.
`0..1`	APILanguage	Specifies the programming language in which the symbol is defined. For example: `occ`.
`1`	Type	Specifies the symbol’s type. For example: `clm`.
`0..1`	Scope	Specifies the scope within which the symbol is defined. For example: `NSArray`.

Content

Tokenized string. This string identifies a symbol. For example: //apple_ref/occ/clm/NSArray/arrayWithContentsOfFile:. See Defining Tokens Using apple_ref Identifiers for details.

Name

Specifies a name.

Name [] {string}

Attributes

None.

Content

String.

APILanguage

Species a programming language.

APILanguage [] {string}

Attributes

None.

Content

String.

Type

Specifies a symbol type.

Type [] {string}

Attributes

None.

Content

String. Valid values are described in “Symbol Markers for HTML-Based Documentation” in HeaderDoc User Guide.

Scope

Specifies a programming scope (namespace or container).

Scope [] {string}

Attributes

None.

Content

String.

Abstract

Specifies a summary or brief description.

Abstract [type] {HTMLCode|string}

This element lets you provide a summary description, usually one sentence.

When using HTML content, it must be valid; this includes double-escaping of entities. You can include links or basic HTML formatting. Hyperlinks with relative paths are resolved relative to the Documents directory.

Attributes

Name	Type	Description
`type`	String	Optional. The type of the content. Values: `"text"` (default), `"html"`.

Content

HTML code or string.

Anchor

Specifies the name of an anchor in an HTML file.

Anchor [] {normalizedString}

Attributes

None.

Content

Normalized string.

NodeRef

References a node defined in the nodes file.

NodeRef [refid]

Attributes

Name	Type	Description
`refid`	Integer	Specifies the `id` of the referenced node.

Declaration

Specifies a symbol’s declaration statement.

Declaration [type] {HTMLCode|string}

Use an HTML PRE element to ensure the line breaks and indentations are preserved when the content is displayed.

Attributes

Name	Type	Description
`type`	String	Optional. The type of the content. Values: `"text"` (default), `"html"`.

Content

HTML code or string.

Parameters

Specifies the list of parameters that can be passed to the symbol, if any.

Parameters

    Parameter

Parameters encloses one or more Parameter elements. Each parameter element encloses the parameter name followed by an abstract.

Subelements

Cardinality	Element	Usage
1..*	Parameter	Specifies a parameter that can be passed to the symbol.

Parameter

Specifies a parameter that can be passed to the symbol, if any.

Parameter

    Name

    Abstract

Subelements

Cardinality	Element	Usage
1	Name	Specifies the parameter name.
1	Abstract	Specifies a short description of the parameter.

ReturnValue

Specifies the value returned by the symbol, if any.

ReturnValue

    Abstract

Subelements

Cardinality	Element	Usage
1	Abstract	Provides a short description of the value returned by the symbol.

DeclaredIn

Specifies the header and framework in which the symbol is declared, for tokens that describe an API symbol.

// Usage 1:

DeclaredIn []

   HeaderPath

   FrameworkName

// Usage 2:

DeclaredIn [] {filepath}

This element supports two usage patterns:

You can specify the file path to the header in which the symbol is declared and the name of the framework that must be loaded to use that symbol separately, using the HeaderPath and FrameworkName elements, respectively. See Subelements for details.
If the API is not part of a framework, you can specify the path to the header as a string, directly within the DeclaredIn element. See Content for details.

Subelements

Cardinality	Element	Usage
`1`	HeaderPath	Specifies the pathname of the symbol’s header file.
`0..1`	FrameworkName	Specifies the name of the symbol’s framework. Needed only when the symbol is part of a framework.

Content

Pathname. The pathname of the symbol’s header file.

Availability

Specifies availability information related to a product and computer architecture.

Availability [distribution]

   IntroducedInVersion

   RemovedAfterVersion

   DeprecatedInVersion

   DeprecationSummary

See Version Information for usage details.

Attributes

Name	Type	Description
`distribution`	String	Specifies the name of a product, such as `OS X`.

Subelements

Cardinality	Element	Usage
`1..*`	IntroducedInVersion	Specifies a product version and computer architecture in which a symbol was introduced.
`0..*`	RemovedAfterVersion	Specifies a product version and computer architecture in which a symbol was last available.
`0..*`	DeprecatedInVersion	Specifies a product version and computer architecture in which a symbol was deprecated.
`0..1`	DeprecationSummary	Provides information about a symbol whose usage is not recommended.

Path

Specifies a filepath.

Path [] {filepath}

Attributes

None.

Content

Filepath.

HeaderPath

Species the pathname of a header file.

HeaderPath [] {pathname}

Attributes

None.

Content

Pathname.

FrameworkName

Specifies the name of a framework.

FrameworkName [] {string}

Attributes

None.

Content

String.

IntroducedInVersion

Specifies an introduced-in version number.

IntroducedInVersion [cputype,bitsize] {threeTupleNumber}

Attributes

Name	Type	Description
`cputype`	String	Specifies the CPU type to which this version information applies. Values: `ppc` (PowerPC), `i386` (Intel). When unspecified, the version applies to both CPU types.
`bitsize`	Integer	Specifies the CPU bitsize to which this version information applies. Values: `32` (32 bit), `64` (64 bit). When unspecified, the version number applies to both CPU bitsizes.

Content

Period-separated, three-tuple number in the form x.y.z, where x, y, and z are integers. Only the major version number—x—is required.

DeprecatedInVersion

Specifies a deprecated-in version number.

DeprecatedInVersion [cputype,bitsize] {threeTupleNumber}

Attributes

Name	Type	Description
`cputype`	String	Specifies the CPU type to which this version information applies. Values: `ppc` (PowerPC), `i386` (Intel). When unspecified, the version applies to both CPU types.
`bitsize`	Integer	Specifies the CPU bitsize to which this version information applies. Values: `32` (32 bit), `64` (64 bit). When unspecified, the version number applies to both CPU bitsizes.

Content

Period-separated, three-tuple number in the form x.y.z, where x, y, and z are integers. Only the major version number—x—is required.

RemovedAfterVersion

Specifies a removed-after version number.

RemovedAfterVersion [cputype,bitsize] {threeTupleNumber}

Attributes

Name	Type	Description
`cputype`	String	Specifies the CPU type to which this version information applies. Values: `ppc` (PowerPC), `i386` (Intel). When unspecified, the version applies to both CPU types.
`bitsize`	Integer	Specifies the CPU bitsize to which this version information applies. Values: `32` (32 bit), `64` (64 bit). When unspecified, the version number applies to both CPU bitsizes.

Content

Period-separated, three-tuple number in the form x.y.z, where x, y, and z are integers. Only the major version number—x—is required.

DeprecationSummary

Specifies summary information about a symbol whose usage is not recommended.

Use this element to provide additional information about other symbols or technologies that the user should use instead.

DeprecationSummary [type] {HTMLCode|String}

Attributes

Name	Type	Description
`type`	String	Optional. The type of the content. Values: `"text"` (default), `"html"`.

Content

HTML code or string.

RelatedTokens

Defines a list of tokens.

RelatedTokens [title]

   TokenIdentifier

Attributes

Name	Type	Description
`title`	String	Specifies a label for the token list. (Optional)

Subelements

Cardinality	Element	Usage
`1..*`	TokenIdentifier	Identifies a token defined in the documentation set.

RelatedDocuments

Defines a list of documents.

RelatedDocuments []

   NodeRef, URL

Attributes

None.

Subelements

Cardinality	Element	Usage
`1..*`	NodeRef	References a node defined in the nodes file.
	URL	Absolute URL to a document outside the documentation set.

RelatedSampleCode

Defines a list of documents containing sample code.

RelatedSampleCode []

   NodeRef, URL

Attributes

None.

Subelements

Cardinality	Element	Usage
`1..*`	NodeRef	References a node defined in the nodes file.
	URL	Absolute URL to a document outside the documentation set.

File

Identifies an HTML file and a set of tokens that are documented in that file.

File [path,noderef]

   Token

When you use the File element to group token definitions, the individual Token elements inside of the File element cannot contain Path or NodeRef elements.

Attributes

Name	Type	Description
`path`	Filepath	Specifies the path to the HTML file that documents the tokens. See Grouping Tokens by File for details.
`noderef`	Integer	Specifies the `id` of the node to associate with the tokens this element specifies. See Node for more information.

Subelements

Cardinality	Element	Usage
`1..*`	Token	Specifies a token that is documented in the HTML file.

URL

Identifies the location of a document that is outside of the documentation set.

URL [] {URL}

Attributes

None.

Content

URL.

Next Previous