Robert D Anderson [mailto:firstname.lastname@example.org]
Sent: Thursday, November 17, 2016 2:24 PM
To: Kristen James Eberlein
Cc: Tom Magliery; DITA TC
Subject: Re: [dita] "The DITA iceberg"
presentation at DITA Europe 2016 -- how RNG focus could
I think this point needs a lot of thought / discussion:
>> Maybe we need to move
to a model where we encourage folks to configure,
specialize, and constrain in RNG -- keeping to all the rules
driven by modularization -- but them convert the RNG to a
monolithic DTD for use in production. Yes, this will limit
ease of interchange, but ...
This where I've been going in my head. It was prompted by the
shock I went through finding people were (at great cost)
maintaining modular XSDs and modular DTDs for the same
grammar, simply to follow the spec grammar rules.
Here's my thinking, which hopefully flows logically:
- Some constraints are relatively easy in DTD
(for those who can already understand DTD). Others have a
clear pattern, but are hard. Many get so big as to be
impractical (removing <ph> or <pre> from every
- The entities we have to use in DTD are just
plain ugly. They're required by DTD rules if we want
specialization/constraints to work. But they're ugly.
- Basic DTD rules also require that we order many
files in a specific way. We lay those out as rules in our
spec, because anybody doing this has to follow them or the
DTD breaks. For other files, the order is less important,
but we put rules on those too. Because saying "Put these 10
things in this order" is better than saying "Put these 7
things in order, then this one somewhere between 0 and 3,
and these somewhere between 5 and 7".
- Constraints in RNG are easy. If you know XML
but not RNG, the patterns are easy to learn. I mean
ridiculously easy, compared to DTD.
- In a world where we all write constraints in
RNG, no single constraint is out of bounds simply because
- If you (like we at OASIS) develop in RNG,
everything else can / should be generated. Doing otherwise
would be like developing content in DITA, but maintaining an
HTML version in parallel.
- Once it's generated ... the organization of the
DTD / XSD shouldn't matter to the average DITA user. The use
of entities, the number of files are irrelevant, because
you'll never look at it. It's almost certainly more
efficient to have a single file for use in your tools; it's
certainly less confusing.
- If we push this as a best practice with 2.0 ...
constraints become almost trivial. Specialization isn't
trivial, but it's certainly far easier than in DTD or RNG.
Even those who cannot use RNG win.
Point #5 above is the one that most closely relates to the
iceberg problem. If base DITA with no domains is too much for
you, today there are practical limits to what you can cut
away, and still Follow The Rules. With RNG, that practical
limit goes away. There's now a straightforward, easy to follow
pattern for any constraint. At least, that is my
understanding, and the basis for this entire note.
One outcome from this could be for DITA 2.0 to get away from
modular DTDs and XSDs entirely, but keep our rules /
instructions for modular RNGs.
There are reasons not to push everybody to RNG as their
"source", but I'm wondering if the advantages outweigh the
The following list of objections is probably not be
exhaustive, but they're sure to come up:
- Those with extensive DTD or XSD based
specializations would clearly have a harder time upgrading
to 2.0. Either we'd have to ship a modular copy of DTD / XSD
just to allow this, or else they'd have to convert their
modules to RNG.
- Those trying to stay with modular DTD/XSD would
no longer be able to easily exchange vocabulary modules.
That said - in DITA 1.0 days we thought this would happen
all the time, but I haven't seen it happen much in practice.
- People already comfortable with DITA DTDs
(there are a few of us) or XSDs would have to learn a new
way of working. But ... that seems reasonable after 15
years, especially when RNG is so much easier.
- People who spent weeks making a constraint to
remove <ph> in XSD might be annoyed once they learn
how easy it is in RNG. Of course that's probably an argument
for the switch rather than a reason to oppose it...
I'm curious to hear what others would think about this. If the
logic doesn't make sense, I'll blame jetlag, having returned
last night from Munich. As mentioned, I've been thinking about
this for a while, so it's also possible I jumped over some
logical step that I had wrestled with some weeks ago.
Kristen James Eberlein ---11/17/2016
02:46:17 AM---Maybe we can separate the pain points raised
in Leigh's presentation and possible solutions: Pain p
From: Kristen James Eberlein <email@example.com>
To: Tom Magliery <firstname.lastname@example.org>,
DITA TC <email@example.com>
Date: 11/17/2016 02:46 AM
Subject: Re: [dita] "The DITA iceberg"
presentation at DITA Europe 2016
Sent by: <firstname.lastname@example.org>
Maybe we can separate the pain
points raised in Leigh's presentation and possible
1. Our starter set of DTDs has more in
it than many people want.
2. Many people don't
understand that they can configure their own document-type
shells; they think the start set of shells ARE DITA. If they
know that they can configure shells, it still might be too
troublesome to implement them. For example, a small company
with a handful of writers using version control on the file
system will have to install doctype plug-ins whenever they
upgrade their authoring tool or DITA-OT instance.
3. Constraints are
ridiculously time consuming to implement in DTDs. It's
relatively simple to subset a domain -- but to remove base
elements (for example, <pre>) requires constraining
every element that can contain the base element. It's much
easier in RNG. And it just doesn't really work in XSD.
1. DITA 2.0 gives us the opportunity
to modify what we include in the starter set of shells. We
also could distribute other sets of shells ... I suspect
that if we wanted to entertain that, we should NOT have them
be part of the standard. We could "release" them as a
package associated with a ZIP file.
2. We need to do more
education about configuration.
3. Maybe we need to move to a
model where we encourage folks to configure, specialize, and
constrain in RNG -- keeping to all the rules driven by
modularization -- but them convert the RNG to a monolithic
DTD for use in production. Yes, this will limit ease of
interchange, but ...
4. Drop support for XSD.
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
+1 919 682-2290; kriseberlein (skype)
On 11/16/2016 10:45 PM, Tom
I love the idea of a smaller
"standard DITA", and I look forward to months/years of
entertaining discussion while "what's in" gets hammered
From: email@example.com [mailto:firstname.lastname@example.org] On Behalf Of Kristen James
Sent: Tuesday, November 15, 2016 11:19 PM
To: DITA TC
Subject: [dita] "The DITA iceberg" presentation at DITA
Attached is a PDF from a session done by Leigh White,
IXIASOFT, at this
year's DITA Europe conference. (I'll follow up later
additional PDFs from other sessions.)
I'd like to ask TC members to read and consider it; I'm
to discussion on the list.
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