Mailing List Archive

david wrote:
>
> I experienced another problem in my forrest project.
>
> I wrote a short how to using the How-To DTD. Like in the sample page I
> used a faqs item for the FAQ.
> I created the following sample document to show the problem:
>
> <!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V2.0//EN"
> "http://forrest.apache.org/dtd/howto-v20.dtd">
> <howto>
> <header>
> <title>Sample</title>
> <last-modified-content-date date="2008-10-12" />
> </header>
>
> <steps title="The Steps">
> <p>See <a href="#entry">sdaf</a></p>
> </steps>
>
> <faqs>
> <faq id="entry">
> <question>The question</question>
> <answer>And the answer</answer>
> </faq>
> </faqs>
>
> </howto>
>
> My problem is that no HTML-anchor is created for the FAQ entry. I mean
> normally when I write a FAQ page without the surrounding how to such an
> anchor will be created, it looks something like:
>
> <a name="entry"></a>
>
> Well, when using the FAQ in a how to document no anchor with my defined ID seems
> to be created. Instead I find the following:
>
> <a name="1+The+question"></a>
>
> Did I do something wrong? And if not, is there possibly a reason why the behavior
> of forrest seems to change when using faqs in a howto?
>
> Thanks a lot,

Not much time to look, but i can give you some
quick pointers.

It seems that you might have found a bug.
Or maybe the automated id-generation is a feature
(i don't know).

I looked at the example document:
http://forrest.apache.org/docs/howto/howto-howto.html
Its first FAQ should be "#faq-difference".

If you are seriously considering using Forrest then
it would be good to understand its internal processing.

Following this bug might be a good exercise.

The sitemaps involved in "howto" and "faq" processing are
$FORREST_HOME/main/webapp/sitemap.xmap which passes to
$FORREST_HOME/main/webapp/forrest.xmap and faq.xmap
which refer to the stylesheets
$FORREST_HOME/resources/stylesheets/howto-to-document.xsl
and faq-to-document.xsl and faqv20-to-faqv13.xsl
(the latter is because document-v13 is the internal
format, not document-v20).

-David

David Crossley wrote:
> david wrote:
> >
> > I experienced another problem in my forrest project.
> >
> > I wrote a short how to using the How-To DTD. Like in the sample page I
> > used a faqs item for the FAQ.
> > I created the following sample document to show the problem:
> >
> > <!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V2.0//EN"
> > "http://forrest.apache.org/dtd/howto-v20.dtd">
> > <howto>
> > <header>
> > <title>Sample</title>
> > <last-modified-content-date date="2008-10-12" />
> > </header>
> >
> > <steps title="The Steps">
> > <p>See <a href="#entry">sdaf</a></p>
> > </steps>
> >
> > <faqs>
> > <faq id="entry">
> > <question>The question</question>
> > <answer>And the answer</answer>
> > </faq>
> > </faqs>
> >
> > </howto>
> >
> > My problem is that no HTML-anchor is created for the FAQ entry. I mean
> > normally when I write a FAQ page without the surrounding how to such an
> > anchor will be created, it looks something like:
> >
> > <a name="entry"></a>
> >
> > Well, when using the FAQ in a how to document no anchor with my defined ID seems
> > to be created. Instead I find the following:
> >
> > <a name="1+The+question"></a>
> >
> > Did I do something wrong? And if not, is there possibly a reason why the behavior
> > of forrest seems to change when using faqs in a howto?
> >
> > Thanks a lot,
>
> Not much time to look, but i can give you some
> quick pointers.
>
> It seems that you might have found a bug.
> Or maybe the automated id-generation is a feature
> (i don't know).
>
> I looked at the example document:
> http://forrest.apache.org/docs/howto/howto-howto.html
> Its first FAQ should be "#faq-difference".

The current version of that document has moved to
http://forrest.apache.org/howto-howto.html
i.e. $FORREST_HOME/site-author/content/xdocs/howto-howto.xml

> If you are seriously considering using Forrest then
> it would be good to understand its internal processing.
>
> Following this bug might be a good exercise.
>
> The sitemaps involved in "howto" and "faq" processing are
> $FORREST_HOME/main/webapp/sitemap.xmap which passes to
> $FORREST_HOME/main/webapp/forrest.xmap and faq.xmap
> which refer to the stylesheets
> $FORREST_HOME/resources/stylesheets/howto-to-document.xsl
> and faq-to-document.xsl and faqv20-to-faqv13.xsl
> (the latter is because document-v13 is the internal
> format, not document-v20).
>
> -David

Hi.

Well, actually I didn't look at all of these documents you gave me.
But I viewed the two stylesheets

faq-to-document.xsl and howto-to-document.xsl

I found out that the parts dealing with the faq-tags differ.
I actually don't understand why they differ so much, but probably this
has reasons I cannot understand because I don't know so much about the
internals of the project.
Well, I focused on my problem, and somehow fixed it I think (at least
for my purposes).
In faq-to document.xsl it sais:

<xsl:template match="faq">
<xsl:variable name="id">
<xsl:call-template name="generate-id"/>
</xsl:variable>
<section id="{$id}">
<xsl:apply-templates select="question"/>
<xsl:apply-templates select="answer"/>
</section>
</xsl:template>

and

<xsl:template name="generate-id">
<xsl:choose>
<xsl:when test="@id">
<xsl:value-of select="@id"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="concat(concat(local-name(.), '-'),
generate-id(.))"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>

while in the howto-to-documents.xsl the same element 'faq' is treated
differently:

<xsl:template match="faq">
<section>
<xsl:apply-templates select="question"/>
<xsl:apply-templates select="answer"/>
</section>
</xsl:template>

and no id-generator is available.

I tried copying the parts from the faq-to-document.xsl and now it works
just fine for me. The correct IDs are generated.

Greetings,

david.

On Mon, 2008-10-13 at 13:11 +1100, David Crossley wrote:
> David Crossley wrote:
> > david wrote:
> > >
> > > I experienced another problem in my forrest project.
> > >
> > > I wrote a short how to using the How-To DTD. Like in the sample page I
> > > used a faqs item for the FAQ.
> > > I created the following sample document to show the problem:
> > >
> > > <!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V2.0//EN"
> > > "http://forrest.apache.org/dtd/howto-v20.dtd">
> > > <howto>
> > > <header>
> > > <title>Sample</title>
> > > <last-modified-content-date date="2008-10-12" />
> > > </header>
> > >
> > > <steps title="The Steps">
> > > <p>See <a href="#entry">sdaf</a></p>
> > > </steps>
> > >
> > > <faqs>
> > > <faq id="entry">
> > > <question>The question</question>
> > > <answer>And the answer</answer>
> > > </faq>
> > > </faqs>
> > >
> > > </howto>
> > >
> > > My problem is that no HTML-anchor is created for the FAQ entry. I mean
> > > normally when I write a FAQ page without the surrounding how to such an
> > > anchor will be created, it looks something like:
> > >
> > > <a name="entry"></a>
> > >
> > > Well, when using the FAQ in a how to document no anchor with my defined ID seems
> > > to be created. Instead I find the following:
> > >
> > > <a name="1+The+question"></a>
> > >
> > > Did I do something wrong? And if not, is there possibly a reason why the behavior
> > > of forrest seems to change when using faqs in a howto?
> > >
> > > Thanks a lot,
> >
> > Not much time to look, but i can give you some
> > quick pointers.
> >
> > It seems that you might have found a bug.
> > Or maybe the automated id-generation is a feature
> > (i don't know).
> >
> > I looked at the example document:
> > http://forrest.apache.org/docs/howto/howto-howto.html
> > Its first FAQ should be "#faq-difference".
>
> The current version of that document has moved to
> http://forrest.apache.org/howto-howto.html
> i.e. $FORREST_HOME/site-author/content/xdocs/howto-howto.xml
>
> > If you are seriously considering using Forrest then
> > it would be good to understand its internal processing.
> >
> > Following this bug might be a good exercise.
> >
> > The sitemaps involved in "howto" and "faq" processing are
> > $FORREST_HOME/main/webapp/sitemap.xmap which passes to
> > $FORREST_HOME/main/webapp/forrest.xmap and faq.xmap
> > which refer to the stylesheets
> > $FORREST_HOME/resources/stylesheets/howto-to-document.xsl
> > and faq-to-document.xsl and faqv20-to-faqv13.xsl
> > (the latter is because document-v13 is the internal
> > format, not document-v20).
> >
> > -David

David Poetzsch-Heffter wrote:
>
> Well, I focused on my problem, and somehow fixed it I think (at least
> for my purposes).

Fantastic.

I recorded an Issue for it and linked to your investigation.
Thanks for your first contribution.

Hopefully someone can find time to investigate further
and patch the code.

http://issues.apache.org/jira/browse/FOR-1128
FAQs in Howto docs have auto-generated id@ rather than source-specified identifier

-David