dita — archive

RE: Migrating specialized DTDs to DITA 1.2

From: Robert Anderson <[email protected]>
To: [email protected]
Date: Wed, 26 Jan 2011 09:56:00 -0000

Hi Su-Laine, > For the DITA TC, here are some questions to consider: > 1) Should the TC require that all DTDs and XSDs that it approves > include directly-resolvable system IDs? We currently do this for the > base DITA schemas, however I don't think we have thought about > whether we will require it for specializations developed by subcommittees. All of the shipped 1.2 DTDs contain valid relative references to each other. > 2) Should the TC (and/or Adoption TC) recommend as a best practice > that specialized DTDs and XSDs include directly-resolvable system IDs? I would rather leave that up to the team creating a specialization. As Eliot says - his own recommendation is to *not* do this. I can see advantages to both sides. If everything is directly resolvable, it can work in tools that without catalogs. However, invalid references forces you to be aware of the catalog; a seemingly correct system ID has misled me several times into spending hours debugging a problem with the wrong file. I do think that any packages we ship from OASIS should continue to use valid relative system IDs; this was one of the validation checks I performed with the package. > 3) For the official DTD and XSD packages in DITA 1.3 and future > versions, should we try to keep the folder structure the same as in > DITA 1.2 so that paths from specialized DTD and XSDs to the base > DTDs and XSDs are maintained? That's currently my intention. The paths changed with 1.2 for two reasons: 1) I did not want to begin filling up a single directory with subcommittee modules. Among other things, this would add yet more weight to the perception that DITA is too complex, because a user who only wants the base would see 60 or more files that did not apply to them. 2) The restructuring occurred early on when we were actively working towards a modular deliverable, and the directories made that easier and cleaner. > 4) Should we provide a "flattened" version of the DITA 1.2 DTDs and > XSDs so that system IDs written for DITA 1.1 will continue to work > with DITA 1.2? I lean towards "no" -- I think in the end this will cause more problems than it solves. My reasons are: 1) Shipping two packages will cause confusion. The sole purpose for having a flattened version is for tools that cannot use catalogs - so we would need to create an edited version of every DTD with flattened internal references. OASIS would then be providing / maintaining two "official" versions of each DTD, with no way to easily tell the difference. 2) I expect future versions to continue to use a directory structure, so tools that cannot use a catalog should migrate at some point anyway. 3) If we ship that now, people who take advantage will expect the same thing with 1.3 and future versions. Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit "Su-Laine Yeo" <[email protected]> wrote on 01/25/2011 10:33:06 PM: > From: "Su-Laine Yeo" <[email protected]> > To: "dita" <[email protected]> > Date: 01/25/2011 10:37 PM > Subject: [dita] RE: Migrating specialized DTDs to DITA 1.2 > > Hi everyone, > > Thanks Eliot for your comments. I think this issue could use wider > discussion. The use of modular DTD and XSD files is essential to > DITA specialization, but as far as I know we do not have an explicit > statement on the syntax for linking up the modules. > > When one DTD module links to another DTD module, the use of public > IDs and catalogs can make for an elegant and nicely-maintainable > organization of files. Unfortunately however, the use of public IDs > and catalogs does not entirely replace the need for directly- > resolvable system IDs, because some tools can ONLY understand system > IDs. Many XML tools can use a catalog to find a DTD module that is > referenced by another DTD module. > > Neither the XML specification nor the conformance statement in the > DITA specification requires tools to be able to use catalogs. > Colleagues have told me that some commonly-used tool components that > are not natively catalog-aware, at least not in all versions, are > MSXML and Xerces. Applications that incorporate MSXML or Xerces can > implement a catalog resolver if the application is developed using a > compiled language such as C++ or Java. However, it is impossible to > implement a catalog resolver when developing an application for > certain platforms such as Internet Explorer (i.e. HTML + JScript). > So the processor itself must be able to resolve references between > DTD modules. > > Summary: If a specialized DTD references other modules, it will be > usable in more tools if it includes directly-resolvable system IDs. > > For the DITA TC, here are some questions to consider: > 1) Should the TC require that all DTDs and XSDs that it approves > include directly-resolvable system IDs? We currently do this for the > base DITA schemas, however I don't think we have thought about > whether we will require it for specializations developed by subcommittees. > 2) Should the TC (and/or Adoption TC) recommend as a best practice > that specialized DTDs and XSDs include directly-resolvable system IDs? > 3) For the official DTD and XSD packages in DITA 1.3 and future > versions, should we try to keep the folder structure the same as in > DITA 1.2 so that paths from specialized DTD and XSDs to the base > DTDs and XSDs are maintained? > 4) Should we provide a "flattened" version of the DITA 1.2 DTDs and > XSDs so that system IDs written for DITA 1.1 will continue to work > with DITA 1.2? > > Regards, > Su-Laine > > > Su-Laine Yeo > Solutions Consultant > JustSystems Canada, Inc. > Office: 1 (778) 327-6356 > [email protected] > > XMetaL Community Forums: http://forums.xmetal.com > >