Here is a bit of Lightweight DITA perspective. I am throwing this on
the list of possible solutions that Kris Eberlein provided earlier
in this thread.|
In the LWDITA subcommittee we are working on a specialization tool
that starts with a reasonably simple template file (basically a DITA
topic) that you create to define your specialization. Then you run
the template through a tool that generates an RNG schema for your
specialization. From there we plan to use Trang to generate DTDs and
XSDs if needed. A first pass on the tool, and other info on
template-based specialization, is here:
Mark Giffin Consulting, Inc.
On 11/17/2016 2:24 PM, Robert D
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 context).
- 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
- 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 it's impractical.
- 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
- 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
- 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 objections.
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
James Eberlein <firstname.lastname@example.org>
Magliery <email@example.com>, DITA TC
[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 solutions:
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
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
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 Magliery wrote:
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 out.
From: email@example.com [mailto:firstname.lastname@example.org] On Behalf Of Kristen James Eberlein
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 with
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