dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: AW: [dita] DITA 1.2 packages [an alternative proposal]
- From: "SeicoDyne DITA" <dita@seicodyne.ch>
- To: "'Ogden, Jeff'" <jogden@ptc.com>
- Date: Tue, 13 May 2008 17:03:30 +0200
We just discussed the packaging in the DITA Machine
Industry SC.
Mainly we would like to have the UI domain added but
the programming and software domains removed.
Also we need the bookmap, as well as the topic,
concept, reference and glossary. (but not the task, at it is replaced by the
constraint mi task type shell)
Machine Industry
Package:
a) The core
items, plus:
b)
DITA 1.2 Machine Industry Architecture and
Language Reference.
c)
Machine Industry Task
doctype shell (constrained task plus the
core topic and Machine Industry
domain specializations).
d) Machine
Industry domain specialization modules.
e) Topic document type shell (topic plus core topic domains plus the
UI
domains). (not the software, programming domain)
f)
Concept document type shell (concept plus core topic domains plus
the
UI domains). (not the software, programming domain)
g) Glossary document type shell (glossentry plus core topic domains
plus the
UI domains). (not the software, programming domain)
h) Reference document type shell (reference plus core topic domains
plus the
UI domains). (not the software, programming domain)
j) concept, glossary, reference, and task specialization
modules.
k)
UI domain specialization modules.
l)
Map document type
shell (map plus map group, delayed resolution, and indexing domains).
m)
Bookmap
document type shell (bookmap plus map group, indexing,
delayed resolution,
and xNAL domains).
n) Bookmap specialization modules.
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
Member of
the DITA Technical Committee
Chairman
of the DITA Machine Industry
Subcommittee
Hi Jeff and Robert,
Apologies for neglecting to inform you
sooner, but after consulting with the Learning & Training SC, our desire is
*not* to include the UI, software, and programming domains in the default
L&T package.
Thanks
much.
John
___________________________________
John Hunt
DITA
Architect / Lotus Information Development Center
Chair, OASIS DITA learning
and training content sub-committee
IBM Software Group/Lotus
Software
john_hunt@us.ibm.com
| From:
| "Ogden, Jeff"
<jogden@ptc.com>
|
| To:
| "SeicoDyne DITA"
<dita@seicodyne.ch>, <dita@lists.oasis-open.org>
|
| Date:
| 05/06/2008 07:25 PM
|
| Subject:
| RE: [dita] DITA 1.2 packages [an
alternative proposal] |
Here is a more detailed version of the
alternative packaging proposal. I encourage the TC to discuss the
proposals and make some decisions over the next week or two even thought I’ll be
on vacation and unable to participate in the discussion. You may want to
start the discussion with the less detailed version that I sent out this morning
(a copy is included below) since that is less dense and may be easier to
discuss. In any case here is the more detailed version:
Abandon the idea of
having separate individual packages that do not duplicate the content of other
individual packages and instead have several separate packages each of which is
complete and self-contained. The files and directories in the packages will be
structured and named so that several packages can be installed into the same
directory with the duplicate files overwriting each other and producing a
consistent result.
For DITA 1.2 we will create and distribute six packages:
Full, Documentation, Modular Content, Software, Learning and Training
Content, and Machine Industry.
Drop the Core, Book, and the Semantic Linking,
Controlled Values, and Taxonomies packages that were included in the original
proposal. To get all of that content you would need to use the Full Package,
although much of the abandoned Core Package content will be included in each of
the remaining packages and the Book package contents will be included in several
of the individual packages.
This alternative, beyond the repackaging and the
addition of the new Modular Content doctype shells, maintains the decisions that
the TC previously made as far as splitting up the documentation and the overall
structure of directories and files.
This alternative gets us down
to 6 packages from 8. Users don’t need to worry about dependencies between
packages. Most users will be able to load just one package. The Software Package
is very similar to what was included in DITA 1.1. Even with the reduced
number of packages, because of the addition of the Modular Content Package, we
are offering a richer set of pre-packaged doctype shells. We’ve provided a less
software oriented alternative. And we’ve given the software package a more
honest name.
The following “core” items are not a separate package, but are
included by all of
the packages except for the documentation package and are
listed here so they
can be referenced without repeating them in the detailed
descriptions
for each package:
a) DITA 1.2 Core Architectural Specification (introduction, topic, map,
and
metadata markup, processing including delayed resolution,
specialization including constraints).
b)
DITA 1.2 Core Language Reference (map, topic,
metadata including
delayed resolution, map group domain).
c)
DITA 1.2 Utility Domain Specializations
Architecture and Language
Reference (utilities, highlighting, and hazard
statement domains).
d) DITA 1.2 xNAL Domain Specializations Architecture and Language
Reference.
e)
Topic type modules.
f)
Topic domain specialization
modules for the indexing, utilities,
highlighting, and hazard statement
domains (the core topic domains).
g)
Map modules.
h)
Map Group domain specialization modules.
i)
Delayed Resolution
domain specialization modules.
j) xNAL domain specialization modules.
k)
ditaval document type.
The packages will
include:
Full Package
Includes everything,
documentation, DTDs, XSDs, and related files. In addition
to the items
included in other packages the following items would only be available
in
the full package:
a)
Subject Schema Map document type
shell (need details here).
b) Subject Schema Map modules.
c)
Classification Map document type shell (need
details here).
d) Classification domain specialization modules.
e)
Basic Topic document type shell
(topic type, no domains).
f) Basic Map document type shell (only map type plus the map
group domain).
Documentation Package
Includes all of the documentation including DITA source, all
outputs,
but no DTDs, XSDs, or related files. In addition to PDF
documentation included
in other packages the following items would only be
included in the
documentation package and in the full package:
a)
The DITA source plus chunked HTML, unchunked
HTML, and
HTML Help output for all of the Architecture, Language
Reference,
Guideline, and Example documents from the other packages.
b)
The source and all outputs for the
DITA 1.2 Semantic Linking,
Controlled Values, and Taxonomies Architecture
and Language Reference.
c) The source and all outputs for all of the approved Best
Practice
documents as individual documents.
d)
The source and all outputs for the DITA 1.2
Processing Guidelines
and Examples (non-normative).
Modular Content
Package (may want a better name)
This would be what was the technical content package, plus
bookmap,
but without the sw-d,
pr-d, and ui-d domains. Specifically:
a) The core items, plus:
b)
DITA 1.2 Modular Content
Architecture and Language Reference (concept, task, reference, glossary).
c) DITA 1.2 Book
Architecture and Language Reference (bookmap).
d)
Topic document type shell (topic plus core topic
domains).
e) Concept document type shell (concept plus core topic domains).
f)
Glossary document type shell
(glossentry plus core topic domains).
g)
Reference document type shell (reference plus
core topic domains).
h) Task document type shell (constrained task plus core topic
domains).
i) concept, glossary, reference, and task specialization
modules.
j) Software, programming, and UI domain specialization
modules.
k) Map document type shell (map plus map group, delayed resolution, and
indexing domains).
l) Bookmap document type shell (bookmap plus map group, indexing,
delayed resolution, and xNAL domains).
m) Bookmap specialization modules.
n)
Modular Content Ditabase doctype shell (topic,
concept, glossentry, reference, constrained task plus the core topic
domains).
Software Package
This
would be what was the technical content package, plus bookmap,
but with the sw-d, pr-d, and ui-d domains
included. Specifically:
a)
The core items, plus:
b)
DITA 1.2 Modular Content Architecture and
Language
Reference (concept, task, reference, glossary).
c)
DITA 1.2 Software, Programming, and
User Interface Domains
Specializations Architecture and Language
Reference.
d) DITA 1.2 Book Architecture and Language Reference
(bookmap).
e)
Topic document type shell (topic plus core topic
domains plus the
software, programming, and UI domains).
f)
Concept document type shell
(concept plus core topic domains plus
the software, programming, and UI
domains).
g) Glossary document type shell (glossentry plus core topic
domains plus
the software, programming, and UI domains).
h)
Reference document type shell
(reference plus core topic domains plus
the software, programming, and UI
domains).
i) Task document type shell (constrained task plus core topic
domains plus the
software, programming, and UI domains).
j)
concept, glossary,
reference, and task specialization modules.
k)
Software, programming, and UI domain
specialization modules.
l) Map document type shell (map plus map group, delayed
resolution, and indexing domains).
m)
Bookmap document type shell (bookmap plus map
group, indexing,
delayed resolution, and xNAL domains).
n)
Bookmap specialization
modules.
o) Software Content Ditabase doctype shell (topic, concept,
glossentry,
reference, constrained task plus the core topic domains plus the
software,
programming, and UI domains).
Learning and Training Content
Package
This would be the same
as what was proposed previously. Specifically:
a) The core items, plus:
b) DITA 1.2 Learning and Training Content Architecture and
Language Reference.
c)
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.
d) Learning and Training topic, map, and metadata domains.
e)
Learning and Training map
doctype shell (map plus the map group,
delayed resolution, Learning Map,
Learning Metadata, and
Learning topic domains).
f)
Learning and Training bookmap doctype
shell (bookmap plus the
map group, delayed resolution, Learning Map and
Learning
Metadata domains).
g)
Learning and Training map domain specialization
modules.
Machine Industry Package
This would be the same as what was proposed previously.
Specifically:
a)
The core items, plus:
b)
DITA 1.2 Machine Industry Architecture and
Language Reference.
c)
Machine Industry Task
doctype shell (constrained task plus the
core topic and Machine Industry
domain specializations).
d) Machine Industry domain specialization modules.
General
comments:
i. The proposal is to organize the DITA 1.2 specification into a set of four
individual
packages plus a documentation package plus a full package as
outlined above.
ii.
All packages except the documentation
package include both DTD and XSD
doctype shells and modules.
iii.
All packages include catalog files (both
XML and text).
iv.
All packages include PDF output for the
documentation specific to that package. The
documentation package includes
DITA source, PDF, chunked HTML
output, and HTML Help (chm) and unchunked
HTML output. The combined package
includes everything.
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.
Each package will be self contained
and complete. There will be no need for user’s to
download more than one
package unless they want specific content that is only available
in a
particular package.
viii.
Each packages will duplicate
information included in other packages.
ix. The
Software Package gives roughly what is available in DITA 1.1 with the
addition
of the Hazard Statement domain, and the Delayed Resolution domain.
x.
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.
xi.
The DITA TC and
eventually OASIS will be asked to approve the specifications,
DTDs, XSDs,
modules, and related files in the full package. The other packages are
only
being provided as a convience and should not need to be separately
approved.
From: SeicoDyne DITA
[mailto:dita@seicodyne.ch]
Sent: Tuesday, May 06, 2008 9:32
AM
To: Ogden, Jeff; dita@lists.oasis-open.org
Subject: AW:
[dita] DITA 1.2 packages [an alternative proposal]
Jeff, I fully support your proposal.
My concern was to have concept, reference, task and the
software domains in one singel package only. Your proposal looks very convenient
to me and thank you for your work.
Best regards and
have a good meeting.
Chris
Von: Ogden, Jeff
[mailto:jogden@ptc.com]
Gesendet: Dienstag, 6. Mai 2008
15:11
An: dita@lists.oasis-open.org
Betreff: RE: [dita] DITA
1.2 packages [an alternative proposal]
In an attempt to address the concerns that have been raised by Chris and
JoAnn as well as one expressed privately by Erik and my own concerns about the
number of packages, I’d like to put forward the following alternative packaging
proposal for discussion today.
I suggest that we
abandon the idea of having separate individual packages that do not duplicate
the content of other individual packages and instead have several separate
packages each of which is complete and self-contained. That the files and
directories in the packages be structured and named so that several packages can
be installed into the same directory with the duplicate files overwriting each
other and producing a consistent result.
That for DITA 1.2 we
create and distribute the following packages:
Full Package
Includes everything including documentation, dtds, xsds, and related
files.
Documentation Package
Includes all of the documentation including DITA
source, all outputs,
but no dtds, xsds, or related
files
Modular Content Package (I’m open to suggestions
for a better name)
This would be what was the technical content package, plus bookmap,
but without the sw-d, pr-d,
and ui-d domains
Software Package
This would be what was the technical
content package, plus bookmap,
but with the sw-d, pr-d, and ui-d domains included.
Learning and Training Content Package
This would be the same as what was
proposed previously.
Machine Industry
Package
This would be
the same as what was proposed previously.
We would drop the Core, Book, and the Semantic Linking, Controlled
Values, and Taxonomies packages. To get all of that content you would need to
use the Full Package, although much of the abandoned Core Package content will
be included in each of the remaining packages.
This alternative, beyond the repackaging and the addition of the Modular
Content doctype shells, maintains the decisions that the TC previously made as
far as splitting up the documentation and the overall structure of directories
and files.
This alternative gets us down to 6
packages from 8. Users don’t need to worry about dependencies between
packages. Most users will be able to load just one package. The Software Package
is very similar to what was included in DITA 1.1. Even with the reduced
number of packages, because of the addition of the Modular Content Package, we
are offering a richer set of pre-packaged doctype shells. We’ve provided a less
software oriented alternative. And we’ve given the software package a more
honest name.
-Jeff
From: Ogden, Jeff
Sent:
Monday, May 05, 2008 11:50 AM
To:
'dita@lists.oasis-open.org'
Subject: RE: [dita] DITA 1.2 packages
[updated again]
I’m not sure that a detailed
description of the sort you are looking for is doable without knowing more about
what applications the user is using (OpenTool Kit, XMetal, Arbortext, …) and
what it is they are trying to do (what DITA doctypes they are using, what it is
they need to adjust). If someone can write down a specific use case or
two, I’d be willing to try to address that.
A goal of the proposed packages is to provide one out-of-the-box doctype
shell that includes everything that was included in DITA 1.1 in a DITA 1.1
doctype shell. In fact the proposed doctype shells generally provide a bit more
than was included in DITA 1.1, but they don’t include everything that is new to
DITA 1.2 in each doctype shell. Thus some of the Machine Industry work
isn’t available everywhere, but is only available in the Machine Industry
package. And the Learning and Training Content specializations are available in
the Learning and Training Content package.
Reading between the lines of your response it sounds as if you are more
concerned about what is included in the doctype shells that are included in the
out-of-the-box release from OASIS (item ii from my note) then you are about how
many packages we have or what is included in which package (item iii) or about
the division of the specification into smaller documents (item i).
-Jeff
From: JoAnn Hackos
[mailto:joann.hackos@comtech-serv.com]
Sent: Monday, May 05, 2008
11:01 AM
To: Ogden, Jeff; dita@lists.oasis-open.org
Subject:
RE: [dita] DITA 1.2 packages [updated again]
Hi Jeff,
I guess what
I’d like to understand in depth is the user experience with all of this. Is it
possible to describe what will happen if someone gets a set that he or she needs
to adjust, i.e., add one of the domains back in?
A clear explanation of the user experience would help us decide if the
packaging is a benefit or a detriment.
Thanks for your
continued thoughts on this.
Best,
JoAnn
JoAnn T. Hackos, PhD
President
Comtech Services,
Inc.
710 Kipling Street, Suite 400
Denver, CO
80215
303-232-7586
joann.hackos@comtech-serv.com
joannhackos Skype
www.comtech-serv.com
From: Ogden, Jeff
[mailto:jogden@ptc.com]
Sent: Monday, May 05, 2008 8:33
AM
To: dita@lists.oasis-open.org
Subject: RE: [dita] DITA
1.2 packages [updated again]
Any thoughts on
the following?
> In the packaging proposal there
are (at least) three separate, but related things being
discussed:
>
(i)
There
is the division of the documentation into a number of smaller subsets.
>
(ii)
There is the
structure of the directories that will hold the DTDs, XSDs, and related files.
>
(iii)
And there is
the packaging of all of that into a collection of individual zip archives plus
two
> combined zip
archives (documentation and everything).
>
> Is it one particular item that is causing
concern or is it all of them?
>
> And, if it is item iii (the number of
packages) that is causing concern, would moving from 8 to 3
> or 4
packages help or do we need to get back to just a single package to resolve the
concern?
-Jeff
From: Ogden, Jeff
Sent:
Tuesday, April 29, 2008 9:29 AM
To:
'dita@lists.oasis-open.org'
Subject: RE: [dita] DITA 1.2 packages
[updated again]
In the packaging proposal there are
(at least) three separate, but related things being discussed:
(i)
There is the division of the
documentation into a number of smaller subsets.
(ii)
There is the structure of the
directories that will hold the DTDs, XSDs, and related files.
(iii)
And there is
the packaging of all of that into a collection of individual zip archives plus
two combined zip archives (documentation and everything).
Is it one particular item that is
causing concern or is it all of them?
And, if it is
item iii (the number of packages) that is causing concern, would moving from 8
to 3 or 4 packages help or do we need to get back to just a single package to
resolve the concern?
JoAnn
asked:
> Does the new packaging not require a significantly
increased level of expertise to begin than we have had before?
My own feeling is that there should be no more expertise needed with DITA
1.2 than with DITA 1.1 to achieve the same level of functionality that someone
had with DITA 1.1 because we plan to deliver out-of-the-box document type shells
that are very similar to the doctype shells that were included in DITA 1.1.
Where the additional expertise comes in is if someone wants to customize their
use of DITA in ways that weren’t pre-packaged. But that isn’t really
anything new. And someone can avoid having to make any choices by using
the combined package that contains everything and not doing any
customization.
DITA 1.2 does offer a number of
enhancements that will require more expertise to use, but these are largely
optional. One goal of splitting up the documentation and providing different
packages was to allow users without the expertise or desire to use the new
features to avoid having to deal with them. Not sure we have achieved that, but
it was one of the goals.
JoAnn also
asked:
> What packages are the editor and CMS vendors going
to provide to their customers? How will they implement any or all of them?
Aren’t we increasing the cost of entry and discouraging newcomers by making the
choices too complex?
Hopefully the
editor and CMS vendors have enough expertise to make good choices. I think
what we write into the DITA 1.2 Spec. as REQUIRED will have an impact on this,
but that is something separate from packaging. I’d hope that the packaging
wouldn’t drive decisions on the part of the vendors. Vendors are of course
free to come up with their own packaging that may or may not be directly related
to the OASIS convenience packaging as long as they correctly implement all of
the REQUIRED portions.
-Jeff
From: JoAnn Hackos
[mailto:joann.hackos@comtech-serv.com]
Sent: Monday, April 28, 2008
6:14 PM
To: Ogden, Jeff; dita@lists.oasis-open.org
Subject:
RE: [dita] DITA 1.2 packages [updated again]
Well, I do think we have too many packages – all of these make the
decisions for new users even more confusing than just downloading one package.
It won’t be clear to newcomers what they’re getting or not getting if they
aren’t already experts and/or consultants. What packages are the editor and CMS
vendors going to provide to their customers? How will they implement any or all
of them? Aren’t we increasing the cost of entry and discouraging newcomers by
making the choices too complex?
Committee members
casually talk about creating new local shells but most of the people I know who
are implementing DITA aren’t capable of doing any of that. Does the new
packaging not require a significantly increased level of expertise to begin than
we have had before?
If this packaging was intended to make
adoption easier, I feel we’ve gotten far away from that goal. We’re making
adoption more complex instead.
JoAnn
JoAnn T. Hackos, PhD
President
Comtech Services,
Inc.
710 Kipling Street, Suite 400
Denver, CO
80215
303-232-7586
joann.hackos@comtech-serv.com
joannhackos Skype
www.comtech-serv.com
From: Ogden, Jeff
[mailto:jogden@ptc.com]
Sent: Tuesday, April 15, 2008 3:58
PM
To: dita@lists.oasis-open.org
Subject: [dita] DITA 1.2
packages [updated again]
Here is another
version of the DITA 1.2 packaging proposal updated based on comments and
suggestions received during today’s DITA TC call and subsequent e-mail to the
DITA TC list. Changes from the previous draft are highlighted in blue.
I’m sure this will be discussed again on next week’s DITA TC
call. And 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.
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 LTC
subcommittee.
This issue is settled until we hear back
from the LTC subcommittee.
II.
Do we want a Learning and Training
map doctype shell that is based on bookmap? John said yes.
This issue is settled, we just need to do the work.
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?
We agreed to include just one ditabase as part of the
Technical Content package. If the Learning and Training Content or the Machine
Industry sub-committees want ditabases to be included as part of their packages,
they can request that. We’ll assume that we don’t want or need the additional
ditabases for these two packages unless someone speaks up.
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?
We agreed to include the Best Practice documents in
the documentation package as individual documents.
V.
Which map
document type shells should include the Delayed Resolution domain? Basic map?
Technical Content Map? Bookmap? Leaning Map?
We agreed to include the Delayed Resolution domain in all map doctype
shells unless a sub-committee explicitly asks for the domain to be omitted for
map doctype shells included in their package. No explicit requests made yet, but
its early.
V.
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?
The Technical Content package will
include a constrained task doctype shell. The Machine Industry package will
include a differently constrained task doctype shell. The DITA 1.2 release will
not include a completely unconstrained task doctype shell, but individuals and
organizations are free to create one if they wish.
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?
This is OK.
VIII.
Notice
that the xNAL domain is included in the core package, but it is only included in
the Bookmap doctype shell.
We agreed to
separate out the documentation for the xNAL package into its own Architecture
and Language Reference document, to include this document and other xNAL files
in the core package, and to create separate xNAL directories for DTDs and XSDs
within the core package.
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.
We didn’t get to this item during today’s discussion, but while
discussing other items the feeling seemed to be that we should have a separate
combined documentation package and this would be the place to put the Best
Practice documents together with all of the documents from the other
packages.
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?
We didn’t talk about this during today’s call, but I suggest that we
include PDF output for the documents in each of the packages and that we include
the DITA source, PDF, unchunked html, chunked html, and HTML Help output in the
documentation package.
XI.
Are seven or eight packages too many (six
individual, one combined, and possibly a combined documentation package)?
We didn’t talk about this during today’s call, but so far at
least no one has expressed concerns about the number of packages.
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.
I’m no longer sure
what the issue was here. Robert is going forward to implement (a prototype) of
his suggested approach. I suggest that we came back and revisit this after that
work is done.
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.
We didn’t talk about this during today’s call. In a
e-mail exchange with Robert and Michael I said I didn’t like “common” since we
already have common files (common to topics and map) and so having a package
named common might lead to “common common files” which would be confusing.
I think we are going with “core” for now. If someone has strong
feelings about this, they should speak up and hopefully offer suggestions for a
new/better name.
XIV.
There
are questions about the right place to put the xNAL and Hazard Statement domains
that we need to sort out.
We talked about this
indirectly. We seem to be leaning toward putting the xNAL and Hazard
Statement domains in the core package, but with a separate document to describe
xNAL. The xNAL domain will be used from the bookmap doctype shell. The
Hazard Statement domain will be used from several doctype shells in several
packages.
XV.
Is Technical
Content a good name for item #2 above? Would Technical Publications be
better? Something else?
The view was
expressed that Technical Content isn’t a good name. No suggestions for an
alternative so far. Not sure if Technical Publications or TechPubs is
better or not. Probably not. We’ll probably stick with Technical Content until
someone suggests an alternative.
XVI.
Not sure we have agreement on
item xii below.
General comments:
i.
The proposal is to organize the DITA 1.2
specification into a set of six individual
packages plus a documentation package
plus a 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 PDF output for the documentation specific
to that package. The
documentation package includes DITA source, PDF,
chunked HTML
output, and HTML Help (chm) and unchunked HTML output. The
combined package
includes everything.
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 documentation and 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, the Delayed
Resolution 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 including delayed resolution,
specialization including constraints).
b)
DITA 1.2 Core Language Reference (map, topic,
metadata including
delayed
resolution, map group domain).
c)
DITA 1.2 Utility Domain Specializations
Architecture and Language
Reference (utilities, highlighting, and hazard
statement domains).
c.1) DITA 1.2
xNAL Domain Specializations Architecture and Language Reference.
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.
n)
ditaval document type.
2)
Technical Content
Package
a)
DITA 1.2 Technical Content
Architecture and Language
Reference (concept, task, reference,
glossary).
b) DITA 1.2 Software, Programming,
and User Interface Domains
Specializations
Architecture and Language Reference.
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,
delayed resolution, and indexing domains).
k)
Technical Content Ditabase doctype shell (topic,
concept, glossentry,
reference, constrained task plus the core topic domains
plus the software,
programming, and UI domains).
3)
Book Package
a)
DITA 1.2 Book Architecture and Language Reference
(bookmap).
b)
Bookmap document type shell
(bookmap plus map group, indexing,
delayed resolution, and xNAL
domains).
c) Bookmap specialization modules.
4) Learning and Training Content Package
a)
DITA 1.2 Learning and Training Content
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 map group,
delayed resolution, Learning Map,
Learning Metadata, and Learning topic
domains).
e) Learning and Training bookmap doctype shell (bookmap plus the
map group, delayed
resolution, Learning Map and Learning
Metadata domains).
f) Learning and Training map domain specialization modules.
5)
Machine Industry Package
a)
DITA 1.2 Machine Industry Architecture and
Language Reference.
b)
Machine Industry Task doctype shell
(constrained task plus the
core topic and Machine Industry domain
specializations).
c) Machine Industry domain specialization modules.
6)
Semantic Linking, Controlled Values, and
Taxonomies Package
a) DITA 1.2 Semantic Linking, Controlled Values, and
Taxonomies
Architecture and Language Reference.
b)
Subject Schema Map document type shell
(need details here).
c) Subject Schema Map modules.
d)
Classification Map document type shell
(need details here).
e) Classification domain specialization modules.
7)
Documentation
Package
a) The DITA source plus PDF, chunked HTML, unchunked HTML, and
HTML Help
output for all of the Architecture, Language Reference,
Guideline, and
Example documents from the other packages.
b) The source and all outputs for all of the approved
Best Practice
documents as individual documents.
8)
Combined Package
a)
All of the above in one combined package.
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]