forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steve Masover <>
Subject howto-v2.0 and howto2document.xsl (was [jira] Commented: (FOR-824) ...)
Date Wed, 08 Mar 2006 21:04:42 GMT
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...

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.

(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.  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 HTML

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].

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)" <>
>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.
>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">
     <title>Building a Project Site</title>
       <person email="" name="Steve Masover"/>
     <last-modified-content-date date="2006-03-08"/>
   <audience title="Audience">
   <purpose title="Purpose">
     <p>To document projects.</p>
   <prerequisites title="Prerequisites">
       <li>Know stuff.</li>
   <steps title="Picking the right tool">
       <title>Open-source recommendation</title>
       <p>Use <a class="fork" href=" 

Forrest v 0.6:
<!ENTITY % document PUBLIC
     "-//APACHE//ENTITIES Documentation V1.3//EN"


Forrest v 0.7:
<!ENTITY % document PUBLIC
     "-//APACHE//ENTITIES Documentation V2.0//EN"


Steve Masover

IS&T - Student Information Services, UC Berkeley

Steve Masover <>

View raw message