OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Updated 12050 documents


I've reflected (I believe) the changes requested by
Michael and Robert as summarized in [1] and [2] in
the attached files (that use highlighting to show
the changes for easier re-review).

Comments solicited.

paul

[1] http://lists.oasis-open.org/archives/dita/200707/msg00022.html
[2] http://lists.oasis-open.org/archives/dita/200707/msg00023.html
Title: Analysis of DITA href, format, scope, type

Analysis of DITA href, format, scope, and type attributes

2007 May 29-June 18 (pbg); minor edits 2007 June 26-28; revised 2007 July 11 (and changes highlighted thusly)

Arbortext made the following comments for DITA 1.2:

Add format, scope, and type attributes for DITA elements that carry an href or other reference attribute, but which do not have these attributes today.

Change the type attribute on lq, author, and publisher to match the type attribute on most other DITA elements, and add format and scope attributes.

This document provides an analysis of DITA's use (in the latest 1.1 DTDs) of the href, format, scope, and type attributes and provides suggested changes for DITA 1.2. Suggested changes to the Architecture Spec, the Language spec, and the DTDs and XML Schemas are color coded accordingly.

This document is designed to detail specific changes throughout the specs and DTDs/XSDs. See elsewhere for a companion document that summarizes the suggested resulting descriptions of all uses of DITA href, format, scope, and type attributes.

“Standard” definitions for the href, format, scope, and type attributes

Many dita elements have an href attribute with the following “standard” definition:

A hyperlink to an external Web page (URL) or other non-DITA resource, to another DITA topic in the same file or in another file, or to a specific element inside a DITA topic. The format attribute identifies the format of the target. Non-DITA targets use standard URL syntax. DITA content is targetted [sic, should be “targeted”] as follows:

Target elsewhere in the same file:
   href="#topicID"
   href="#topicID/elemID
Target in a different file:
   href="filename.dita#topicID"
   href="fname.dita#topicID/elemID"

Elements inside a topic need to have their location scoped by the containing topic's ID. Only the id of the target element and the topic that contains it matter: id's on any other containing elements (for example an id on the <body> element) are not part of the link syntax.

If the URL contains an ampersand character, the ampersand symbol (&amp;) should be used to indicate that character

We should update the standard definition for href to make it clear that the values are URI references that must follow the URI rules (see RFC 3986). (This has implications for forward and backslashes in names as well as some other special characters such as # and ?.) We should put the updated standard definition under “Chapter 25 Commonly referenced attributes, Complex attribute definitions” and then refer to this definition from all elements with this attribute.

Many dita elements have a format and type attribute whose definition is given by reference to that in the “complex attribute definitions” section.

Many dita elements have a scope attribute with the “standard” definition given under the %topicref-atts; section (though many of them have the definition inline).

Suggested changes

Architecture spec
Chapter 4, IDs and references, Topic IDs

Replace:

The complete identifier for a topic consists of the combination of the URI for the document instance, a separating hash character, and the topic id (as in http://some.org/some/directory/topicfile.xml#topicid). URIs are described in RFC 2396. As is typical with URIs,

with:

The complete identifier for a topic is a URI-reference consisting of the combination of the URI for the document instance, a separating hash character, and the topic id (as in http://some.org/some/directory/topicfile.xml#topicid). URIs and URI references are described in RFC 3986.

Note that certain characters (including, but not limited to, #, ?, \, and space) are not permitted unescaped within URIs. Such characters must be percent-encoding (per RFC 3986) if there is a need to represent them within a string that is a URI. Also note that the “&” (ampersand) and “<” (greater than) characters are not permitted in XML attribute values, so they must be represented by appropriate character or entity references if there is a need to represent them within such a string.

As is typical with URIs,

Chapter 4, IDs and references, Element IDs within a topic

Replace:

The complete identifier for topic content consists of the combination of the complete identifier for the topic,

with:

The complete identifier for topic content is a URI-reference consisting of the combination of the complete identifier for the topic,

Chapter 4, IDs and references, Map IDs and element IDs within a map

Replace:

The complete identifier for a map element consists of the combination of the absolute URI

with:

The complete identifier for a map element is a URI-reference consisting of the combination of the URI

Chapter 4, Content inclusion (conref),

Replace:

The element containing the content reference acts as a placeholder for the referenced element. The identifier for the referenced element must be either absolute or resolvable in the context of the referencing element.

with:

The element containing the content reference acts as a placeholder for the referenced element. The value of the conref attribute is a URI-reference providing the identifier for the referenced element which must be either an absolute reference or a relative reference that is resolvable in the context of the referencing element.

Language spec
Chapter 25 Commonly referenced attributes, Complex attribute definitions, The href attribute

Add the following:

The href attribute

The href attribute is used by many elements to provide a reference to an external Web page or other non-DITA resource, to another DITA topic in the same file or in another file, or to a specific element inside a DITA topic.

The value of a DITA href attribute must be a valid URI-reference [RFC 3986]. It is an error if the value is not a valid URI-reference. An implementation may (but need not) give an error message, and may (but need not) recover from this error condition by attempting to convert the value to a valid URI-reference.

In the case of a reference to a DITA resource, an href value consisting of a URI with no fragment identifier resolves to the document element in the referenced file. If the reference is from a topicref element or a topicref element specialization, all topics (and topic specializations) in the file are referenced. If the reference is not from a topicref element or a topicref element specialization, the reference resolves to the first (or only) topic (or topic specialization) in the file.

An href value consisting of a URI with a fragment identifier must have a valid DITA local identifier as the portion after the hash. A DITA local identifier consists of topicID/elementID for a subelement of a topic and of elementID for topics, maps, and map subelements.

Note that certain characters (including, but not limited to, #, ?, \, and space) are not permitted unescaped within URIs. Such characters must be percent-encoding (per RFC 3986) if there is a need to represent them within a string that is a URI. Also note that the “&” (ampersand) and “<” (greater than) characters are not permitted in XML attribute values, so they must be represented by appropriate character or entity references if there is a need to represent them within such a string. (Some tools may do the required encoding on the user’s behalf while others may require the user to avoid the special characters or perform the encoding manually.)

Chapter 25 Commonly referenced attributes, Complex attribute definitions, The conref attribute, Using conref to refer to a topic

Replace:

The conref value follows the same conventions as HTML for normal file links. To refer to target content in a different file, put the full URL of that topic before the # character.

with:

The conref value is a URI-reference.

Chapter 25 Commonly referenced attributes, Complex attribute definitions, The conref attribute, Using conref to refer to an element within a topic

Replace:

The value of conref is a URI that includes (or consists entirely of) a fragment identifier consisting a number sign (’#’) followed by the ID of the topic that contains the element that is the target of the content reference, a slash (″/″), and the ID of the target element. If the URI consists of only a fragment identifier, the target element must be in the same XML document as the reference.

with:

The value of conref is a URI-reference that includes (or consists entirely of) a fragment identifier consisting a number sign (’#’) followed by the ID of the topic that contains the element that is the target of the content reference, a slash (″/″), and the ID of the target element. If the URI-reference consists of only a fragment identifier, the target element must be in the same XML document as the reference.

Chapter 25 Commonly referenced attributes, Complex attribute definitions, The conref attribute, Using conref to refer to an element within a map

Replace:

Within a map, the conref attribute references an equivalent element in the same map or another map. The value of conref is a URI that includes (or consists entirely of) a fragment identifier consisting of the number sign (’#’) followed by the ID of the target element. If the URI consists of only a fragment identifier, the target element must be in the same XML document as the reference.

with:

Within a map, the conref attribute references an equivalent element in the same map or another map. The value of conref is a URI-reference that includes (or consists entirely of) a fragment identifier consisting of the number sign (’#’) followed by the ID of the target element. If the URI-reference consists of only a fragment identifier, the target element must be in the same XML document as the reference.

Chapter 25 Commonly referenced attributes, Complex attribute definitions, The type attribute

Under “Using type on a linking element”, replace the second paragraph that currently reads:

When the type attribute is unspecified, it should be determined by inspecting the target if possible. If the target cannot be inspected for some reason, the value should default to ″topic″.

with the following:

If not explicitly specified on an element, the type attribute inherits its value from ancestors. If there is no explicit value for the type attribute on any ancestor, a default value of “topic” is used. During output processing for references to DITA topics (format="dita"), it is an error if the actual type of a DITA topic and the explicit, inherited, or default value for the type attribute are not the same as or a specialization of the type attribute value. In this case, an implementation may (but need not) give an error message, and may (but need not) recover from this error condition by using the type attribute value. During output processing for references to non-DITA objects (i.e., either scope is not “local” or format is neither “dita” nor “ditamap”) or other cases where the type of the referenced item cannot be determined from the item itself, the explicit, inherited, or default value for the type attribute is used without any validation. When a referencing element is first added to or updated in a document, DITA aware editors may, but are not required to, set the type attribute value based on the actual type of a referenced DITA topic.

After the mention of the “(no value)” option, add:

-dita-use-conref-target
See Using the -dita-use-conref-target value for more information.
Chapter 25 Commonly referenced attributes, Complex attribute definitions, The scope attribute

Add the following (after the description of “The format attribute”):

The scope attribute

The scope attribute identifies the closeness of the relationship between the current document and the target resource.

  • Set scope to local when the resource is part of the current set of content.
  • Set scope to peer when the resource is part of the current set of content but is not accessible at build time. An implementation may choose to open such resources in the same browser window to distinguish them from those with scope set to external.
  • Set scope to external when the resource is not part of the current information set and should open in a new browser window.
  • See “Using the -dita-use-conref-target value” for more information on -dita-use-conref-target.

If no value is specified, but the attribute is specified on an ancestor within a map or within the related-links section, the value will inherit from the closest ancestor. The processing default is local.

Elements using the “standard” definitions of href, format, scope, and type

The following elements all have the href, format, scope, and type attributes defined using the above mentioned “standard” definitions:

Suggested changes

Language spec

For each of the following elements:

  • xref, link, data-about, data
  • [deleted the list of specializations of topicref]
  • the following specializations of data: approved, bookchangehistory, bookevent, bookeventtype, bookid, booknumber, bookowner, bookpartno, bookrestriction, bookrights, copyrfirst, copyrlast, edited, edition, isbn, maintainer, organization, person, printlocation, published, publishtype, reviewed, tested, volume, contactnumber, contactnumbers, emailaddress, emailaddresses, firstname, generationidentifier, honorific, lastname, middlename, namedetails, organizationinfo, otherinfo, personinfo, personname, url, urls

replace the Description for the href attribute in the element's table with:

Provides a reference to a resource. See “The href attribute” for detailed information on supported values and processing implications.

For each of the following elements:

  • xref, link, data-about, data
  • the following specializations of data: approved, bookchangehistory, bookevent, bookeventtype, bookid, booknumber, bookowner, bookpartno, bookrestriction, bookrights, copyrfirst, copyrlast, edited, edition, isbn, maintainer, organization, person, printlocation, published, publishtype, reviewed, tested, volume, contactnumber, contactnumbers, emailaddress, emailaddresses, firstname, generationidentifier, honorific, lastname, middlename, namedetails, organizationinfo, otherinfo, personinfo, personname, url, urls

replace the Description for the scope attribute in the element's table with:

The scope attribute identifies the closeness of the relationship between the current document and the target resource. See “The scope attribute” for details on supported values.

For each of the following elements (specializations of topicref):

  • amendments, appendix, bookabstract, chapter, colophon, dedication, draftintro, notices, part, preface

replace the Description for the href attribute in the element's table with (the same as that for topicref):

A pointer to the resource represented by the <topicref>. See “The href attribute” for detailed information on supported values and processing implications. References to DITA content cannot be below the topic level: that is, you cannot reference individual elements inside a topic. References to content other than DITA topics should use the format attribute to identify the kind of resource being referenced.

Chapter 25 Commonly referenced attributes, %topicref-atts; and %topicref-atts-no-toc;

Replace the Description for the scope attribute in this section's table with:

The scope attribute identifies the closeness of the relationship between the current document and the target resource. See “The scope attribute” for details on supported values.

Elements using the “standard” definitions of format, scope, and type but with Alternative href definition #1 for the href attribute

Several elements use an alternative definition for the href attribute.

Alternative href definition #1 is:

Points to a manual listing for the current element. If no href is specified, processors may choose to generate an appropriate listing for this element. All of the book listings operate in a similar manner; for example, <toc href="toc.dita"/> points to a topic which contains a manual table of contents, while <toc/> indicates that a processor should generate the table of contents. References to content other than DITA topics should use the format attribute to identify the kind of resource being referenced.

The following elements all have the format, scope, and type attributes defined using the above mentioned “standard” definitions and have an href attribute that uses Alternative href definition #1:

Suggested changes

Language spec

For each of the following elements:

  • abbrevlist, bibliolist, booklist, figurelist, glossarylist, indexlist, tablelist, toc, trademarklist

replace the Description for the href attribute in the element's table with:

Points to a manual listing for the current element. See “The href attribute” for detailed information on supported values and processing implications. If no href is specified, processors may choose to generate an appropriate listing for this element. All of the book listings operate in a similar manner; for example, <toc href="toc.dita"/> points to a topic which contains a manual table of contents, while <toc/> indicates that a processor should generate the table of contents. References to content other than DITA topics should use the format attribute to identify the kind of resource being referenced.

Element using the “standard” definitions of format, scope, and type but with Alternative href definition #2 for the href attribute

The topicref element has yet a different definition for href (even though most of its specializations use either the standard definition or Alternative href definition #1).

The topicref element has the format, scope, and type attributes defined using the above mentioned “standard” definitions and have an href attribute that uses Alternative href definition #2:

A pointer to the resource represented by the <topicref>. References to DITA content cannot be below the topic level: that is, you cannot reference individual elements inside a topic. References to content other than DITA topics should use the format attribute to identify the kind of resource being referenced.

Suggested changes

Language spec

For the topicref element, replace the Description for the href attribute in the element's table with:

A pointer to the resource represented by the <topicref>. See “The href attribute” for detailed information on supported values and processing implications. References to DITA content cannot be below the topic level: that is, you cannot reference individual elements inside a topic. References to content other than DITA topics should use the format attribute to identify the kind of resource being referenced.

Elements using the “standard” definitions of format, scope, and type (but without an href attribute)

The following elements all have the format, scope, and type attributes defined using the above mentioned “standard” definitions (presumably for the purpose of being inherited by descendants) but no href attribute:

No suggested changes.

Elements with an href attribute with the standard definition and with no format, scope, or type attributes

The following elements each have an href attribute using the “standard” definition but no format, scope, or type attribute (despite the fact that the description of the href attribute for these elements refers to the format attribute):

Suggested changes

Language spec

For the publisher and publisherinformation elements, add rows in the table for the format, scope, and type attributes with the (now) “standard” entries, that is:

type: Describes the target of a cross-reference. See “The type attribute” for detailed information on supported values and processing implications.

format: The format attribute identifies the format of the resource being cross referenced. See “The format attribute” for details on supported values.

scope: The scope attribute identifies the closeness of the relationship between the current document and the target resource. See “The scope attribute” for details on supported values.

Also, replace the Description for the href attribute in the tables for these two elements with:

Provides a reference to a resource. See “The href attribute” for detailed information on supported values and processing implications.

DTDs/XSDs

Add the format, scope, and type attributes to the publisher and publisherinformation elements.

Elements with an href attribute with a different definition and with no format, scope, or type attributes

The following elements each have an href attribute with a different definition and no format, scope, or type attribute. In each case, the definition of the href attribute is given.

image

The href attribute definition is:

The relative path or URL to the image. The href attribute uses conventional URL syntax to point to the resource: href="../images/construction.gif"

Suggested changes
Language spec

Replace the Description for the href attribute in the table for the image element with:

Provides a reference to the image. See “The href attribute” for detailed information on supported values and processing implications.

Replace the Description for the longdescref attribute in the table for the image element with:

A reference to a textual description of the graphic or object. This attribute supports creating accessible content. See “The href attribute” for detailed information on supported values and processing implications. NOTE: This attribute is deprecated in favor of the longdescref subelement to this element.

For the image element, add a row in the table for the scope attribute with the (now) “standard” entry, that is:

scope: The scope attribute identifies the closeness of the relationship between the current document and the target image resource. See “The scope attribute” for details on supported values.

[Deleted the suggested addition of the longdescformat and longdescscope attributes.]

[Note: Proposal 12050a will be adding a longdescref subelement to this element.]

DIDs/XSDs

Add the scope, longdescformat , and longdescscope attributes to the image element.

source

The href attribute definition is:

A pointer to the external resource from which the present resource is derived. The href attribute identifies the destination of the resource using conventional URL syntax.

Suggested changes
Language spec

For the source element, add rows in the table for the format, scope, and type attributes with the (now) “standard” entries, that is:

type: Describes the target of a cross-reference. See “The type attribute” for detailed information on supported values and processing implications.

format: The format attribute identifies the format of the resource being cross referenced. See “The format attribute” for details on supported values.

scope: The scope attribute identifies the closeness of the relationship between the current document and the target resource. See “The scope attribute” for details on supported values.

Also, replace the Description for the href attribute in the tables for this element with:

Provides a reference to a resource from which the present resource is derived. See “The href attribute” for detailed information on supported values and processing implications.

DTDs/XSDs

Add the format, scope, and type attributes to the source element.

fragref

The href attribute definition is:

A reference to a syntax diagram fragment element. The referenced fragment should be in the same diagram as the fragref element. The href attribute uses conventional URL syntax to point to the ID of the matching syntax diagram fragment: href="#topicid/fragmentid"

Suggested changes
Language spec

Replace the Description for the href attribute in the table for the fragref element with:

A reference to a syntax diagram fragment element. The referenced fragment must be in the same diagram as the fragref element. See “The href attribute” for detailed information on supported values and processing implications. (Processing assumes the equivalent of scope="local" and format="dita".)

synnoteref

The href attribute definition is:

Points to the target syntax note (<synnote>), which must be in the same syntax diagram. Use standard DITA href syntax for targetting the element: href="#topicid/synnoteid"

Suggested changes
Language spec

Replace the Description for the href attribute in the table for the synnoteref element with:

A reference to the target syntax note (<synnote>) element. The referenced syntax note must be in the same syntax diagram as the synnoteref element. See “The href attribute” for detailed information on supported values and processing implications. (Processing assumes the equivalent of scope="local" and format="dita".)

Elements with an href attribute but with at least one of format, scope, or type attributes missing or with a non-standard definition

lq

The lq element has href and type (which is defined differently from most other cases) and no format or scope.

Its href attribute definition is:

A hyperlink representing a bibliographic citation to resources that can be accessed by browsers (meaning a URL). The href attribute identifies the destination of the resource using conventional URL syntax.

Its type definition is:

Indicates the location of the source of the quote. Note that this differs from the type attribute on many other DITA elements. Allowable values are:

external
the href is to a Web site
internal
the href is to a DITA topic
bibliographic
the href is to a specialized bibliographic topic. There is not currently a standard bibliographic topic type at OASIS.
-dita-use-conref-target
See Using the -dita-use-conref-target value for more information.
Suggested changes

For the lq element, add a row in the table for the scope and format attributes with the (now) “standard” entries but with some additions as follows:

scope : The scope attribute identifies the closeness of the relationship between the current document and the target resource. See “The scope attribute” for details on supported values. In the absence of an explicit specification for the scope attribute, an explicit value of type="external" implies scope="external".

format: The format attribute identifies the format of the resource being cross referenced. See “The format attribute” for details on supported values. In the absence of an explicit specification for the format attribute, an explicit value of type="internal" implies format="dita".

In the description of the type attribute, change:

Indicates the location of the source of the quote. Note that this differs from the type attribute on many other DITA elements. Allowable values are:

external
the href is to a Web site
internal
the href is to a DITA topic
bibliographic
the href is to a specialized bibliographic topic. There is not currently a standard bibliographic topic type at OASIS.
-dita-use-conref-target
See Using the -dita-use-conref-target value for more information.

to:

Indicates the location of the source of the quote. Note that this allows some values in addition to those allowed on the type attribute on many other DITA elements. See “The type attribute” for detailed information on the usual supported values and processing implications. In addition, the following attribute values are allowed (but deprecated) for backward compatibility:

external
the href is to a Web site. This value is deprecated in favor of use of the scope and format attributes.
internal
the href is to a DITA topic. This value is deprecated in favor of use of the scope and format attributes.

When either the scope or format attribute has an explicit setting, a type attribute value of external or internal is ignored.

Replace the Description for the href attribute in the table for the lq element with the (now standard):

Provides a reference to a resource. See “The href attribute” for detailed information on supported values and processing implications.

author

The author element has href (the “standard” DITA definition) and type (which is defined differently from most other cases) and no format or scope (despite the fact that the description of the href attribute for this element refers to the format attribute). It is not clear why the author element should be substantially different from an element such as the publisher one (except, perhaps, for its type attribute values).

Its type attribute definition is:

Indicates the primary author of the content. Note that this differs from the type attribute on many other DITA elements. Allowable values are:

creator
The primary or original author of the content.
contributor
An additional author who is not primary.
-dita-use-conref-target
See Using the -dita-use-conref-target value for more information.
Suggested changes
Language spec

For the author element, add rows in the table for the format and scope attributes with the (now) “standard” entries, that is:

format: The format attribute identifies the format of the resource being cross referenced. See “The format attribute” for details on supported values.

scope: The scope attribute identifies the closeness of the relationship between the current document and the target resource. See “The scope attribute” for details on supported values.

Also, replace the Description for the href attribute in the tables for this element with:

Provides a reference to a resource. See “The href attribute” for detailed information on supported values and processing implications.

Replace the Description for the type attribute with:

type: Describes the target of a cross-reference. See “The type attribute” for detailed information on supported values and processing implications. The following values are also recognized for the author element (and its specializations):

creator
The primary or original author of the content.
contributor
An additional author who is not primary.
DTDs/XSDs

Add the format and scope attributes to the author element.

Change author's type attribute to be CDATA.

authorinformation

The authorinformation element (specialization of author) has href (the “standard” DITA definition) and type (the “standard” definition—not that for author), but no format or scope.

Suggested changes
Language spec

For the authorinformation element, add rows in the table for the format and scope attributes with the (now) “standard” entries, that is:

format: The format attribute identifies the format of the resource being cross referenced. See “The format attribute” for details on supported values.

scope: The scope attribute identifies the closeness of the relationship between the current document and the target resource. See “The scope attribute” for details on supported values.

Also, replace the Description for the href attribute in the tables for this element with:

Provides a reference to a resource. See “The href attribute” for detailed information on supported values and processing implications.

Replace the Description for the type attribute with:

type: Describes the target of a cross-reference. See “The type attribute” for detailed information on supported values and processing implications. The following values are also recognized for the author element (and its specializations):

creator
The primary or original author of the content.
contributor
An additional author who is not primary.
DTDs/XSDs

Add the format and scope attributes to the authorinformation element.

Change authorinformation's type attribute to be CDATA.

Elements without an href attribute, but with an href-like attribute

map

The map element has type, scope, format (topic-ref-atts) using the standard definitions plus an anchorref attribute.

The anchorref attribute definition is:

Identifies a location within another map file where this map will be anchored (added at runtime, using Eclipse navigation integration). For example, anchorref="map1.ditamap/a1" causes this map to be pulled into the location of the anchor point a1 in the other map1.ditamap.

No suggested changes.

navref

The navref element has no type, format, or scope attribute. It does have a mapref attribute.

The mapref attribute definition is:

Specifies the URL (local filename, at least) of the map file to reference. It may point to a DITA map, or to a file that is appropriate for your output format (such as XML TOC file for Eclipse output).

No suggested changes.

bookmap

The bookmap element (a specialization of map) has type, scope, format (topic-ref-atts) plus an anchorref attribute whose definition is the same as that for the map element's anchorref attribute.

No suggested changes.

Other elements with a non-standard type attribute and/or a non-standard href-like attribute

note

The note element has a type attribute (no format or scope or href) with its own note-specific definition.

No suggested changes.

object

The object element has classid and data (both of which can be URIs) and type and codetype. The type attribute has its own object-specific definition.

Suggested changes

Replace:

DITA's <object> element corresponds to the HTML <object> element.

with:

DITA's <object> element corresponds to the HTML <object> element, and its attributes' semantics derive from their HTML definitions. For example, the type attribute differs from the type attribute on many other DITA elements.

[Note: Proposal 12050a will be adding a longdescref subelement to this element.]

param

The param element has a value attribute which (if its valuetype attribute value is ref) could be a URI. It also has a type attribute with its own param-specific definition.

No suggested changes.

This element is comparable to the XHMTL <param> element.

Suggested changes

Replace:

This element is comparable to the XHMTL <param> element.

with:

This element is comparable to the XHMTL <param> element, and its attributes' semantics derive from their HTML definitions. For example, the type attribute differs from the type attribute on many other DITA elements.

In the description of the valuetype attribute's “ref” value, replace:

A value of ref indicates that the value of valuetype is a URL that designates a resource where run-time values are stored.

with:

A value of ref indicates that the value of the value attribute is a URL that designates a resource where run-time values are stored.

copyright

The copyright element has a type attribute (no format or scope or href) with its own copyright-specific definition.

No suggested changes.

Title: Summary of suggested 1.2 descriptions of DITA href, format, scope, type

Summary of suggested 1.2 descriptions of DITA href, format, scope, type

2007 June 14 (pbg); minor edits 2007 June 26-28; revised 2007 July 11 (and changes highlighted thusly)

Arbortext made the following comments for DITA 1.2:

Add format, scope, and type attributes for DITA elements that carry an href or other reference attribute, but which do not have these attributes today.

Change the type attribute on lq, author, and publisher to match the type attribute on most other DITA elements, and add format and scope attributes.

This document attempts to summarize the suggested descriptions of the href , format, scope, and type attributes on all elements for DITA 1.2. See elsewhere for its companion document that gives the analysis providing the background for this suggestion and for the specific specification and schema changes needed to implement this suggestion. I've attempted to use color to help highlight the differences in attribute definitions from the “standard” ones (note: this does not highlight the changes between DITA 1.1 and 1.2—see the other document mentioned in the previous sentence for suggested changes). I have also included some “Notes” in this document using colored text to highlight them that attempt to clarify for each of the various elements with an href attribute what kinds of resources can be referenced by that element. I have not yet updated this document's companion document with specific suggestions for specification changes that give this information. (I am thinking of developing a table that provides this information, perhaps in the architecture specification, but I haven't done that yet.)

“Standard” definitions for the href, format, scope, and type attributes

In general, the description for these various attributes for each element will refer to the “standard” description after providing any element-specific information.

The standard description for the href attribute will be:

The href attribute

The href attribute is used by many elements to provide a reference to an external Web page or other non-DITA resource, to another DITA topic in the same file or in another file, or to a specific element inside a DITA topic.

The value of a DITA href attribute must be a valid URI-reference [RFC 3986]. It is an error if the value is not a valid URI-reference. An implementation may (but need not) give an error message, and may (but need not) recover from this error condition by attempting to convert the value to a valid URI-reference.

In the case of a reference to a DITA resource, an href value consisting of a URI with no fragment identifier resolves to the document element in the referenced file. If the reference is from a topicref element or a topicref element specialization, all topics (and topic specializations) in the file are referenced. If the reference is not from a topicref element or a topicref element specialization, the reference resolves to the first (or only) topic (or topic specialization) in the file.

An href value consisting of a URI with a fragment identifier must have a valid DITA local identifier as the portion after the hash. A DITA local identifier consists of topicID/elementID for a subelement of a topic and of elementID for topics, maps, and map subelements.

Note that certain characters (including, but not limited to, #, ?, \, and space) are not permitted unescaped within URIs. Such characters must be percent-encoding (per RFC 3986) if there is a need to represent them within a string that is a URI. Also note that the “&” (ampersand) and “<” (greater than) characters are not permitted in XML attribute values, so they must be represented by appropriate character or entity references if there is a need to represent them within such a string. (Some tools may do the required encoding on the user’s behalf while others may require the user to avoid the special characters or perform the encoding manually.)

The standard description for the scope attribute will be:

The scope attribute

The scope attribute identifies the closeness of the relationship between the current document and the target resource.

  • Set scope to local when the resource is part of the current set of content.
  • Set scope to peer when the resource is part of the current set of content but is not accessible at build time. An implementation may choose to open such resources in the same browser window to distinguish them from those with scope set to external.
  • Set scope to external when the resource is not part of the current information set and should open in a new browser window.
  • See “Using the -dita-use-conref-target value” for more information on -dita-use-conref-target.

If no value is specified, but the attribute is specified on an ancestor within a map or within the related-links section, the value will inherit from the closest ancestor. The processing default is local.

The standard description for the type attribute will be as currently given in DITA 1.1 “Chapter 25 Commonly referenced attributes, Complex attribute definitions, The type attribute” with the following for the “default value” paragraph:

If not explicitly specified on an element, the type attribute inherits its value from ancestors. If there is no explicit value for the type attribute on any ancestor, a default value of “topic” is used. During output processing for references to DITA topics (format="dita"), it is an error if the actual type of a DITA topic and the explicit, inherited, or default value for the type attribute are not the same as or a specialization of the type attribute value. In this case, an implementation may (but need not) give an error message, and may (but need not) recover from this error condition by using the type attribute value. During output processing for references to non-DITA objects (i.e., either scope is not “local” or format is neither “dita” nor “ditamap”) or other cases where the type of the referenced item cannot be determined from the item itself, the explicit, inherited, or default value for the type attribute is used without any validation. When a referencing element is first added to or updated in a document, DITA aware editors may, but are not required to, set the type attribute value based on the actual type of a referenced DITA topic.

and the additional value description of:

-dita-use-conref-target
See Using the -dita-use-conref-target value for more information.

The standard description for the format attribute will be as currently given in DITA 1.1 “Chapter 25 Commonly referenced attributes, Complex attribute definitions, The format attribute”.

Elements using the “standard” definitions of href, format, scope, and type

The following elements all had in DITA 1.1 the href, format, scope, and type attributes defined using the “standard” definitions:

The following elements should, in DITA 1.2, also use the same standard definitions:

Attribute descriptions

href
Provides a reference to a resource. See “The href attribute” for detailed information on supported values and processing implications.
type
Describes the target of a cross-reference. See “The type attribute” for detailed information on supported values and processing implications.
format
The format attribute identifies the format of the resource being cross referenced. See “The format attribute” for details on supported values.
scope
The scope attribute identifies the closeness of the relationship between the current document and the target resource. See “The scope attribute” for details on supported values.

Elements using the “standard” definitions of format, scope, and type but with Alternative href definition #1 for the href attribute

The following specializations of topicref have a slightly different description for the href attribute:

Attribute descriptions

href
Points to a manual listing for the current element. See “The href attribute” for detailed information on supported values and processing implications. If no href is specified, processors may choose to generate an appropriate listing for this element. All of the book listings operate in a similar manner; for example, <toc href="toc.dita"/> points to a topic which contains a manual table of contents, while <toc/> indicates that a processor should generate the table of contents. References to content other than DITA topics should use the format attribute to identify the kind of resource being referenced. Reference to DITA maps, DITA topics, and non-DITA content.
type
Describes the target of a cross-reference. See “The type attribute” for detailed information on supported values and processing implications.
format
The format attribute identifies the format of the resource being cross referenced. See “The format attribute” for details on supported values.
scope
The scope attribute identifies the closeness of the relationship between the current document and the target resource. See “The scope attribute” for details on supported values.

Elements using the “standard” definitions of format, scope, and type but with Alternative href definition #2 for the href attribute

The topicref element and its specializations have yet a slightly different definition for href. The elements in question are:

Attribute descriptions

href
A pointer to the resource represented by the <topicref>. See “The href attribute” for detailed information on supported values and processing implications. References to DITA content cannot be below the topic level: that is, you cannot reference individual elements inside a topic. References to content other than DITA topics should use the format attribute to identify the kind of resource being referenced. Reference to DITA maps, DITA topics, and non-DITA content.
type
Describes the target of a cross-reference. See “The type attribute” for detailed information on supported values and processing implications.
format
The format attribute identifies the format of the resource being cross referenced. See “The format attribute” for details on supported values.
scope
The scope attribute identifies the closeness of the relationship between the current document and the target resource. See “The scope attribute” for details on supported values.

image

Attribute descriptions

href
Provides a reference to the image. See “The href attribute” for detailed information on supported values and processing implications. Reference to graphics file.
scope
The scope attribute identifies the closeness of the relationship between the current document and the target resource. See “The scope attribute” for details on supported values.
longdescref
A reference to a textual description of the graphic or object. This attribute supports creating accessible content. See “The href attribute” for detailed information on supported values and processing implications. NOTE: This attribute is deprecated in favor of the longdescref subelement to this element.

[Deleted the suggested addition of the longdescformat and longdescscope attributes.]

(No type or format attributes.)

[Note: Proposal 12050a will be adding a longdescref subelement to this element.]

source

Attribute descriptions

href
Provides a reference to a resource from which the present resource is derived.. See “The href attribute” for detailed information on supported values and processing implications. Reference to DITA topics, DITA sub-topic (element), and non-DITA content.
type
Describes the target of a cross-reference. See “The type attribute” for detailed information on supported values and processing implications.
format
The format attribute identifies the format of the resource being cross referenced. See “The format attribute” for details on supported values.
scope
The scope attribute identifies the closeness of the relationship between the current document and the target resource. See “The scope attribute” for details on supported values.

fragref

Attribute descriptions

href
A reference to a syntax diagram fragment element. The referenced fragment must be in the same diagram as the fragref element. See “The href attribute” for detailed information on supported values and processing implications. (Processing assumes the equivalent of scope="local" and format="dita".) Reference to a DITA fragment element.

(No type, format, or scope attributes.)

synnoteref

Attribute descriptions

href
A reference to the target syntax note (<synnote>) element. The referenced syntax note must be in the same syntax diagram as the synnoteref element. See “The href attribute” for detailed information on supported values and processing implications. (Processing assumes the equivalent of scope="local" and format="dita".) Reference to a DITA syntax note element in the same topic similar to a footnote reference.

(No type, format, or scope attributes.)

lq

Attribute descriptions

href
Provides a reference to a resource. See “The href attribute” for detailed information on supported values and processing implications. Reference to DITA topics, DITA sub-topic (element), and non-DITA content.
type

Indicates the location of the source of the quote. Note that this allows some values in addition to those allowed on the type attribute on many other DITA elements. See “The type attribute” for detailed information on the usual supported values and processing implications. In addition, the following attribute values are allowed (but deprecated) for backward compatibility:

external
the href is to a Web site. This value is deprecated in favor of use of the scope and format attributes.
internal
the href is to a DITA topic. This value is deprecated in favor of use of the scope and format attributes.

When either the scope or format attribute has an explicit setting, a type attribute value of external or internal is ignored.

format
The format attribute identifies the format of the resource being cross referenced. See “The format attribute” for details on supported values. In the absence of an explicit specification for the format attribute, an explicit value of type="internal" implies format="dita".
scope
The scope attribute identifies the closeness of the relationship between the current document and the target resource. See “The scope attribute” for details on supported values. In the absence of an explicit specification for the scope attribute, an explicit value of type="external" implies scope="external".

author, authorinformation

Attribute descriptions

href
Provides a reference to a resource. See “The href attribute” for detailed information on supported values and processing implications. Reference to DITA topics, DITA sub-topic (element), and non-DITA content.
type

Describes the target of a cross-reference. See “The type attribute” for detailed information on supported values and processing implications. The following values are also recognized for the author element (and its specializations):

creator
The primary or original author of the content.
contributor
An additional author who is not primary.
format
The format attribute identifies the format of the resource being cross referenced. See “The format attribute” for details on supported values.
scope
The scope attribute identifies the closeness of the relationship between the current document and the target resource. See “The scope attribute” for details on supported values.

Other elements with a type and/or an href-like attribute

No non-trivial href-related changes are suggested for these; they are just listed here for comparison and completeness for now—I'll probably delete this section at some later point before finalizing this document.

map

The map element has type, scope, format (topic-ref-atts) using the standard definitions plus an anchorref attribute.

navref

The navref element has no type, format, or scope attribute. It does have a mapref attribute.

bookmap

The bookmap element (a specialization of map) has type, scope, format (topic-ref-atts) plus an anchorref attribute whose definition is the same as that for the map element's anchorref attribute.

note

The note element has a type attribute (no format or scope or href) with its own note-specific definition.

object

The object element has classid and data (both of which can be URIs) and type and codetype. The type attribute has its own object-specific definition.

[Note: Proposal 12050a will be adding a longdescref subelement to this element.]

param

The param element has a value attribute which (if its valuetype attribute value is ref) could be a URI. It also has a type attribute with its own param-specific definition.

copyright

The copyright element has a type attribute (no format or scope or href) with its own copyright-specific definition.



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]