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


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.

 

Cheers,

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.

Regards,

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.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+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.

mag


-----Original Message-----
From:
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
To: DITA TC
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



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