[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] RE: Migrating specialized DTDs to DITA 1.2
I agree with Robert that the TC-provided vocabulary modules should all use locally-resolvable system IDs--that only makes sense and there's no reason to not do that. The larger question is what should people do for locally-defined vocabulary modules. The problem is that there is no single right answer that will work for everybody. Catalogs and catalog resolution are techniques and technology that date from SGML days (I remember sitting in what I think was the first meeting of (organization name escapes me) where Paul Grosso and I and other venerable types hashed out the syntax for the original SGML entity catalogs. XML catalogs have been around almost as long as XML. So it's certainly the case that the technology is well established. Certainly within a Java context catalog support is a given because any SAX parser can be easily configured to use a catalog resolver and all the code to do is free and ubiquitous. But as Su-Laine says, there are [cough, broken] environments that don't provide catalog mechanisms. That means that this is really a development and deployment practice issue, not a "what's best practice" issue. That is, if you need to develop vocabulary modules that will work with the widest array of tools then it only makes sense to author them using public IDs or URNs that depend on catalogs, which will work with the most common tools without modification) (e.g., the Toolkit, all the major editors, any Java-based XML processor you can give a catalog to, etc.). To satisfy catalog-unaware tools you have no choice but to implement some sort of deployment or packaging process that can create a target-specific packaging of the vocabulary modules since you have no way, in general, of predicting where the standard modules will be relative to your local modules. Such a process can be as easy as an Ant script that uses string replacement to a full-feature DTD parser/rewriter, such as we developed at RSI for use with our RSuite CMS system (which stores all DTDs internally with repository-specific absolute URIs). So I don't see this as being a DITA TC issue since there's nothing the TC can do about something that is fundamental XML technology and there can't be a "best practice" since there is no single practice that will work for all users. As far as I know the DTD parser I implemented for RSuite CMS is unique (that is, I wrote it because I couldn't find any existing open-source solution). It's a general-purpose tool that could be useful for doing things like flattening DITA vocabulary module sets and rewriting system IDs. I'll ask if Really Strategies is willing to make the source available as open source. That would at least make it easier for groups who need resolvable system IDs to get them from catalog-requiring-as-authored vocabularies. Cheers, E. On 1/26/11 3:55 AM, "Robert D Anderson" <robander@us.ibm.com> wrote: > 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" <su-laine.yeo@justsystems.com> wrote on 01/25/2011 10:33:06 > PM: > >> From: "Su-Laine Yeo" <su-laine.yeo@justsystems.com> >> To: "dita" <dita@lists.oasis-open.org> >> 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 >> 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 >> >> >> --------------------------------------------------------------------- >> 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 >> > > > --------------------------------------------------------------------- > 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 > -- Eliot Kimber Senior Solutions Architect "Bringing Strategy, Content, and Technology Together" Main: 512.554.9368 www.reallysi.com www.rsuitecms.com
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]