Re: [dita] Re: Analysis of 1.3 Proposals Related to Linking andAddressing

[Eliot Kimber <ekimber@reallysi.com>]

Yes--I didn't mean to imply that 13069 was about variable scope, was just
answering your question about what I meant by "variable scope".

On the subject of 13069, I'm not sure I fully understand the issue, since
the only way for a key-based address to point to an element within a topic
is for the key to be bound to the *topic*, not the document that contains
the topic.

That is, keys are bound to topic elements, not documents. The ability to
address a topic *when it is the root or first child of its containing
document* is merely a convenience and is a shortcut for direct addressing of
the topic by ID in the keyref.

Thus, if you want to address an element in a topic via keyref you need to
bind a key to the topic.

Cheers,

E.

On 6/27/11 11:13 PM, "Su-Laine Yeo" <syeo@interelement.ca> wrote:

> 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?
> 
> Cheers,
> Su-Laine
> 
> 
> 
> 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
>>> 
>>> 
> 
> 
> ---------------------------------------------------------------------
> 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
> 

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com