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] Playing Devil's Advocate with Keys


Hi there,

I don't think that the wording in the Key Ref feature article helps
clarify this.

"The keydef element can be used in combination with the keyword elements
in a ditamap to define and set "variables"...

Perhaps we should update the article to reflect David's points?
Amber

-----Original Message-----
From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On
Behalf Of David J. B. Hollis
Sent: Tuesday, May 19, 2015 1:27 AM
To: DITA TC
Subject: [dita] Playing Devil's Advocate with Keys

Hi Kris, et. al.

I'm aware that there's a key review in progress, and this post will
hopefully support that. I do appreciate, however, that this is somewhat
left-field.

At a certain recent contract, I worked with a number of very intelligent
authors, many of whom were from an electronic engineering background. Some
were quite capable of creating conversion scripts that took machine
readable content, and turned it into DITA.

Now, two of these guys, totally independently, came to the same conclusion
about keys. And that was that it had to be the keyword element that is the
means of adding key content to a topic.

Now, OK, to the 'DITA-rati', that is completely bonkers. But, thinking
about it, it does make some sense.

But, I'll pause and explain that they both had the same blind spot when it
came to DITA. They simply didn't want to read the DITA Spec., nor the very
useful Adoption TC article about keys. As far as they were concerned, that
was not their job, it should be someone else who reads this stuff, and
then spoon feeds them what they need to do. OK, to some extent I
understand that, except that they were part of the guinea pig team and
project, and so really had no excuses. I actually had to badger one of
them for some time before they would read the article!

So, if someone comes to DITA with little or no reading, training or
understanding, how might they approach keys?

Well, they start with the keydef element. That is part of the map, and it
points to a topic. OK - fine. Create a topic with the referable content.

OK, so topic with content, and keydef in a map. What's next?

Well, keydef is an element, so what is the corresponding element that puts
the keydef content into a topic. Ahh, keyword! Obviously!

So, that's what they did, or tried to do. And, of course, it didn't work.

For the TC, is there anything that needs to be done, and possibly
incorporated into the Spec.?

Some thoughts:

1. Somehow make it abundantly clear that DITA allows referable content
from any element in one topic to the same element in another topic. There
is no 'special' element. All elements are equal, and can access the same
keys mechanism.

2. Because referenced content works for any element, the keys mechanism is
primarily attribute, not element based. The only exception being the
keydef element.

3. A note as part of the keyword element description, that it is NOT part
of the keys mechanism. It is merely an unfortunate coincidence that it
happens to have 'key' in its name.

OK, I suppose some might say that no amount of additional notes or
cautions are going to stop someone doing as described, if they are not
prepared to read the DITA Spec. in the first place!

That's certainly true, but it might be useful for someone?

I hope this helps?

Many thanks,
David
---------------------------------------------------------------------
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]