[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] Question about keyref with format="ditamap"
A map is just as referenceable as anything else in DITA: it's merely a
matter of deciding what it means to reference it. One decision is that
there is a correspondence between normal-role topicrefs and addressible
structures in a deliverable table of contents, e.g., <li> elements within
an HTML page.
Map map01.ditamap:
<map>
<topicref id="tr01" navtitle="Topicref 1" href="topic-01.dita">
</map>
Topic topic-01.dita:
<topic id="topicid"><title>Topic 01</title>
<body>
<p>My navigation entry: <xref href="map01.ditamap#tr01"
format="ditamap"/>.</p>
</body>
</topic>
Generated HTML:
toc.html:
<html>
<head>...</head>
<body>
<ul class="navtree">
<li id="tr01"><a href="topic-01.html">Topicref 1</a></li>
<ul>
</body>
</html>
topic-01.html
<html>
<head>...</head>
<body>
<p>My navigation entry: <a href="top.html#tr01>Topicref 1</a>.</p>
</body>
</html>
So to say that "Maps are not referenceable" is ipso facto false: I just
demonstrated that they are in fact meaningfully referencable in a way that
has (arguably) useful (but certainly sensible and generatable) results in
a typical output.
If they are referenceable then if follows that we must provide a way to
reference them. That way *already existed* in DITA 1.1 by direct URL
reference with an element ID fragment identifier. Thus key-based addresses
must provide the equivalent. And they do.
[And of course the larger argument is that DITA doesn't say *at all* what
it means to reference something (we can suggest, offer default behaviors,
describe typical uses, but we cannot prescribe or limit the meaning). All
elements in DITA (with the exception of <title>) may take an ID and
therefore all elements are addressable. We cannot simply say, by fiat,
that it is not meaningful *in all possible cases* to link to something. A
given processor is free to say what processing is does or doesn't provide
for a given reference, but that's up to a processor, not the DITA
standard. The DITA standard merely enables the addressing and linking.]
Cheers,
E.
—————
Eliot Kimber, Owner
Contrext, LLC
http://contrext.com
On 4/14/15, 8:40 AM, "Helfinstine, David" <dhelfinstine@ptc.com> wrote:
>Greetings,
>
>Just to weigh in on implementation of what the possible rule
>interpretation could be. No - no implementation here. Currently there is
>no looking at the format to determine an intent as for other keyrefs it
>is a matter of taking the result of the keyref, merging attributes, and
>then seeing what the combined result is. Saying that a particular format
>needs to be looked at in conjunction with that keyref is currently not
>done.
>
>Also, the example used below is confusing me:
> I had only considered the xref case, that is, making the key-based
>equivalent of <xref href="somemap.ditamap#topicrefid" format="ditamap">.
>
>The href above does not point to a topic, or anything referenceable, but
>to a transient item (the ditamap (my rule is you cannot do that because
>you don't compose a map, you use a map to compose your output) ). Maps
>are not addressable in outputs, or certainly not in all outputs. I would
>strongly discourage this use as this would only lead to a
>non-referenceable item and a broken link. Referencing maps from topics
>implies you know what the map is going to always be used for, and would
>bind the topic to a particular map and intent.
>
>However, when used within a map, the example mentioned is
>straightforward, with a straightforward implementation.
>
><topicref keyref="mybranch"/>
><topicref keys="mybranch"
>href="whatever.ditamap#indirectReferenceToBranch" format="ditamap"/>
>
>I do vote for an example in any case that might address topicrefs and
>keyrefs. I don't know how common it is to have more important paragraphs
>after the examples, but maybe this should be examined (if not now, 2.0)
>to change this. Not that I have read every word, but that paragraph did
>surprise me as well. :-)
>
>Thanks.
>
>-Dave H.
>
>Dave Helfinstine
>dhelfinstine@ptc.com
>
>
>-----Original Message-----
>From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On
>Behalf Of Eliot Kimber
>Sent: Monday, April 13, 2015 5:59 PM
>To: Robert D Anderson; DITA TC
>Subject: Re: [dita] Question about keyref with format="ditamap"
>
>The intent of that rule was to give you same thing you get if you xref to
>a topicref by ID, that is, a reference to the topicref, not to the
>resource the topicref references.
>
>In an HTML environment where there is a table of contents that is the
>literal reflection of the map as a navigation structure, it could make
>sense to literally link to the HTML element in the ToC's HTML page and I
>think that was the use case that was intended for direct-URL references
>to topicrefs by ID.
>
>
>More generally, it allows for a use/mention distinction for references to
>topicrefs by keys: the normal keyref (@format="{format of target
>resource}") gets you the resource ultimately addressed while a
>format="ditamap" keyref gets you the topicref itself.
>
>I had only considered the xref case, that is, making the key-based
>equivalent of <xref href="somemap.ditamap#topicrefid" format="ditamap">.
>
>This is obviously an edge case but I think it's necessary for
>completeness of the addressing mechanism (that is, keyref and ID refs
>need to be exactly equivalent such that any IDREF can be replaced by the
>equivalent keyref and visa versa).
>
>DITA doesn't (and can't) impose any particular semantics on the results
>of addresses, it can only say what it is that you are addressing, in
>terms of the DITA source as authored or the effective document as
>determined by the DITA-defined rules for creating effective documents
>(conref, filtering).
>How you use that thing for some purpose is up to you.
>
>To respond to Robert's analysis: there is a fundamental problem with this
>as the target of reference:
>
><topicref keys="mybranch"
>href="whatever.ditamap#indirectReferenceToBranch" format="ditamap"/>
>
>
>The referenced resource, whatever.ditamap, is referenced outside of any
>use context: it is part of this map? Where is it bound to this map's
>navigation structure? Etc. If I author a keyref-based xref to the key
>"mybranch", what am I addressing?
>
>If the purpose of the key reference is to refer to a specific topicref as
>an object, then the above fails because there is no well-defined context,
>in the current map, as to what is intended.
>
>By contrast, a reference to a key is unambiguous: it can only mean the
>topicref with that key in the context of the key space (key scope) that
>defines the map.
>
>That is, a direct URI xref to a topicref is wrong for exactly the same
>reason that all other direct-URI xrefs to DITA resources are wrong: they
>do not have any well-defined use context and thus are inherently
>ambiguous.
>
>Cheers,
>
>E.
>
>—————
>Eliot Kimber, Owner
>Contrext, LLC
>http://contrext.com
>
>
>
>
>On 4/13/15, 4:17 PM, "Robert D Anderson" <robander@us.ibm.com> wrote:
>
>>Hi,
>>
>>I have a question about some language that is in 1.2 and the 1.3 draft.
>>Specifically, the wording is:
>>
>>
>> A key reference to a topicref element where the linking element
>>specifies a format value of "ditamap" addresses the topicref element
>>itself as though the topicref element had been addressed by ID. In
>>particular, a topicref with a key reference to another topicref and a
>>format value of "ditamap" is a use of the map branch rooted at the
>>referenced topicref. [
>> 1
>><http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/using_keys_to_ad
>>dre
>>ss_dita_elements.html>
>> ]
>>
>>
>>In 1.2 and draft 1.3, it's hidden below an example, which is probably
>>why I hadn't really thought much about it (it looks like part of the
>>simple example). I'm guessing that's true of most other readers.
>>However, it's actually setting out a normative rule that isn't mentioned
>>anywhere else.
>>
>>I think the rule means that I can have the following map, and have the
>>first two key references resolve differently:
>><topicref keyref="mybranch"/>
>><topicref keyref="mybranch" format="ditamap"/> <topicref
>>keys="mybranch" href="someParent.dita">
>> <topicref href="someChild.dita"/>
>></topicref>
>>
>>The first topicref with keyref="mybranch" resolves as a reference to
>>someParent.dita -- this is normal resolution for a key.
>>
>>As I understand the spec, the second topicref works differently because
>>of the format="ditamap" attribute. It is "a use of the map branch
>>rooted at the referenced topicref" -- almost the same as a conref of
>>that branch (not quite the same, because metadata merging between the
>>two is not straightforward).
>>
>>I don't like this for a few reasons. First - I had to read the language
>>many times to work out what it is saying. Second - I don't find the use
>>intuitive. It seems wrong to have @format on the reference trigger an
>>entirely different resolution. Third - I think that if you want an
>>indirect reference to an entire map branch, the following markup is
>>more in line with other keys:
>><topicref keyref="mybranch"/>
>><topicref keys="mybranch"
>>href="whatever.ditamap#indirectReferenceToBranch" format="ditamap"/>
>>
>> In that case, your key would resolve using normal key processing rules
>>-- pulling in both @href and @format -- after which you end up with a
>>reference to whatever map or whatever branch you need:
>><topicref href="whatever.ditamap#indirectReferenceToBranch"
>>format="ditamap"/>
>>
>>Once I worked out the meaning of the current rule, I checked with a
>>couple other people, and it surprised them as well. We're not aware of
>>any key processor that would support the resolution described here. So
>>my questions are:
>>1. Is my interpretation of the rule correct?
>>2. If so, has anybody ever implemented it, or could anybody see
>>implementing it?
>>3. If no implementations, can we remove this language, since alternate
>>markup can get the same result?
>>
>>Thanks -
>>
>>[1]
>>http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/using_keys_to_add
>>res
>>s_dita_elements.html
>>
>>Robert D Anderson
>>IBM Authoring Tools Development
>>Chief Architect, DITA Open Toolkit (http://www.dita-ot.org/)
>
>
>
>---------------------------------------------------------------------
>To unsubscribe from this mail list, you must leave the OASIS TC that
>generates this mail. Follow this link to all your TCs in OASIS at:
>https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]