RE: Migrating specialized DTDs to DITA 1.2

["Su-Laine Yeo" <su-laine.yeo@justsystems.com>]

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
syeo@justsystems.com

XMetaL Community Forums: http://forums.xmetal.com 

-----Original Message-----
From: Eliot Kimber [mailto:ekimber@reallysi.com] 
Sent: Saturday, January 08, 2011 2:23 AM
To: Kristen Eberlein
Cc: Su-Laine Yeo; JoAnn Hackos
Subject: Re: Migrating specialized DTDs to DITA 1.2

I would normally expect all references to be resolved via the public IDs and
corresponding catalogs, not the system IDs.

Thus it shouldn't matter what the organization of the TC-provided modules
are as long as the catalog is accurate.

As a matter of general practice I recommend *against* having system IDs that
are directly resolvable for the simple reason that it will mask catalog
resolution issues.

[One could argue that that's a strong argument for public IDs being bogus
and their use should be replaced by the use of system IDs with URNs but the
use of public IDs is too entrenched for that argument to take hold, so
making sure that your system IDs are not directly resolvable is the next
best thing.]

Cheers,

E.


On 1/7/11 8:10 PM, "Kristen Eberlein" <keberlein@sdl.com> wrote:

> Eliot, I think you authored the ³Migrating from DITA 1.1 to DITA 1.2² topic.
> Can you respond to Su-Laine¹s e-mail?
> Best regards,
> Kris
> Kristen James Eberlein l DITA Architect and Technical Specialist l SDL
> Structured Content Technologies Division l (t) + 1 (919) 682-2290 l
> keberlein@sdl.com
>   <http://www.sdl.com/>
> Please consider the environment before printing this e-mail
>  
>  
>  
> 
> From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com]
> Sent: Friday, January 07, 2011 7:28 PM
> To: Kristen Eberlein; JoAnn Hackos
> Subject: Migrating specialized DTDs to DITA 1.2
>  
> Hi Kris and JoAnn,
> 
> Warm greetings for the new year to you both :)
> 
> The realization hit me today that the new folder structure for DITA 1.2 means
> that specialized DTDs written for DITA 1.0 or 1.1 will not work with DITA 1.2
> without refactoring. E.g. the faq-shell.dtd file written for DITA 1.1 says:
> 
> <!ENTITY % topic-type PUBLIC "-//OASIS//ELEMENTS DITA Topic//EN"
> "../../dtd/topic.mod">
> 
>  
> 
> To make it work for DITA 1.2, it needs to say:
> 
> <!ENTITY % topic-type PUBLIC "-//OASIS//ELEMENTS DITA Topic//EN"
> "../../dtd/base/dtd/topic.mod">
> 
> The spec does not seem to mention that specialized DTDs will have to be
> refactored to take the new folder paths into account :
> http://docs.oasis-open.org/dita/v1.2/os/spec/non-normative/migration-1_1-to-1_
> 2.html 
> <http://docs.oasis-open.org/dita/v1.2/os/spec/non-normative/migration-1_1-to-1
> _2.html>  . It looks to me as if this is a gap in communication that needs to
> be filled, otherwise everyone who has specialized DITA will run into it when
> they move to DITA 1.2. Or am I missing something?
> 
> Cheers,
> 
> Su-Laine
> 
> Su-Laine Yeo
> Solutions Consultant
> 
> JustSystems Canada, Inc.
> Office: 1 (778) 327-6356
> syeo@justsystems.com <mailto:syeo@justsystems.com>
> 
> XMetaL Community Forums: http://forums.xmetal.com
> 
> For partners only: http://www.justpartnercenter.com

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com