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] Comments on Glossary elements section


Hi Eliot -

One complaint that several reviewers submitted was that the
contains/contained by was not accurate, depending on whether they were
looking at a topic in the ditabase context or in one of the other main
topic types. The comment was most often received about the topic types,
though it also applies to body elements (section can be in body, conbody,
or refbody when inside ditabase, but only in one of those when in the OASIS
reference type).

For the current draft of the language reference, I put in the ditabase
content model. I considered putting in all of the models: "When in an OASIS
Ditabase, you will see this. When in an OASIS topic or concept, you will
see this." However, that would really blow up the size of the reference.
So, I put in the wording you will see in many places about the model
differing slightly. Even that is not great, because as you point out the
statement is only accurate with regards to the OASIS doctypes. That is
really the best we can do though, if we are going to list the
contains/contained by at all.

Do you (or anybody else) have any better wording for the glossentry
element, or for the common text that appears with elements like <p>? For
glossary, I could change the text to something like this:
In the OASIS Composite document type, the glossentry element can be
contained by other topic types (topic, concept, task, reference), and by
the dita element.
In the OASIS glossentry topic type, the glossentry element cannot be
contained by any other element.
Like other topic types, this model may differ when the glossary module is
used in new document types.

Related to this and to your other note - one open item from Jeff Ogden's
original review of the language reference is to use the same wording
everywhere for composite, ditabase, and the other terms that are used for
the <dita> wrapper. I did not have time to get that fixed before the last
draft came out, but it is certainly an open review comment that should be
fixed.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit
(507) 253-8787, T/L 553-8787

"W. Eliot Kimber" <ekimber@innodata-isogen.com> wrote on 01/22/2007
08:54:45 PM:

> I find the glossary elements slightly confusing.
>
> The first sentence of the introductory paragraph is:
>
> "Use the glossary topic type to define terms."
>
> However, there is no glossary topic type, only the glossary entry topic
> type. I think this should read "Use the glossary entry topic type to
> define terms"
>
> Under "contained by" for glossentry, there is this statement:
>
> "When used in a glossary topic on its own, the glossentry element cannot
> be contained by anything."
>
> This sentence doesn't make sense to me--the phrase "used in" isn't well
> defined--does that mean organized hierarchically via a map relative to
> another topic? I can't think of any other way that a topic can be "used
> by" another topic but not be literally nested within it.
>
> In any case, it's a pointless constraint since the whole point of DITA
> is that topics can be organized for storage without regard to how they
> are combined into packages via maps.
>
> Or have I just totally missed something non-obvious about glossentry
topics?
>
> Cheers,
>
> Eliot
> --
> W. Eliot Kimber
> Professional Services
> Innodata Isogen
> 8500 N. Mopac, Suite 402
> Austin, TX 78759
> (214) 954-5198
>
> ekimber@innodata-isogen.com
> www.innodata-isogen.com
>



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]