dita — archive

Re: [dita] Keywords in DITA (example)

From: Erik Hennum
To: [email protected]
Date: Fri, 11 Mar 2005 22:56:00 -0000

MHonArc v2.5.0b2 -->

dita message

Subject: Re: [dita] Keywords in DITA (example)

From: Erik Hennum <[email protected]>
To: Dana Spradley <[email protected]>
Date: Fri, 11 Mar 2005 14:55:09 -0800

Hi, Esteemed DITA Committee-folk:

The discussion here (good thread) seems to point up the problem as being that the <keyword> element in the prolog really only captures the reference half of the semantic words. There is also the conceptual half of the semantic words, which DITA marks up within discourse using the <term> element. So, a possible conclusion from the thread would seem to be that we should add the <term> element to the prolog.

That way, you can supply semantic words either inline within discourse or, if they apply to the topic as a whole, in the prolog. If you need to indicate that a semantic word comes from a specific vocabulary, you can create a specialization of the <term> or <keyword> element and use that specialized element everywhere to represent the same semantic. For instance, an author can identify a specialized <retailterm> or <sqlword> as such in either discourse or the prolog.

In other words, we continue in the direction of providing elements based on semantic rather than use. After all, an application could legitimately choose to display a <keyword> or <term> from the prolog in formatted output. For instance, some uses of DITA might benefit from emitting the semantic words in a running head to flag the topic.

Facing the grim light of day, however, I don't think we want to hold up DITA 1.0 over adding the <term> element to the prolog -- after all, there will always be more enhancements to make. We've deferred a number of enhancement proposals for the sake of getting the initial release out for the benefit of the community. In fact, while they're on the table, both <term> and <keyword> might benefit from an href attribute so they can point at the authoritative definition for the semantic word (or perhaps for the semantic vocabulary?), but consideration of that enhancement is best deferred for post-DITA 1.0

Hoping that's useful,

Erik Hennum
[email protected]

[email protected]>">Dana Spradley <[email protected]>

Dana Spradley <[email protected]>

03/09/2005 04:43 PM

To	"Esrig, Bruce (Bruce)" <[email protected]>
cc	Don Day/Austin/IBM@IBMUS, Paul Prescod <[email protected]>, [email protected], JoAnn Hackos <[email protected]>
Subject	Re: [dita] Keywords in DITA (example)

I agree wholeheartedly, Bruce.

As here: we've fallen into ambiguity on several fronts that resulted in some confusion.

I think we need to restrict <keyword> to the DocBook sense: a word that, if you searched on it, you'd be happy to find this topic. To be used either inline if you like - and subclassed if you like that - or as metadata in the <keywords> element.

As for indicating that something is a keyword in the technical sense in a programming language - and not a keyword of this topic itself - so that it can be formatted differently on output or otherwise processed semantically for some reason, <kwd> would seem to be the likeliest condidate - with "Compare" references between it and <keyword> a necessity.

--Dana

Esrig, Bruce (Bruce) wrote:

1. Yes, just so. We have wider and wider scopes of application for the markup language.

Syntax diagrams;

language that appears in programs;

language, controls, and other screen phenomena that appear in user interfaces;

and conceptual language that governs how our audiences think about the work that they perform.

2. We have many ways of marking up identifiers and other expressions.

There are significant differences in purpose among them,

and in some places, those purposes interact. So we need to discuss those different purposes explicitly

and define and organize the markup in a way that reflects those different purposes.

If we do not explicitly design around the purposes, we instead reason about the effect that we can achieve with each element.

The clashes among various combinations of effects are leading to the clashes about how to use the markup,

and what to allow and disallow.

3. As a result of the examination done in item 2, we would have specific elements,

as we do now, plus a design that explains why those elements cover our needs,

and that systematizes any future structural specializations and any proposals for similar new elements.

Best wishes,

Bruce