RE: [dita] conref.dita editorial review

Thanks. Here are some comments and questions about the "general case".

I think Eliot switched to use "key name" in most places where "key" was used.

This sentence:

A key is bound to the resource addressed by the <topicref> or <keydef> in which it is defined.

Might be better as:

A key name is bound to the resource addressed by the <topicref> or <topicref> specialization such as <keydef> in which it is defined.

Or even:

A key name is bound to the resource addressed by the <topicref> or <topicref> specialization in which it is defined.

is rendered as the content of the referenced element.

Shouldn’t “referenced” be “referencing”? This is confusing because a key reference references the key definition and the key definition may reference some other resource, but in this particular case the content is inserted into or replaces content from the element that contains the key reference which is the referencing element.

Bruce asked:

> can a key be bound both to an element in the local <topicmeta>

> and to the resource referenced by the @href attribute in <topicref> or

> <keydef>, at the same time?

In the general key reference case it can. An example would be <navtitle> within <topicmeta> within a key definition that references a non-DITA resource using a URI. In the specific case of conkeyref only the @href resource would be used. And if there were no @href resource, the conref would be “disabled” and regular markup before conref would be used. I tend to forget that key references can cause things to be deleted or removed in addition to being overridden or added.

So in the general case it isn't either/or between an @href resource and <topicmeta> resources. Instead everything contained within the key definition (the <topicref> itself and <topicmeta> elements within the <topicref>) are available. The contents of the key definition are used selectively as appropriate depending on the context in which the key reference occurs.

So a reworded suggestion for the general case might be:

A key name is bound to resources contained within a key definition created using the @keys attribute on a <topicref> or <topicref> specialization in a map. The resources included in the key definition may include items addressed by the @href attribute such as a DITA map or topic, a non-DITA resource such as a graphic, or an object specified by an external URI, other attributes on the <topicref> element, and <topicmeta> content within the key definition such as titles and other metadata. Which resources are actually used depends on the context in which the key reference occurs.

When a key definition includes an element within the <topicmeta> as a resource, that element may be rendered as all or part of the content of the referencing element. By this means, the referenced element can be used as a variable, and the content of the resource provides a way to set the variable's value wherever the key name occurs within the documents aggregated by the map(s).

> -----Original Message-----

> From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com]

> Sent: Wednesday, November 25, 2009 10:10 AM

> To: Ogden, Jeff; Eliot Kimber; Michael Priestley

> Cc: dita

> Subject: RE: [dita] conref.dita editorial review

> No, this is part of an overview of keys in general. It's in the current

> revision of conref.dita in the SVN repository. (Probably that file

> should be renamed sometime.)

> The detailed descriptions are in other topics (such as keyref.dita

> "Keyref (indirect addressing)" in the arch spec, and element-specific

> topics and common/keysandkeyref.dita "Using keys and keyref" in the

> lang

> ref).

> For this overview topic, perhaps it's sufficient to say "the

> information

> provided by the <topicref> or <keydef>, such as a title and metadata"

> plus the follow-on paragraph with more specific information about

> setting variables in <topicmeta>.

> Note that I have added "or <keydef" to the sentence in quotation marks

> above. To keep this in context, the two paragraphs thus now read as

> follows:

> > A key is bound to the resource addressed by the <topicref>

> > or <keydef> in which it is defined. The resource to which

> > a key is bound may be a DITA map or topic, or it may be a

> > non-DITA resource such as a graphic or an object specified

> > by an external URI. If no address is provided, the key is

> > bound to the information provided by the <topicref> or

> > <keydef>, such as a title and metadata.

> >

> > When a key is bound to an element within the <topicmeta>

> > of the key-defining <keydef> or <topicref>, the content of

> > that element is rendered as the content of the referenced

> > element. By this means, the referenced element can be used

> > as a variable, and the content of the bound element in

> > the definition in the map provides a way to set the

> > variable's value wherever that key occurs within the

> > document aggregated by that map.

> > -----Original Message-----

> > From: Ogden, Jeff [mailto:jogden@ptc.com]

> > Sent: Wednesday, November 25, 2009 8:40 AM

> > To: Bruce Nevin (bnevin); Eliot Kimber; Michael Priestley

> > Cc: dita

> > Subject: RE: [dita] conref.dita editorial review

> >

> > Is this description specific to conkeyref or is it a more

> > general description of key references?

> >

> > In the more general key reference case, a key definition may

> > include @href, title, and metadata resources. Which resources

> > are used depends on which resources are applicable in the

> > context in which the key definition is being used and it is

> > possible to use more than one resource to resolve a key reference.

> >

> > I had assumed that only the @href resource would be used to

> > resolve a @conkeyref and that title or metadata resources

> > would be ignored. Is my assumption incorrect?

> >

> > -Jeff

> >

> > > -----Original Message-----

> > > From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com]

> > > Sent: Wednesday, November 25, 2009 12:12 AM

> > > To: Eliot Kimber; Michael Priestley

> > > Cc: dita

> > > Subject: RE: [dita] conref.dita editorial review

> > >

> > > [Just got SVN working again. Thanks, Kris.]

> > >

> > > I think the following revision resolves question 2. Please

> > let me know

> > > if problems remain.

> > >

> > > A key is bound to the resource addressed by the <topicref>

> > > or <keydef> in which it is defined. The resource to which

> > > a key is bound may be a DITA map or topic, or it may be a

> > > non-DITA resource such as a graphic or an object specified

> > > by an external URI. If no address is provided, the key is

> > > bound to the information provided by the <topicref>, such

> > > as a title and metadata.

> > >

> > > When a key is bound to an element within the <topicmeta>

> > > of the key-defining <keydef> or <topicref>, the content of

> > > that element is rendered as the content of the referenced

> > > element. By this means, the referenced element can be used

> > > as a variable, and the content of the bound element in

> > > the definition in the map provides a way to set the

> > > variable's value wherever that key occurs within the

> > > document aggregated by that map.

> > >

> > > Eliot: can a key be bound both to an element in the local

> > <topicmeta>

> > > and to the resource referenced by the @href attribute in

> > <topicref> or

> > > <keydef>, at the same time? If so, could you provide an

> > example? Such

> > > an example is needed in several places in the lang ref (e.g. keydef,

> > Using

> > > keys and keyref) and maybe in the arch spec as well. And if

> > so, then

> > > the above text needs further work.

> > >

> > > > -----Original Message-----

> > > > From: Eliot Kimber [mailto:ekimber@reallysi.com]

> > > > Sent: Tuesday, November 24, 2009 11:53 AM

> > > > To: Michael Priestley; Bruce Nevin (bnevin)

> > > > Cc: dita

> > > > Subject: Re: [dita] conref.dita editorial review

> > > >

> > > > On 11/24/09 10:37 AM, "Michael Priestley" <mpriestl@ca.ibm.com>

> > wrote:

> > > >

> > > > > for 2:

> > > > >

> > > > > 2. The question embedded within the following paragraph:

> > > > >

> > > > > A key is bound to the resource addressed by the

> > > > topicref or keyref

> > > > > in which it is defined, if it is provided.

> > > > > <!--What happens if none is provided? It can't be

> > > > resolved? -->

> > > > > The resource to which a key is bound may be a DITA

> > > > map or topic,

> > > > > or it

> > > > > may be a non-DITA resource such as a graphic or an

> > > > object specified

> > > > > by an external URI.

> > > > >

> > > > > A key is bound to the resource addressed by the topicref in

> > > > which it

> > > > > is defined. If no address is provided, the key is bound to the

> > > > > information provided by the topicref, such as a title and

> > metadata.

> > > >

> > > > This wording implies that the resource/subelement binding is

> > > > exclusive, but in fact it's both. I'm not sure how to

> > express that

> > > > crisply--every time I've tried it comes out convoluted.

> > > >

> > > > That is, a key binds to any resource addressed by the topicref as

> > > > well as to any applicable subelements of the topicref's topicmeta

> > > > child.

> > > >

> > > > Cheers,

> > > >

> > > > Eliot

> > > >

> > > > --

> > > > Eliot Kimber

> > > > Senior Solutions Architect

> > > > "Bringing Strategy, Content, and Technology Together"

> > > > Main: 610.631.6770

> > > > 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_workgr

> > > > oups.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

> >

dita message