[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] Question about keyref with format="ditamap"
Actually, title does take @id--forgot to delete that. It's
@conref/@conkeyref that title does not take.
Cheers,
E.
—————
Eliot Kimber, Owner
Contrext, LLC
http://contrext.com
On 4/14/15, 9:11 AM, "Eliot Kimber" <ekimber@contrext.com> wrote:
>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
>>
>
>
>
>---------------------------------------------------------------------
>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]