translation of document-v10 -> v11 DTD

[David Crossley <cr...@indexgeo.com.au>]

I have taken the liberty of bringing off-list discussion
back to the list ... (my comments are below).

Diana Shannon wrote:
> Steven Noels wrote:
>
> > David and I are actively doing some more Forrest-work, as you might have
> > seen, and are readying the v1.1 dtds in the mean time. We could use XSLT
> > to do automatic translation from v10->v11, but that will obviously mean
> > nobody will ever care about using the new dtds... what are your thoughts
> > on the transition process?

With such powerful tools, we have no need to do it by hand.
In fact it will be far more consistent to do it by stylesheet and
by batch. The translation stylesheet could then remain as
a tool for users to translate their own v10 documents.

The transition process should not be done behind-the-scenes.
Of course, we could easily allow v10 to continue and just
add an extra transformation step to the Cocoon sitemap. Yes
that would create the "not care" situation that Steven mentions.

> Clearly, new contributions should be based on v11. Why create additional 
> work for ourselves down the road? I threw up what I had now, based on 
> v10, because I'm feeling under pressure to show something. I've factored 
> v11 into my draft dtds, for howto, tutorial, snippet, etc.

(Diana is talking about the excellent new docs in Cocoon.)
You cannot mix document types. The Cocoon sitemap is
applying stylesheets which expect v10 content in all xdocs.
I think that all Cocoon documents will need to be converted
as a once-off batch process, along with corresponding
stylesheet and sitemap modifications. After that, yes, any
newly contributed doc should be v11.

I wonder if there is another possibility which could allow
mixed document types during an extended transition process.
Can the stylesheet document2html.xsl be changed to detect
the DTD version, or is that information gone from the pipeline
once the XML instance has been parsed? We would still
need to encourage transition to and use of the v11 DTD,
but in this way the stylesheet could cope with both.
On reviewing my comment i see that this could just introduce
another issue with cumbersome stylesheets.

> I want to complete a global edit of all existing docs, in the near term, 
> mainly to clean up embarrassing grammar and typos. Whoever does this 
> (I'm happy to participate) could convert them to v11, one by one. After 
> the job is complete, perhaps we should remove v10 from the dtd 
> directories in the repository?

I do not think it is good practice to remove the old DTD.
It must stay, otherwise users will suddenly have broken
documents in their projects. Worse still they will have
no way to transform them because Cocoon will break
when it cannot find the v10 DTD.

> I think v10 -> v11 is ok for other Apache projects. I think we
> should expect Cocoon to be current...

Absolutely, it must be a shining example. We need the
v10 -> v11 transformation for all projects including
Cocoon and also for users' own work which is based
on Forrest/Cocoon.

> > With the v11 dtd, we got rid of the stupid s1/s2/... and named them
> > sections instead, and another thing I'm still thinking about is
> > introducing a proper title element for sections. Apart from that, the
> > dtds are mostly identical, if not of course for the modularity of the
> > v11 versions.

--David

Re: translation of document-v10 -> v11 DTD

[David Crossley <cr...@indexgeo.com.au>]

Nicola Ken Barozzi wrote:
<snip/>
> 
> One point: in Centipede we already are using v11, and now
> it's being changed...  :-(
> 
> If we change them, we should label them -dev or change
> version number IMHO.

I think the Latin for it is "caveat emptor" - "let the buyer beware".
You are using a pre-release of a DTD, so you must expect
it to change. Your idea is good, to clearly label the DTD
as under development. There should at least be a warning
inside each v11 DTD that it is under development.

I am not sure about the need for -dev Public Identifiers
and System Identifiers. The whole of Forrest is pre-release,
so why bother.
--David

Re: translation of document-v10 -> v11 DTD

[Ivelin Ivanov <iv...@apache.org>]

I am not of much help here, but just thought I'd mention that I'm anxious to
see forrest 1.0 to
start promoting in within the company.

I haven't forgot I promised I'd help as soon as XMLForm matures a bit.

Regards,

Ivelin


----- Original Message -----
From: "Steven Noels" <st...@outerthought.org>
To: <fo...@xml.apache.org>
Sent: Thursday, May 16, 2002 2:02 AM
Subject: RE: translation of document-v10 -> v11 DTD


> Nicola et al. wrote:
>
> > At Avalon many devs want to keep the v10 format because it's
> > compatible with
> > Anakia.
> > I've already done a simple Forrest2MAven conversion in
> > Centipede's Forrest
> > Cent, which I want to put here ASAP.
>
> To be frank: I'm not so sure whether Jakarta is the right use case to
> focus on, right now. I know this might sound partisan, but this project
> is about doing a new xml.apache.org website, and not so much supporting
> each and every old & new version of DTD circulating for the sake of
> applications which are bound to these DTDs using (hard) code. Remember
> my point of XSLT? ;-)
>
> > Currently we have had a very hectic moment at Krysalis, but I
> > think that
> > beta 3 will come out very soon.
> >
> > I will make Forrest use that just after it, if you don't mind.
>
> Use what?
>
> > Oh, BTW, Keiron from Fop and Tom are our new committers for
> > charting stuff.
> >
> > Keiron has "donated" very cool charting stuff, so Cocoon will
> > have it very
> > very soon :-)
>
> Anxiously awaiting ;-)
>
> > > > Clearly, new contributions should be based on v11. Why
> > create additional
> > > > work for ourselves down the road? I threw up what I had
> > now, based on
> > > > v10, because I'm feeling under pressure to show
> > something. I've factored
> > > > v11 into my draft dtds, for howto, tutorial, snippet, etc.
> > >
> > > (Diana is talking about the excellent new docs in Cocoon.)
> > > You cannot mix document types. The Cocoon sitemap is
> > > applying stylesheets which expect v10 content in all xdocs.
> > > I think that all Cocoon documents will need to be converted
> > > as a once-off batch process, along with corresponding
> > > stylesheet and sitemap modifications. After that, yes, any
> > > newly contributed doc should be v11.
> > >
> > > I wonder if there is another possibility which could allow
> > > mixed document types during an extended transition process.
> > > Can the stylesheet document2html.xsl be changed to detect
> > > the DTD version, or is that information gone from the pipeline
> > > once the XML instance has been parsed?
>
> Information about the DTD is not available in the XPath/XSLT data model,
> unless we provide this as a parameter to the XSLT process, which means
> we'll have to indicate this somehow in the request environment, which is
> really bad practice, I guess. So no: support for v10 will be done using
> 'liberal' stylesheets offering templates for older elements/attrs.
>
> > > We would still
> > > need to encourage transition to and use of the v11 DTD,
> > > but in this way the stylesheet could cope with both.
> > > On reviewing my comment i see that this could just introduce
> > > another issue with cumbersome stylesheets.
>
> +1: we can make liberal stylesheets, but we should clearly indicate
> support for v10 is fading away. I will make sure s1|s2|s3 etc gets added
> to the Forrest skin, but that's about all I'm planning to do to support
> v10 authoring.
>
> > > > I want to complete a global edit of all existing docs, in
> > the near term,
> > > > mainly to clean up embarrassing grammar and typos.
> > Whoever does this
> > > > (I'm happy to participate) could convert them to v11, one
> > by one. After
> > > > the job is complete, perhaps we should remove v10 from the dtd
> > > > directories in the repository?
> > >
> > > I do not think it is good practice to remove the old DTD.
> > > It must stay, otherwise users will suddenly have broken
> > > documents in their projects. Worse still they will have
> > > no way to transform them because Cocoon will break
> > > when it cannot find the v10 DTD.
> >
> > But not mix them.
> > They should clearly tell Forrst the version in use.
>
> Dunno. We should think more about this.
>
> > > > I think v10 -> v11 is ok for other Apache projects. I think we
> > > > should expect Cocoon to be current...
> > >
> > > Absolutely, it must be a shining example. We need the
> > > v10 -> v11 transformation for all projects including
> > > Cocoon and also for users' own work which is based
> > > on Forrest/Cocoon.
> >
> > +1
> >
> > > > > With the v11 dtd, we got rid of the stupid s1/s2/...
> > and named them
> > > > > sections instead, and another thing I'm still thinking about is
> > > > > introducing a proper title element for sections. Apart
> > from that, the
> > > > > dtds are mostly identical, if not of course for the
> > modularity of the
> > > > > v11 versions.
> >
> > Yes.
> >
> > One point: in Centipede we already are using v11, and now it's being
> > changed...  :-(
>
> The early adopter syndrome :-)
>
> I prefer to release "official v11 DTD's" together with the release of
> Forrest 1.0 and with the new DTDs Dianna suggested added, too. Until
> then, everything can be considered -dev. What people fail to see, is the
> modular aspect of the new DTDs, which is much more important than some
> elements/attrs getting changed. We should build our stylesheets
> reflecting this modularity, so that it becomes easier to build your own
> Forrest-skin (I will try to do so for the existing Forrest skin in the
> next few days).
>
> Cheers,
>
> </Steven>
>

RE: translation of document-v10 -> v11 DTD

[Steven Noels <st...@outerthought.org>]

Nicola et al. wrote:

> At Avalon many devs want to keep the v10 format because it's
> compatible with
> Anakia.
> I've already done a simple Forrest2MAven conversion in
> Centipede's Forrest
> Cent, which I want to put here ASAP.

To be frank: I'm not so sure whether Jakarta is the right use case to
focus on, right now. I know this might sound partisan, but this project
is about doing a new xml.apache.org website, and not so much supporting
each and every old & new version of DTD circulating for the sake of
applications which are bound to these DTDs using (hard) code. Remember
my point of XSLT? ;-)

> Currently we have had a very hectic moment at Krysalis, but I
> think that
> beta 3 will come out very soon.
>
> I will make Forrest use that just after it, if you don't mind.

Use what?

> Oh, BTW, Keiron from Fop and Tom are our new committers for
> charting stuff.
>
> Keiron has "donated" very cool charting stuff, so Cocoon will
> have it very
> very soon :-)

Anxiously awaiting ;-)

> > > Clearly, new contributions should be based on v11. Why
> create additional
> > > work for ourselves down the road? I threw up what I had
> now, based on
> > > v10, because I'm feeling under pressure to show
> something. I've factored
> > > v11 into my draft dtds, for howto, tutorial, snippet, etc.
> >
> > (Diana is talking about the excellent new docs in Cocoon.)
> > You cannot mix document types. The Cocoon sitemap is
> > applying stylesheets which expect v10 content in all xdocs.
> > I think that all Cocoon documents will need to be converted
> > as a once-off batch process, along with corresponding
> > stylesheet and sitemap modifications. After that, yes, any
> > newly contributed doc should be v11.
> >
> > I wonder if there is another possibility which could allow
> > mixed document types during an extended transition process.
> > Can the stylesheet document2html.xsl be changed to detect
> > the DTD version, or is that information gone from the pipeline
> > once the XML instance has been parsed?

Information about the DTD is not available in the XPath/XSLT data model,
unless we provide this as a parameter to the XSLT process, which means
we'll have to indicate this somehow in the request environment, which is
really bad practice, I guess. So no: support for v10 will be done using
'liberal' stylesheets offering templates for older elements/attrs.

> > We would still
> > need to encourage transition to and use of the v11 DTD,
> > but in this way the stylesheet could cope with both.
> > On reviewing my comment i see that this could just introduce
> > another issue with cumbersome stylesheets.

+1: we can make liberal stylesheets, but we should clearly indicate
support for v10 is fading away. I will make sure s1|s2|s3 etc gets added
to the Forrest skin, but that's about all I'm planning to do to support
v10 authoring.

> > > I want to complete a global edit of all existing docs, in
> the near term,
> > > mainly to clean up embarrassing grammar and typos.
> Whoever does this
> > > (I'm happy to participate) could convert them to v11, one
> by one. After
> > > the job is complete, perhaps we should remove v10 from the dtd
> > > directories in the repository?
> >
> > I do not think it is good practice to remove the old DTD.
> > It must stay, otherwise users will suddenly have broken
> > documents in their projects. Worse still they will have
> > no way to transform them because Cocoon will break
> > when it cannot find the v10 DTD.
>
> But not mix them.
> They should clearly tell Forrst the version in use.

Dunno. We should think more about this.

> > > I think v10 -> v11 is ok for other Apache projects. I think we
> > > should expect Cocoon to be current...
> >
> > Absolutely, it must be a shining example. We need the
> > v10 -> v11 transformation for all projects including
> > Cocoon and also for users' own work which is based
> > on Forrest/Cocoon.
>
> +1
>
> > > > With the v11 dtd, we got rid of the stupid s1/s2/...
> and named them
> > > > sections instead, and another thing I'm still thinking about is
> > > > introducing a proper title element for sections. Apart
> from that, the
> > > > dtds are mostly identical, if not of course for the
> modularity of the
> > > > v11 versions.
>
> Yes.
>
> One point: in Centipede we already are using v11, and now it's being
> changed...  :-(

The early adopter syndrome :-)

I prefer to release "official v11 DTD's" together with the release of
Forrest 1.0 and with the new DTDs Dianna suggested added, too. Until
then, everything can be considered -dev. What people fail to see, is the
modular aspect of the new DTDs, which is much more important than some
elements/attrs getting changed. We should build our stylesheets
reflecting this modularity, so that it becomes easier to build your own
Forrest-skin (I will try to do so for the existing Forrest skin in the
next few days).

Cheers,

</Steven>

Re: translation of document-v10 -> v11 DTD

[Nicola Ken Barozzi <ni...@apache.org>]

From: "David Crossley" <cr...@indexgeo.com.au>

> I have taken the liberty of bringing off-list discussion
> back to the list ... (my comments are below).
>
> Diana Shannon wrote:
> > Steven Noels wrote:
> >
> > > David and I are actively doing some more Forrest-work, as you might
have
> > > seen, and are readying the v1.1 dtds in the mean time. We could use
XSLT
> > > to do automatic translation from v10->v11, but that will obviously
mean
> > > nobody will ever care about using the new dtds... what are your
thoughts
> > > on the transition process?
>
> With such powerful tools, we have no need to do it by hand.
> In fact it will be far more consistent to do it by stylesheet and
> by batch. The translation stylesheet could then remain as
> a tool for users to translate their own v10 documents.
>
> The transition process should not be done behind-the-scenes.
> Of course, we could easily allow v10 to continue and just
> add an extra transformation step to the Cocoon sitemap. Yes
> that would create the "not care" situation that Steven mentions.

At Avalon many devs want to keep the v10 format because it's compatible with
Anakia.
I've already done a simple Forrest2MAven conversion in Centipede's Forrest
Cent, which I want to put here ASAP.

Currently we have had a very hectic moment at Krysalis, but I think that
beta 3 will come out very soon.

I will make Forrest use that just after it, if you don't mind.

Oh, BTW, Keiron from Fop and Tom are our new committers for charting stuff.

Keiron has "donated" very cool charting stuff, so Cocoon will have it very
very soon :-)

> > Clearly, new contributions should be based on v11. Why create additional
> > work for ourselves down the road? I threw up what I had now, based on
> > v10, because I'm feeling under pressure to show something. I've factored
> > v11 into my draft dtds, for howto, tutorial, snippet, etc.
>
> (Diana is talking about the excellent new docs in Cocoon.)
> You cannot mix document types. The Cocoon sitemap is
> applying stylesheets which expect v10 content in all xdocs.
> I think that all Cocoon documents will need to be converted
> as a once-off batch process, along with corresponding
> stylesheet and sitemap modifications. After that, yes, any
> newly contributed doc should be v11.
>
> I wonder if there is another possibility which could allow
> mixed document types during an extended transition process.
> Can the stylesheet document2html.xsl be changed to detect
> the DTD version, or is that information gone from the pipeline
> once the XML instance has been parsed? We would still
> need to encourage transition to and use of the v11 DTD,
> but in this way the stylesheet could cope with both.
> On reviewing my comment i see that this could just introduce
> another issue with cumbersome stylesheets.
>
> > I want to complete a global edit of all existing docs, in the near term,
> > mainly to clean up embarrassing grammar and typos. Whoever does this
> > (I'm happy to participate) could convert them to v11, one by one. After
> > the job is complete, perhaps we should remove v10 from the dtd
> > directories in the repository?
>
> I do not think it is good practice to remove the old DTD.
> It must stay, otherwise users will suddenly have broken
> documents in their projects. Worse still they will have
> no way to transform them because Cocoon will break
> when it cannot find the v10 DTD.

But not mix them.
They should clearly tell Forrst the version in use.

> > I think v10 -> v11 is ok for other Apache projects. I think we
> > should expect Cocoon to be current...
>
> Absolutely, it must be a shining example. We need the
> v10 -> v11 transformation for all projects including
> Cocoon and also for users' own work which is based
> on Forrest/Cocoon.

+1

> > > With the v11 dtd, we got rid of the stupid s1/s2/... and named them
> > > sections instead, and another thing I'm still thinking about is
> > > introducing a proper title element for sections. Apart from that, the
> > > dtds are mostly identical, if not of course for the modularity of the
> > > v11 versions.

Yes.

One point: in Centipede we already are using v11, and now it's being
changed...  :-(

If we change them, we should label them -dev or change version number IMHO.

--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------

Re: translation of document-v10 -> v11 DTD

[Diana Shannon <te...@mac.com>]

On Tuesday, May 14, 2002, at 11:51  PM, David Crossley wrote:

>> Clearly, new contributions should be based on v11. Why create 
>> additional
>> work for ourselves down the road? I threw up what I had now, based on
>> v10, because I'm feeling under pressure to show something. I've 
>> factored
>> v11 into my draft dtds, for howto, tutorial, snippet, etc.
>
> (Diana is talking about the excellent new docs in Cocoon.)
> You cannot mix document types.
I realize that isn't possible without sitemap/xslt modifications. If all 
the v11 changes are merely structural, then it makes sense to batch 
automate this. It wasn't clear to me how "final" the new v11 dtd 
actually is, or if it might introduce some new concerns that required 
manual input, that's all.

Diana