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: Re: [dita] Re: Analysis of 1.3 Proposals Related to Linking and Addressing

Thanks Eliot. I also submitted item #13069, and it while it is about keyref, it is not about scoping of variables. The full description of #13069 is:

"Allow specifying a topic ID after a key name. Currently, if you want to reference an element in a composite document via keyref or conkeyref, you must either have a key for each topic in the document, or ensure that there is no other element with the same ID before it in the document."

Currently it is possible to have a conkeyref reliably point to an element within a single-topic document. It is also currently possible to have a conkeyref point to an element within a composite document, however doing so is not reliable unless there is a key defined for each topic, because there is no requirement for element IDs in a composite document to be unique across a composite document. The intention of proposal #13069 is to allow a conkeyref to reliably point to an element within a DITA composite document.

The "scoping of variables" feature that you're describing sounds like it would be best covered by a separate proposal. Does this make sense?


On 2011-06-27, at 11:54 AM, Eliot Kimber wrote:

> Doh! I was looking at 13069 but wrote 13068. 13069 is about keyref.
> By "scoping of variables", what I mean is being able to bind values to
> "variable names" such that the binding is effective in any of the following
> scopes, which represent layers of scoping analogous to variable scopes in
> most programming languages, such that the nearest binding wins:
> - Within the scope of a root map.
> - Within the scope of a submap
> - Within the scope of a specific topicref (subtree of the topicref tree)
> - Within the scope of a specific topic and its subtopics.
> Authors would be able to reference the names and get the values current
> within the reference's scope. There probably needs to be a way to refer to
> specific scopes but I haven't thought through that aspect of any potential
> implementation design.
> The way I've been thinking about this to date is using new specializations
> within <topicmeta> to define name-to-value bindings. These name-to-value
> bindings are "variables" in a way that keys with elements within <topicmeta>
> are not. The binding of variables to scopes is more direct and thus more
> obvious and also more flexible: a topicref can override bindings defined
> within the map as a whole or within an ancestor topicref, topics can
> override bindings defined in topicrefs. The intended behavior follows the
> general rules for metadata cascade from maps to topics. I think this
> approach would much more closely match most author's expectations and
> requirements for variable text in a way that keys, by necessity, do not (and
> cannot).
> The impetus for this idea comes from discussion revolving around Jeremy and
> myself on the DITA Users List triggered by Jeremy's implementation of
> submap-scoped key definitions, to which I objected (and object) strongly.
> However, the requirements that Jeremy is trying to satisfy are certainly
> very real and compelling and something that DITA needs to address sooner
> rather than later, one way or another.
> I implemented a simple version of this idea in DITA for Publishers as an
> experiment and proof of concept but the idea would need to be fleshed out
> quite a bit before it could be presented for submission. On the other hand,
> unlike keys, it doesn't require an architectural change to DITA to be
> implemented because it can be done in a domain module with specific
> semantics that relate variable definitions to variable references and its
> relatively easy to implement using XSLT.
> Anyway, I intend to define a more complete expression of the idea as soon as
> I have time.
> Cheers,
> E.
> On 6/27/11 11:54 AM, "Su-Laine Yeo" <syeo@interelement.ca> wrote:
>> Hi everyone,
>> I'm back on the committee as an independent member. I missed you :)
>> Regarding proposal #13068, which was proposed by me, the main issue that the
>> proposal is intended to fix has nothing to do with keyref. The main issue is
>> that if you have a <topicref> pointing to a topic within a composite document,
>> PDF output pulls in every topic from the composite document. Nobody expects
>> this.
>> Eliot, I don't understand what you mean by 'scoping of "variables" by use
>> context', but I'm pretty sure that it's not what #13068 is.  Is there an
>> earlier discussion that gives more background regarding what you're referring
>> to?
>> Cheers,
>> Su-Laine
>> Su-Laine Yeo
>> Interelement Consulting: Communications and design for technology adoption
>> www.interelement.ca
>> syeo@interelement.ca
>> landline: (604) 451-8805
>> cell: (604) 723-9182
>> Subject: Analysis of 1.3 Proposals Related to Linking and Addressing
>>        ? From: Eliot Kimber <ekimber@reallysi.com>
>>        ? To: dita <dita@lists.oasis-open.org>
>>        ? Date: Tue, 21 Jun 2011 11:30:44 -0500
>> The following proposals are concerned primarily or significantly with
>> linking and addressing.
>> Terminology note:
>> By "linking" I mean establishing relationships among elements. <topicref>
>> and <xref> are examples of links in DITA.
>> By "addressing" I mean the syntax and semantics of pointers to things. URLs
>> and key references are examples of addresses.
>> Linking may use explicit pointers or implicit relationships (queries,
>> functions, heuristics). Addresses may be used for mechanical reasons that
>> are not linking in this sense, such as simply connecting two elements
>> together that serve as a single unit of data.
>> 13001 -- Relative URLs for current topic
>> 13002 -- More sophisticated linking into media objects
>> 13004, 13005 -- Scoping of key definitions/references
>> 13006 -- Override of references
>> 13009 -- Indirection for element-to-element addresses
>> 13022 -- Element-to-element relationship tables
>> 13041 -- Allow specification of root scope for key references
>> 13046 -- Allow @keyref in more places
>> 13058 -- Reference a DITA topic in different contexts in the same map
>> 13068 -- Say that if a topicref points to one topic in a file, a processor
>> may include only that one topic in output.
>> 13069 -- Allow specifying a topic ID after a key name.
>> 13072 -- Keyref to <mapref> element
>> 13079 -- Update keyref definition to make distinctions between elements.
>> These proposals appear to reflect the following general requirements:
>> 1. Addressing convenience: 13001, 13069
>> 2. New addressing features: 13009, 13022
>> 3. Clarify behavior of existing linking and addressing: 13068, 13072, 13079
>> 4. New linking features (new types of relationship): 13002, 13022
>> 5. Key-based addressing enhancements: 13004, 13005, 13041, 13046, 13006(?).
>> In particular, establishing the scope to which a given key definition or key
>> reference applies.
>> 6. Scoping of "variables" by use context: 13068
>> I have put items (5) and (6) last because they are the big ones. Items 1-4
>> seem either relatively non-controversial or likely to be rejected for good
>> reasons (not useful, of too little value, etc.).
>> Items 5 and 6 will require significant architectural thought. I would
>> recommend establishing an ad-hoc workgroup to focus on the key-related
>> proposals.
>> Item 6 is not necessarily about linking or addressing per-se--it's really
>> about scoping of "variables" and one way that has been expressed is through
>> the use of key references to define the content of elements (e.g.,
>> <keyword>, <term>). Key scoping may be one way to address that issue, but
>> it's not the only way and it is not possible for key-based approaches to
>> satisfy all the requirements that I've seen and as I understand them.
>> My considered opinion is that the key-scoping approach suggested by Jeremy
>> Griffith reflects an inappropriate attempt to use keys for something they
>> were not intended for. This is not to say that there aren't other legitimate
>> requirements and use for map-scoped keys, just that "variables" is not one
>> of them.
>> I think we need a new facility for variable scoping and that is what 13068
>> in particular is asking for. I have started working up some ideas but had
>> not yet taken the time to work up a full expression of my ideas. But I will
>> do so now that we are starting on 1.3 in earnest.
>> Cheers,
>> Eliot
>> --
>> Eliot Kimber
>> Senior Solutions Architect
>> "Bringing Strategy, Content, and Technology Together"
>> Main: 512.554.9368
>> www.reallysi.com
>> www.rsuitecms.com

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