[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
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 >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]