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

[Eliot Kimber <ekimber@reallysi.com>]

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