dita — archive

[Dana Spradley]

 MHonArc v2.5.0b2 -->

















dita message






[Date Prev]
 | [Thread Prev]
 | [Thread Next]
 | [Date Next]

--

[Date Index]
 | [Thread Index]
 | [List Home]








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




From: Dana Spradley <dana.spradley@oracle.com>
To: "Esrig, Bruce (Bruce)" <esrig@lucent.com>
Date: Wed, 09 Mar 2005 14:52:21 -0800










Hi Bruce--


Okay, I think I understand a little better now.


What you are basically asking for is that the scope of the <kwd>
element be expanded beyond <syntaxdiagram> elements, so that it
can be used to trigger different formatting of programming keywords on
output - and so that writers aren't tempted to use <keyword> just
to mark something as a programming keyword.


Or am I still missing something?


--Dana



Esrig, Bruce (Bruce) wrote:


  
Hi Dana,

The distinctions were based on a use case argument that I might not have made explicit.

Content-related functions to be supported:
 - make an identifier stand out (userinput)
 - indicate that an identifier has an associated definition (term)
 - indicate that an identifier has a pre-determined, fixed interpretation (wintitle)

Description-related functions to be supported:
 - provide good search targets that permit a topic to be found (keyword)
 - provide good index entries that permit a topic to be found (indexterm)

Applications:
 - general descriptive text about products, services, and processes
 - documentation of concept-rich information such as software

In the example, in the concept "Snow shovel", the descriptive keyword "tool" does not appear in the content but would make a good search target. Reversing the situation: the content term "scoop" does appear in the content but would not make a good search target.

Even in documenting a programming language or a software application, there is a need for markup for content keywords such as "then" or "OK" which are usually not the target of a search or an index lookup. If these get swept up and made into descriptive keywords by an automatic process, then the value of the results is reduced.

Best wishes,

Bruce