Re: [Dita-ot-developer] Handling of xref attributes

[Robert D Anderson <robander@us.ibm.com>]

Hi Paul,

> What should a DITA processing application do with the "scope" and
> "format" attributes? What does the Toolkit do?
The toolkit treats scope="local" as a local file, available for builds. It
considers scope="peer" as part of your information set, but something that
is not necessarily available to you at the moment (such as another
component for your product, which may be authored by somebody else).
Scope="external" is anything outside of your information set.

The format attribute is supposed to describe what you are linking to. If
none is specified, the default is "dita", though I think the toolkit does a
few checks for known extensions before reporting any errors. There are a
few common values, such as dita, html, and pdf. I've also seen txt, zip,
and xml (for generic non-DITA xml). I think it would be great if we
provided a longer list of standard values - though we shouldn't try to list
all known formats. For example, if somebody has an href of
"mailto:something@somewhere";, what is the format of that target? Is it
mailto, email, html, other? I'd be happier if we could point users to a
list of common values.

> What, in particular, is the relationship between these attributes and
> output? For example:
For XHTML builds, scope="external" will cause the link to open in a new
window. If scope=peer or scope=external, we do not try to find the files to
retrieve link text. If the format is not dita, we also do not try to get
link text from the file.

>  * What if topic A links to topic B with scope="local" and format="dita"
> but topic B is not in the map containing topic A? Are the answers for
> print, web and help the same?
For XHTML we would generally try to get the file to find link text;
extensions will be changed to html (or whatever the user specifies); and
the link is created. I'm not sure about PDF at the moment, though I've
heard varying opinions on what the link should be for a DITA file that
doesn't end up as part of the PDF. I'd expect that we do at least retrieve
it to set the link text.

>  * What if topic A is related to topic B through a relationship table,
> but topic B does not occur in the hierarchical part of the map? Are the
> answers for print, web and help the same?
For XHTML, the link will be generated the same as above. Again, I'm not
sure about print, because the topic will not be in the PDF.

>  * What do scope="peer" and scope="external" do for printed output?
What would you say they should do? The target topic is not part of the PDF.
Linking to the DITA source file generally will not work. If the topic is in
another PDF, it may or may not match the name of the topic (b.dita will
probably end up in collection.pdf). Linking to an HTML version of the file
may make sense, or it may not exist. It might make sense to provide all 3
options, and make it easy for users to pick the setting.

>  * Should an application complain if scope="local" but the target file
> cannot be found?
My thought is yes, and we do so today in the toolkit.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit