AW: [dita] DITA 1.2 packages [updated]

I have a few questions regarding the packaging, also 
based on the discussions we had today in the machine industry SC 
meeting.

 

A ) isn't the naming "Technical Content Package" a 
bit misleading? Do the Machinery Industry Package and the Learning and 
Training Package not also contain mainly technical content?

 

B ) As the Learning and Training Package 
will be used by training departments in the machinery industry as well, I would 
propose to add the machinerytask Domain and the Hazard Statement Domain to this 
package. 

 

C ) As decided today in the machine industry 
subcommittee we require the software, UI and programming domain in the machine 
industry package as well. (for the description of user/service terminals, 
machine control units etc.) But at the same time I would like to ask, if it is 
possible to have two shells, one including those three domains and one without 
them?

 

D) Can we use "Machine Industry Package" instead of 
"Machine Industry Specialization Package"

 

E) I am not sure if I misunderstand the description in 
the "Machine Industry Package". I just like to motion that utility, 
highlighting, and indexing domain must be part of the machine industry 
package as well as all topic types: topic, concept, task, reference, 
glossary

 

F) 
Regarding the possible need or needless of a Machine Industry Task, I have the 
following question.

The 
content model of the DITA 1.2 taskbody is:  

 

<!ENTITY % taskbody.content

"(((%prereq;) | 

(%context;) |

(%section;))*,

((%steps; | 

%steps-unordered; |

%process;))?, 

(%result;)?, 

(%example;)*, 

(%postreq;)*)"

>

The 
machinerytask Domain adds two new elements prelreqs 
(preliminary requirements) and closereqs (closing requirements) 
- names derived from S1000D.

prelreqs has been specialized from section and closereqs from 
example.

<!ENTITY % mitask-d-section 
"prelreqs" > 

<!ENTITY % mitask-d-example 
"closereqs" >

 

The content model of prelreqs is derived from 
S1000D:

<!ENTITY prelreqs.content

"((%reqconds;)?, 

(%reqpers;)?, 

(%supequip;)?, 

(%supplies;)?,

(%spares;)?,

(%safety;)?)"

>

(required conditions, required persons, 
support equipment, supplies, spares, 
safety)

 

The 
content model of closereqs is derived from S1000D:

<!ENTITY closereqs.content 

"(%reqconds;)"

>

(required conditions)

 

The 
specialization will add prelreqs to the section element and closereqs to the 
example element.

But 
now raised the question, what to do with prereq and postreq 
?

 

In the 
discussion today in our subcommittee we had 

3 
votes to replace prereq and postreq by prelreqs and closereqs (to avoid 
confusion if both elements exist) => would require to remove prereq and 
postreq from the content model of task.

2 
votes to add prelreqs and closereqs and to keep all elements from the taskbody 
(to offer a choice for the use of prereq or prelreqs) => content model of 
task.mod would remain unchanged

 

How 
big would be the differences and what would be the 
implication between these two options for the 
implementation.

 

Best 
regards

 

Chris

 

SeicoDyne 
GmbH

Eichenstrasse 
16

CH-6015 
Reussbühl

Switzerland

Tel: +41 
41 534 66 97

Mob: +41 
78 790 66 97

Skype: seicodyne

 

www.seicodyne.com



 

Member of 
the DITA Technical Committee

Chairman 
of the DITA Machine Industry 
Subcommittee

 

Von: Ogden, Jeff [mailto:] 

Gesendet: Montag, 14. April 2008 17:19
An: 

Betreff: [dita] DITA 1.2 packages 
[updated]

Here is a new version 
of the DITA 1.2 packaging proposal updated based on comments and suggestions 
received on the first draft. No major changes to the original proposal from 7 
April. A few additional questions for the TC at the end. Changes are highlighted 
in blue.

 

We’d like to discuss this during an 
upcoming DITA TC call. And, as always, comments and suggestions by e-mail to the 
list or directly to me (), 
Robert (), and 
Michael () are 
welcome.

 

The items below are numbered just to 
make it easier to refer to specific items in discussions and via 
e-mail.

 

General 
comments:

 

  
The proposal is to organize the 
  DITA 1.2 specification into a set of six individual
packages plus an 
  additional combined package as outlined below. 
  
All packages include both DTD and 
  XSD doctype shells and modules. 
  
All packages include catalog files 
  (both XML and text). 
  
All packages include 
  documentation (DITA source, PDF, and chunked HTML output, and possibly HTML 
  Help (chm) and unchunked HTML output). 
  
Packages will contain a mix of 
  normative and informative (non-normative) materials. 
  
Directories and files will be 
  organized and named so that they can be combined and
 installed into 
  the same directories without conflict. 
  
Except for the combined package, 
  individual packages won’t duplicate
the content from other 
  packages. 
  
The Core Package can be used by 
  itself. 
  
Each of the individual non-core 
  packages requires the Core package and may
require other 
  packages. 
  
The Core Package plus the 
  Technical Content Package gives what
is available in DITA 1.1 without 
  bookmap and with the addition of  the Hazard 
Statement domain, and 
  the Basic Topic and Basic Map document type shells. 
  
The written specifications, 
  references, and guidelines are being divided into
smaller independent 
  documents to make them more manageable, to allow
them to be maintained 
  somewhat independently, to allow readers to
avoid sections that they may 
  not need or may not be interested in, and to make
it easier to add more 
  structural and domain specializations in the future. 
  
The DITA TC and eventually OASIS 
  will be asked to approve the specifications, 
DTDs, XSDs, modules, and 
  related files in the combined package. 

 

1)       
Core 
Package

 

a)       DITA 1.2 
Core Architectural Specification (introduction, topic, map, and
metadata 
markup, processing, specialization including constraints).

b)       DITA 1.2 
Core Language Reference (map, topic, metadata, map group 
domain).

c)       DITA 1.2 
Utility Domain Specializations Architecture and Language Reference 
(utilities,
highlighting, xNAL, and hazard statement 
domains).

d)       DITA 1.2 
Processing Guidelines and Examples (non-normative).

 

e)       Basic Topic 
document type shell (topic type, no domains).

f)         
Topic type 
modules.

g)       Topic domain 
specialization modules for the indexing, utilities,
highlighting, and hazard 
statement domains.

h)       Basic Map 
document type shell (only map type plus the map group domain).

i)         
Map modules.

j)         
Map Group domain specialization 
modules. 

k)       Delayed 
Resolution domain specialization modules.

l)         
xNAL domain specialization 
modules.

m)     Basic Ditabase document 
type shell (topic type, no domains).

n)       ditaval 
document type.

 

2)       
Technical Content 
Package

 

a)       DITA 1.2 
Technical Content Specializations Architecture and Language 
Reference 
(concept, task, reference, glossary).

b)       DITA 1.2 
Software Specializations Architecture and Language 
Reference (software, 
programming, and UI domains).

 

c)       Topic 
document type shell (topic plus core topic domains plus the
software, 
programming, and UI domains).

d)       Concept 
document type shell (concept plus core topic domains plus
the software, 
programming, and UI domains).

e)       Glossary 
document type shell (glossentry plus core topic domains plus
the software, 
programming, and UI domains).

f)         
Reference document type shell 
(reference plus core topic domains plus
the software, programming, and UI 
domains).

g)       Task 
document type shell (constrained task plus core topic domains plus 
the
software, programming, and UI domains).

h)       Concept, 
glossary, reference, and task specialization modules.

i)         
Software, programming, and UI domain 
specialization modules.

j)         
Map document type shell (map plus 
map group, and indexing domains).

k)       Technical 
Content Ditabase doctype shell (topic, concept, glossentry,
reference, task 
plus the core topic domains plus the software, 
programming, and UI 
domains).

 

3)       
Book 
Specializations Package

 

a)       DITA 1.2 
Book Specialization Architecture and Language Reference 
(bookmap).

 

b)       Bookmap 
document type shell (bookmap plus map group, indexing,
and xNAL 
domains).

c)       Bookmap 
specialization modules.

 

4)       
Learning and 
Training Content Specializations Package

 

a)       
DITA 1.2 Learning and Training 
Content Specializations Architecture and Language Reference.

 

b)       
Doctype shells for all of the 
Learning and Training topic specializations except learningBase,
includes the 
core topic, software, programming, 
UI, Learning topic, and Learning Metadata 
domains.

c)       
Learning and Training topic, map, and metadata 
domains.

d)       
Learning and Training map doctype 
shell (map plus the Learning Map, 
Learning Metadata, and Learning topic domains).

e)       
Learning and Training 
bookmap doctype shell (bookmap plus the Learning Map and Learning Metadata 
domains).

f)         
Learning and Training map domain 
specialization.

g)       
Learning and Training Ditabase 
doctype shell (all of the Learning and Training topics,
plus topic, concept, 
glossary, reference, task, plus the core topic, software, programming, UI, Learning topic, and Learning 
Metadata domains).

 

5)       
Machine Industry 
Specializations Package

 

a)       DITA 1.2 
Machine Industry Specializations Architecture and Language 
Reference.

 

b)       Machine 
Industry Task doctype shell (task plus the core topic and
Machine Industry 
domain specializations).

c)       Machine 
Industry domain specialization modules.

d)       Machine 
Industry Ditabase doctype shell (topic, concept, reference, Machine Industry 
Task,
plus core topic and Machine Industry domain 
specializations).

 

6) 
      Semantic Linking, 
Controlled Values, and Taxonomies

 

a)       DITA 1.2 
Semantic Linking, Controlled Values, and Taxonomies 
Specializations
Architecture and Language Reference.

 

b)       Subject 
Schema Map document type shell.

c)       Subject 
Schema Map modules.

d)       Classification Map document type 
shell.

e)       Classification domain specialization 
modules.

 

7)       
Combined 
Package

 

a)       All of the 
above in one combined package.

 

 

Questions:

 

I.                     
Should the Learning and Training 
topics and ditabase doctype shells include the software, ui, and programming 
domains?  John thinks they 
should, but will check with the subcommittee.

 

II.                   
Do we want a Learning and Training 
map doctype shell that is based on bookmap?  John says yes.

 

III.                  
Is it nuts to include so many 
variations of Ditabase doctype shells? Do we want a ditabase in each package? 
Should we leave this up to the sub-committees?

 

IV.                
Should we include the approved Best 
Practice documents as an informative part of the core package? Should we combine 
the existing best practice documents into a single document?

 

V.                  
Which map document type shells 
should include the Delayed Resolution domain? Basic map? Technical Content Map? 
Bookmap? Leaning Map?

 

VI.                
We have a constrained task doctype 
shell as part of the Technical Content Package. Do we need to include an 
unconstrained task?  If so, in which package?  Or is the Machine 
Industry Task an unconstrained task that can serve this role?

 

VII.               
Notice that the Delayed Resolution 
domain is included in the core package, that it is not included in any doctype 
shells.  Is this OK?

 

VIII.             
Notice that the xNAL domain is 
included in the core package, but it is only included in the Bookmap doctype 
shell.

 

IX.                 
There was a suggestion 
that we have an additional package that would contain the combined documentation 
and none of the DTD, XSD, and related files. This is not included in the above 
proposal, but could be if members of the TC think it would be 
useful.

 

X.                   
We will include the 
DITA source, PDF, and chunked HTML output. Do we want to include HTML Help (chm) 
and unchunked HTML output as well?

 

XI.                 
Are seven or eight 
packages too many (six individual, one combined, and possibly a combined 
documentation package)?

 

XII.                
Questions about how to 
coordinate Robert’s proposed changes to the organization of the DITA Language 
Reference documents with the packaging proposal were raised during the 8 April 
DITA TC call.

 

XIII.              
There is a question 
about the name for what is labeled the “core” package above.  Is “core” OK 
or would “base”, “common”, or something else be better.

 

XIV.             
There are questions 
about the right place to put the xNAL and Hazard Statement domains that we need 
to sort out.

 

XV.              
Is Technical Content a 
good name for item #2 above?  Would Technical Publications be better? 
Something else?