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] DITA 1.2 terminology


Title: Re: Attempt to group the DITA terminology into logical sections

During today’s DITA TC call I agreed to corvine an ad hoc group to talk more about several terminology items.  We’d like to have a call yet this week if possible, but with some people out of the country that may not be possible.

 

I assume that Michael, Eliot, Stan, JoAnn, and I will all be on the call, if we can find a time that works for everyone. Others are welcome.

 

Would everyone who wants to be (or is willing to be) involved in the discussion send me a note letting me know and letting me know when over the next two weeks you could be available for an hour long call?  Please send the information just as soon as you can.  I hope to pick a time and setup the call by noon on Wednesday.  There is at least a chance that the call will be this Thursday, 12 November.

 

   -Jeff

 

 

From: Ogden, Jeff
Sent: Tuesday, November 10, 2009 10:06 AM
To: 'DITA TC'
Subject: RE: [dita] DITA 1.2 terminology

 

Some background for a discussion of the terminology we want to use in the DITA 1.2 specification is included below.

 

   -Jeff

 

 

> From: Kristen James Eberlein [mailto:kris@eberleinconsulting.com]
> Sent: Monday, November 09, 2009 4:52 PM
> To: DITA TC
> Subject: [dita] DITA 1.2 terminology

>

> I am going to miss the next two TC meetings, but I don't want to hinder the resolution of items that pertain to terminology.
>
>I facilitated a call about terminology on 29 October, which led to two action items:

 

> 1. Gershon to propose a logical ordering of terms, which he did the following week.

>

> 2. Agenda item for the TC to discuss the following points at a meeting:

>

>        * Concrete document type

>

>                 -- Do we need this term? Is it a widely accepted term?

>

>                 -- How is a "Concrete document type" different from a "DITA document type"

 

>        * The notes in the entry for "Local shell" are contentious

 

* Does the terminology apply to entire spec (including Lang Ref topics) or only specific topics in the spec?

> I've asked Jeff Ogden to "own" the second item in my absence.
>
>Best,
>
> Kris

 

From Eliot’s 6 November draft rework of the Linking and Addressing spec. content:

 

Concrete document type

A unique set of structural modules, domain modules, and constraint modules. Two concrete document types are equivalent if they combine exactly the same set of modules. A given module set is formally defined as the value of the @domains attribute on <map>, <topic>, and <dita> elements. Thus a concrete document type is implied by a given @domains value: given the @domains value it is conceptually possible to generate a concrete document type that would correctly validate those documents that use the listed domains.

Because <map>, <topic>, and <dita> elements must exhibit the @domains attribute, there is no DITA-defined requirement that DITA documents be literally governed by concrete document types: every DITA document is inherently governed by the virtual concrete document type represented by its root element's @domains value.

Concrete document types may be implemented via document type shells or head schemas.

Document type shell (shell DTD)

A DTD declaration set that implements a concrete document type. The shell DTD includes and configures one or more structural modules, zero or more domain modules, and zero or more constraint modules. Shell DTDs may not declare any element types or attributes directly.

 

Head schema (shell XSD)

An XML Schema document that implements a concrete document type. The head schema includes and configures one or more structural modules, zero or more domain modules, and zero or more constraint modules. Head schemas may not declare any element types or attributes directly.

 

Local shell

A document type shell or head schema that is not a shell provided by a third party supplying pre-defined DITA modules and shells (e.g., OASIS Open). Local shells are required in order to create concrete document types that are different from the OASIS-provided concrete document types. When local shells are associated with public identifiers, URNs, or absolute URLs, they may not be associated with the public identifier, URN, or absolute URL of any OASIS-provided shell.

 

Note: In particular, DITA users should not directly modify OASIS-provided shells or shells provided by third parties.

 

Note: The simplest local shell is simply an unmodified copy of an OASIS (or other standard-defined) provided shell, stored in a distinct location and, if public identifiers are used by documents that use the shell, bound to one or more distinct and unique public identifiers that reflect the ownership of the shell by its creator.

 

Note: Because local shells are required in order to modify any aspect of DITA concrete document types, it follows that any serious use of DITA should start with the creation of local shells in order to allow immediate or future adjustment of concrete document types without the need to modify documents to change their document type declarations or schema location values.

 

 

From: Kristen James Eberlein [mailto:kris@eberleinconsulting.com]
Sent: Monday, November 09, 2009 4:52 PM
To: DITA TC
Subject: [dita] DITA 1.2 terminology

 

I am going to miss the next two TC meetings, but I don't want to hinder the resolution of items that pertain to terminology.

I facilitated a call about terminology on 29 October, which led to two action items:

  1. Gershon to propose a logical ordering of terms, which he did the following week.
  2. Agenda item for the TC to discuss the following points at a meeting:
    • Concrete document type
      • Do we need this term? Is it a widely accepted term?
      • How is a "Concrete document type" different from a "DITA document type"
    • The notes in the entry for "Local shell" are contentious
    • Does the terminology apply to entire spec (including Lang Ref topics) or only specific topics in the spec?

I've asked Jeff Ogden to "own" the second item in my absence.

Best,

Kris


Joann Hackos wrote:

Hi Gershon,
I’m in favor of alphabetizing the terms within each section. Any order we select is likely to be obscure to the readers.
JoAnn


On 11/8/09 4:04 AM, "Gershon Joseph" <gerjosep@cisco.com> wrote:

Eliot and Dick, thanks for the feedback. I agree we need to work on the section titles. I wanted to at least provide something out the door that captures the intent, but I'm not thinking I've got the section titles 100% accurate.

I spent some time working on the order of the terms within each group. The current order does assume some existing knowledge of the subject being discussed, which we can't really get away from. I'm also thinking that sorting the terms within each section alphabetically would probably be the best approach. Does anyone object to me reordering the terms within each section alphabetically?

Eliot, please let me know when you're finished adding terms to this topic and I'll reorder the terms and try to update the section titles based on the input I've received to-date.

--
Gershon


From: Dick Hamilton [mailto:rlhamilton@frii.com]
Sent: Friday, November 06, 2009 2:51 AM
To: 'Kristen James Eberlein'; Gershon Joseph (gerjosep)
Cc: 'Eliot Kimber'; Bruce Nevin (bnevin); 'JoAnn Hackos'; stan@modularwriting.com; 'Don Day'; 'Ogden, Jeff'
Subject: RE: Attempt to group the DITA terminology into logical sections

Overall, I think this is an appropriate breakdown with
good high level categories. I just have a few comments:

- I agree with Eliot that the "Content and key reference
  terminology" category should have a new title, but why
  not make it "Content reference and linking terminology"
  so that linking is explicitly included?

- I can't always figure out the ordering inside the
  groupings. For example, the ordering under General
  XML terminology is Element type, Element instance,
  Attribute type, and Attribute instance. To be consistent,
  the ordering under General DITA terminology should
  start as DITA element type, DITA element, etc., but
  instead it starts DITA element type, DITA attribute
  type, etc.

 In general, I see some logic in some of the orderings,
  but I suspect they are often obscure unless you already
  know the relationships between the terms. I suggest that
  unless there is a clear rationale to the ordering that
  is obvious, or can be explained in a short sentence, an
  alphabetical ordering inside groupings would be better.

Regards,
Dick Hamilton

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