OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [dita] "The DITA iceberg" presentation at DITA Europe 2016 -- how RNG focus could help

The out-of-box authoring experience with the technical content grammars and the common elements is not good. Too many inappropriate element choices for authors are available in too many contexts. The reasons for this are:
  1. The inclusion of all technical content domain modules in the shells
  2. The presence of mixed-content in contexts where authors ought to be using block-level elements
  3. The presence of block-level elements inside of paragraph
The current models didn't happen by accident. Reasoned design trade-offs were made to arrive at them. Unfortunately, authoring usability was sacrificed.

I figured out how to correct these shortcomings in my Tagsmiths authoring DTD plugin for DITA 1.3. (At one point I referred to it as the Franconstraint plugin.) Unfortunately, the plugin's implementation is too complex to extend for anyone who isn't a DTD expert because it makes extensive use of marked sections. If you want to get a feel for what the technical content vocabularies would be like without the three points above, download it and change the settings in CONFIGURATION_SETTINGS.ent to restrict all of the DTDs (the default configuration is isomorphic with out-of-the-box DTDs).

One the first things that I would like for the Technical Communications subcommittee to address is whether we should improve the authoring experience by eliminating the three points mentioned above from the default technical content grammars. There are a few ways to achieve this, but I'd rather defer that discussion.

I agree, abandoning XSD and DTD grammar files in favor of RNG is the best way forward. Trang would be sufficient to generate monolithic DTDs or XSDs. The RNG-to-DTD conversion routine used in 1.3 would not be needed since the resulting DTDs and XSDs would no longer have to comply with the no-longer-present DITA coding guidelines for DTDs and XSDs.

Best Regards,
Bob Thomas

On Thu, Nov 17, 2016 at 3:44 PM, Rob Hanna <rob@precisioncontent.com> wrote:

Good day, Robert.


I am unfamiliar with RNG but it sounds promising. I’m slightly concerned about your comment that moving to RNG could make the exchange of vocabulary modules difficult. I assume this is because the DTD is completely flattened. In converting the RNG to a DTD, could it be possible to flag elements belonging to vocabulary modules and generate separate DTDs to facilitate exchange? I see that the concept of exchange goes back to the headier days of DITA 1.0 but I still have hope that we will get there someday soon.



Rob Hanna


From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf Of Robert D Anderson
Sent: November 17, 2016 5:24 PM
To: Kristen James Eberlein <kris@eberleinconsulting.com>
Cc: Tom Magliery <tom.magliery@justsystems.com>; DITA TC <dita@lists.oasis-open.org>
Subject: Re: [dita] "The DITA iceberg" presentation at DITA Europe 2016 -- how RNG focus could help


Hi all,

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:

  1. 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).
  2. 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.
  3. 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".
  4. 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.
  5. In a world where we all write constraints in RNG, no single constraint is out of bounds simply because it's impractical.
  6. 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.
  7. 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.
  8. 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.


Robert D. Anderson
DITA-OT lead and Co-editor DITA 1.3 specification,
Digital Services Group

E-mail: robander@us.ibm.com
Digital Services Group

11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA

Inactive hide details for Kristen James Eberlein ---11/17/2016 02:46:17 AM---Maybe we can separate the pain points raised in LeKristen 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 <kris@eberleinconsulting.com>
To: Tom Magliery <tom.magliery@justsystems.com>, DITA TC <dita@lists.oasis-open.org>
Date: 11/17/2016 02:46 AM
Subject: Re: [dita] "The DITA iceberg" presentation at DITA Europe 2016
Sent by: <dita@lists.oasis-open.org>

Maybe we can separate the pain points raised in Leigh's presentation and possible solutions:

Pain points

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.

Possible solutions

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 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.


-----Original Message-----
dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf Of Kristen James Eberlein
Sent: Tuesday, November 15, 2016 11:19 PM
Subject: [dita] "The DITA iceberg" presentation at DITA Europe 2016

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 some
additional PDFs from other sessions.)

I'd like to ask TC members to read and consider it; I'm looking forward
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

Bob Thomas
+1 720 201 8260
Skype: bob.thomas.colorado
Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype
Time zone: Mountain (GMT-7)

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]