forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <>
Subject Re: howto-v2.0 and howto2document.xsl (was [jira] Commented: (FOR-824) ...)
Date Thu, 09 Mar 2006 01:04:35 GMT
Steve Masover wrote:
> Forrest Developers,
> My apologies for starting a JIRA issue before writing to this list; I 
> didn't read "Procedure for reporting bugs and issues and enhancement 
> suggestions" on the site carefully enough before pulling the trigger...

No problem. I could see that it would need discussion.
That is why i asked you to bring it to the mailing list.
I am answering today to help move it along. However i am
going away for a while so hopefully another Forrest
developer will follow up.

> David Crossley asked two questions in his comment to FOR-824 of yesterday 
> evening, so I'll answer in two parts
> (a) the problem I believe I've identified; and,
> (b) the oddity I believe I've identified in howto-v20.dtd in different 
> forrest versions
> (a) the problem I believe I've identified
> The problem I have run into can be reproduced as follows:
> In a freshly seeded forrest v 0.7 site, add a new page with XML source as 
> given at the bottom of this e-mail thread (between lines of 
> equals-signs).  Add it to site.xml and generate.  Notice that though there 
> is a class="fork" attribute on the <a> element in the source, the generated 
> page does not contain the expected target="_blank" element; instead it is:
>   <a class="fork" href=" ">Apache-Forrest</a>
> I do not believe this is the intention.  I thought I'd identified the 
> appropriate patch, as reported in FOR-824, but David Crossley's comment 
> suggests I may be mistaken.

I added your test document to the current in-development
SVN (i.e. forrest-0.8-dev) and i see that the problem
is present there too. The <a class="fork" will work
properly in documents (e.g. samples/sample.html) but
not in howtos.

It seems that your patch fixes the immediate issue.
However, i get the feeling that there is something
else going wrong. If the other developers cannot
see what that is, then we should just apply your

Not enough time to investigate properly today.
Referring to forrest-0.8-dev now (*.xsl filenames changed).
I see that the class=fork does work properly in
faq-v20 yet there is no transformation of <a> in the
faq-to-document.xsl transformer. However faq.xmap
uses the faqv20-to-faqv13.xsl which does the <a>
transformation. Perhaps howto-v20 needs similar treatment
in forrest.xmap

> (b) the oddity I believe I've identified in howto-v20.dtd in different 
> forrest versions
> Between forrest v 0.6 and forrest v 0.7 the howto-v20.dtd changed; it seems 
> clear to me that it was corrected in the later version, though the change 
> was not noted in the log that is part of the file.

We need to remove all those "change history" notes from
the DTDs. The notes are incomplete. All change history
can be seen by looking at the subversion logs. One way
to do that is via the web interface:
See Revision 56732.

>  I have provided a 
> comparison of the relevant difference at the end of this thread, between 
> two lines of plus-signs.  The mis-match in forrest v 0.6 between the public 
> ID and the filename of the DTD resulted, in my experience (using an Oxygen 
> XML editor pointing to the appropriate catalog.xcat file in the forrest 
> tree), in HowTo documents that validated when <fork> <jump> and <link>

> elements were included, but not when <a> elements were included -- i.e., 
> forrest source documents whose doctype was given as:
>   <!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V2.0//EN" "howto-v20.dtd">
> Note that in 0.6, using <fork> <jump> and <link> elements, resultant
> was generated as-expected, with appropriate target attributes on the <a> 
> elements.  As I recall from looking at the DTD documents on the 
> site (or was it then?), the DTD for 
> HowTo documented that <fork> <jump> and <link> elements were allowed,

> consistent with my experience validating using Oxygen.
> Using this same doctype validates/invalidates the inverse set of elements 
> in forrest 0.7.  I found this confusing given the identical DTD version 
> number, though making the requisite changes to get a valid document was 
> certainly simple enough [with the caveat in (a) above].

The Public Identifier is the thing that is used to
locate the relevant DTDs, so that bug meant that
the v13 DTD was being used instead of the v20 DTD.

Anyway, am i correct in saying that the issue was fixed
in Forrest-0.7 and your explanation (b) is to help
explain (a)?

> I am aware of the forrest development community's warning that DTDs will 
> change, sometimes markedly, in the pre-1.0 release period, but seemed to me 
> that since the release of this DTD in 0.6 differed in effect -- even if the 
> difference was an understandable and simple typo -- from that in 0.7, a new 
> version number might have been helpful to signal the new (corrected) 
> behavior.
> Hope this helps; and I apologize, again, for failing to post here before 
> adding an issue to JIRA.
> Steve Masover
> >Date: Wed, 8 Mar 2006 02:18:57 +0000 (GMT)
> >From: "David Crossley (JIRA)" <>
> >To:
> >Subject: [jira] Commented: (FOR-824) HowTo DTD 2.0 <a> elements not
> > transformed correctly
> >
> >    [ 
> > 
> >]
> >
> >David Crossley commented on FOR-824:
> >------------------------------------
> >
> >We use the howto-v20 for the Forrest website and its <a> elements are 
> >transformed properly.

I did not realise that the main issue was class=fork.
Now i agree that there is a problem in the howto-v20.

Thanks very much for your efforts with finding this
problem. It must have been difficult to find. I recall
now that some other users (Helena, i think) reported
some issue with class=fork, but we didn't get enough
clues to track it down. You have, thanks.


> >Perhaps you are trying to fix some other issue. Please describe your 
> >problem, preferably on the mailing list.
> >
> >The howto2document.xsl does not need to handle the <a> elements. They are 
> >dealt with later in the processing by docv20todocv13.xsl which converts to 
> >Forrest's internal format (currently document-v13 later will be xhtml2).
> >
> >Would you please explain what you mean by "howto dtd version number was 
> >not changed".
> >
> >
> >> HowTo DTD 2.0 <a> elements not transformed correctly
> >> ----------------------------------------------------
> >>
> >>          Key: FOR-824
> >>          URL:
> >>      Project: Forrest
> >>         Type: Bug
> >>   Components: Skins (general issues)
> >>     Versions: 0.7
> >>     Reporter: Steve Masover
> >>     Priority: Minor
> >
> >>
> >> The v0.7 howto2document.xsl in 
> >$FORREST_HOME/main/webapp/resources/stylesheets does not process a HowTo 
> >DTD 2.0 <a> section correctly. Transformation to document v1.3 should 
> >transform <a> to <link>
> >
> >--
> >This message is automatically generated by JIRA.
> >-
> >If you think it was sent incorrectly contact one of the administrators:
> >
> >-
> >For more information on JIRA, see:
> >
> ===============================
> <?xml version="1.0" encoding="UTF-8"?>
> <!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V2.0//EN" "howto-v20.dtd">
> <howto>
>   <header>
>     <title>Building a Project Site</title>
>     <authors>
>       <person email="" name="Steve Masover"/>
>     </authors>
>     <last-modified-content-date date="2006-03-08"/>
>   </header>
>   <audience title="Audience">
>     <p>Developers.</p>
>   </audience>
>   <purpose title="Purpose">
>     <p>To document projects.</p>
>   </purpose>
>   <prerequisites title="Prerequisites">
>     <ul>
>       <li>Know stuff.</li>
>     </ul>
>   </prerequisites>
>   <steps title="Picking the right tool">
>     <section>
>       <title>Open-source recommendation</title>
>       <p>Use <a class="fork" href=" 
> ">Apache-Forrest</a>.</p>
>     </section>
>   </steps>
> </howto>
> ===============================
> ++++++++++++++++++++++++++++++++
> Forrest v 0.6:
> ---------------------
> <!ENTITY % document PUBLIC
>     "-//APACHE//ENTITIES Documentation V1.3//EN"
>     "document-v20.mod">
> %document;
>     "-//APACHE//ENTITIES FAQ V1.1//EN"
>     "faq-v20.mod">
> %faq;
> Forrest v 0.7:
> ---------------------
> <!ENTITY % document PUBLIC
>     "-//APACHE//ENTITIES Documentation V2.0//EN"
>     "document-v20.mod">
> %document;
>     "-//APACHE//ENTITIES FAQ V2.0//EN"
>     "faq-v20.mod">
> %faq;
> ++++++++++++++++++++++++++++++++
> ************************************************************
> Steve Masover
> Programmer/Analyst
> IS&T - Student Information Services, UC Berkeley
> 510-643-4889
> Steve Masover <>
> ************************************************************* 

View raw message