[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] DITA 1.2 packages [updated]
I'd agree with everything Jeff says here - just want to add a couple of
comments.
The next DTD package that I'll post will include the Machine Industry task.
I've already put together a constraint for that document type which removes
prereq and postreq.
Based on my understanding of conversations today, I will also add the
hazard domain to the topic, concept, reference, and task document types. I
think that this means that we do not need a distinct "Machinery Concept"
document type, because it would be an exact match for the other concept we
already distribute. The same would be true for topic and reference.
Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit
(507) 253-8787, T/L 553-8787 (Good Monday & Thursday)
"Ogden, Jeff"
<jogden@ptc.com>
To
04/15/2008 02:04 <dita@lists.oasis-open.org>
PM cc
Subject
RE: [dita] DITA 1.2 packages
[updated]
Some comments edited into the text below.
-Jeff
From: SeicoDyne DITA [mailto:dita@seicodyne.ch]
Sent: Tuesday, April 15, 2008 1:00 PM
To: Ogden, Jeff; dita@lists.oasis-open.org
Subject: 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?
We’ll need some suggestions for a better name, if we want to consider a
change here.
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.
I guess we’ll want to find out what the Learning and Training sub-committee
thinks.
For myself I’m not sure this is a good idea. If we aren’t careful, we’ll
end up with all of the domains in all of doctype shells. I think we need to
try and make some things simpler/smaller rather than more
complicated/larger. Groups can always create their own customized doctype
shells to use whatever combination of domains they want. The question for
the TC or its sub-committees is what we should include in the
out-of-the-box doctype shells that we will include in each of the DITA 1.2
packages.
In any case we wouldn’t add the domains to the package. While this isn’t
completely settled, one possibility is the Hazard Statement domain will be
part of the Core package and the Machine Industry domain would be part of
the Machine Industry package. And then doctype shells from other packages
could use these domains.
We could use the Hazard Statement domain in the Technical Content topic
doctype shells. That might eliminate the need to create Machine Industry
specific doctype shells for topic, concept, and reference. We’d want to ask
the Learning and Training Content Sub-committee if Hazard Statement should
be included in any of their topic doctype shells, but it would certainly be
possible.
And to be clear, it is making the Machine Industry domain a prerequisite
for Learning and Training (or any other package beyond the Machine Industry
package) is what is making me uncomfortable.
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?
Including more doctype shells could certainly be done, but it makes the
packages bigger and somewhat more difficult for the uninitiated to figure
out. What is the use case for having both? Individual organizations are
always free to create their own customized versions.
D) Can we use "Machine Industry Package" instead of "Machine Industry
Specialization Package"
Sure. We should probably drop the word “Specialization” from all of the
package names. That would give us:
Core Package (Base Package?)
Technical Content Package (or some better name that someone suggests?)
Book Package
Learning and Training Content Package
Machine Industry Package
Semantic Linking, Controlled Values, and Taxonomies Package
Combined Documentation Package
Combined 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
All of the core topic domains (utility, highlighting, indexing, hazard
statement) plus software, programming, and UI plus the Machine industry
domain where appropriate should be included in the Machine Industry package
doctype shells.
Less clear if separate versions of topic, concept, reference, and glossary
are needed or if the versions from the Technical Content package (with the
addition of the Hazard Statement domain) can be used.
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.
Can this be addressed by using constraints with task?
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
christian.kravogel@seicodyne.com
Member of the DITA Technical Committee
Chairman of the DITA Machine Industry Subcommittee
Von: Ogden, Jeff [mailto:jogden@ptc.com]
Gesendet: Montag, 14. April 2008 17:19
An: dita@lists.oasis-open.org
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 (
jogden@ptc.com), Robert (robander@us.ibm.com), and Michael (
mpriestlo@ca.ibm.com) 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:
i. 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.
ii. All packages include both DTD and XSD doctype shells and
modules.
iii. All packages include catalog files (both XML and text).
iv. All packages include documentation (DITA source, PDF, and
chunked HTML output, and possibly HTML Help (chm) and unchunked HTML
output).
v. Packages will contain a mix of normative and informative
(non-normative) materials.
vi. Directories and files will be organized and named so that they
can be combined and
installed into the same directories without conflict.
vii. Except for the combined package, individual packages won’t
duplicate
the content from other packages.
viii. The Core Package can be used by itself.
ix. Each of the individual non-core packages requires the Core
package and may
require other packages.
x. 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.
xi. 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.
xii. 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?
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]