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: [dita] Proposal for better default scope/format/type values


As discussed in this meeting's DITA TC meeting, a few weeks ago in the private discussion about Michael's simplified DITA proposal, I laid out some changes to the rules for determining the effective values of @scope, @format, and @type when they aren't explicitly specified on a reference element. The rules I propose are these:

- If the attribute is explicitly specified, used that value
- If the value can be inherited from an ancestor, use that value
- Otherwise, inspect @href

@scope
- scope="external" if the @href is an absolute URI with a scheme of 'http' or 'https'.
- Otherwise scope="local"

NOTE: If @href specifies a relative URI, then scope is always "local" regardless of what the resolved absolute URI would be. For example, if a map is stored on a WebDAV server at http://example.com/docs/myMap.ditamap, and it contains <topicref href="topics/topic1.dita"/>, then the scope of that topicref is "local" even though the resolved absolute URI of the referenced topic has a scheme of 'http'.

@format
- Generally, if the @href specifies a file extension, then the @format matches that extension after conversion to lower case.
- If the extension is 'xml' then format="dita"
- If there is no extension but the @href specifies an absolute URI with a scheme of 'http' or 'https', format="html"
- Otherwise, format="dita"

@type
- If format="dita" and there is no fragment identifier, or the fragment identifier does not contain '/', then type="topic"
- If format="dita" and there is a fragment identifier to a sub-topic ID, @type is blank; processors should use the tag name of the referenced element.
- Otherwise @type has no value.

External Link Text
- When @scope is "external" and a reference does not specify any text (or navtitle in the case of <topicref>), the text should be the value of @href. Processors may, but need not, issue a warning in such cases.

These rules are more complex for processors, but I think they make intuitive sense for authors, and would allow the vast majority of links to be authored with only @href. I can't count the number of times people have asked me why their web links are resulting in warnings because they didn't explicitly set scope="external".

Interestingly, the DITA spec's source has the 'missing scope' problem. See the links in introduction/normative-references.dita, which contains a bunch of web links that are technically scope="local". This can and does trip up some processors. For example, PTC copies those resources to local files relative to the output location and updates the @href to point to the local copies. With the above rules, they'd all be treated as 'external' automatically.

I've entered this as proposal 13107 on the 1.3 triage list.

Chris Nitchie
Senior Software Engineer

T 734.352.2879   F 734.997.0201
E cnitchie@ptc.com

PTC.com




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