You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by je...@apache.org on 2003/01/27 01:26:23 UTC
cvs commit: xml-forrest/src/resources/library/xslt faq2document.xsl
jefft 2003/01/26 16:26:23
Modified: src/documentation/content/xdocs faq.xml
src/resources/fresh-site/src/documentation/content/xdocs
site.xml
src/resources/library/xslt faq2document.xsl
Added: src/resources/fresh-site/src/documentation/content/xdocs
faq.xml
Log:
- Improved faq2document.xsl to use @id tags on <faq> elements for fragment
identifiers.
- Added a sample FAQ to the seed webapp
Revision Changes Path
1.20 +150 -139 xml-forrest/src/documentation/content/xdocs/faq.xml
Index: faq.xml
===================================================================
RCS file: /home/cvs/xml-forrest/src/documentation/content/xdocs/faq.xml,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- faq.xml 19 Jan 2003 11:13:26 -0000 1.19
+++ faq.xml 27 Jan 2003 00:26:23 -0000 1.20
@@ -3,143 +3,154 @@
<faqs title="Frequently Asked Questions">
-<faq>
- <question>
- When building my project, I get an validation error: <code>Document root
- element "site", must match DOCTYPE root "null".</code>.
- </question>
- <answer>
- <p>
- You are probably trying to build the project with an old version of
- Forrest (built before 2003-01-08) that is incorrectly trying to validate
- the <code>site.xml</code> file. If so, please update your Forrest
- installation.
- </p>
- <p>
- Alternatively, you may be building with an up-to-date Forrest, but have
- overridden <code>forrest.validate.xdocs.excludes</code> in
- <code>forrest.properties</code>. With the introduction of
- <code>site.xml</code>, the above property must have <code>site.xml</code>
- listed to prevent an attempt at DTD-based validation.
- </p>
- </answer>
-</faq>
-
-<faq>
- <question>
- The tab link in my site incorrectly assumes that 'index.html' is present in
- the linked-to directory. How do I fix this?
- </question>
- <answer>
- <p>
- In <code>tabs.xml</code>, use @href instead of @dir, and omit the trailing
- '/'. That will leave which file to serve up to the sitemap. For example, if
- the 'User Manual' tab should link to <code>manual/Introduction.html</code>,
- <code>tabs.xml</code> should contain:
- </p>
- <source><![CDATA[
- <tab label="User Manual" href="manual"/>
- ]]></source>
- <p>
- and add this rule to the sitemap:
- </p>
- <source><![CDATA[
- <map:match pattern="manual">
- <map:redirect-to uri="manual/Introduction.html"/>
- </map:match>
- ]]></source>
- </answer>
-</faq>
-
-<faq>
- <question>
- Why do the generated documents look a little strange?
- </question>
- <answer>
- <p>
- Because we are in transition to the new document-v11.dtd
- and there are still some stylesheets that need tweaking.
- See the <link href="site:samples/document-v11">Demo document-v11</link>
- and <link href="site:compliance">Standards Compliance</link>.
- </p>
- </answer>
-</faq>
-
-<faq>
- <question>
- I have checked out a working copy of <code>xml-forrest</code> CVS, now what?
- </question>
- <answer>
- <p>
- Run "<code>./build.sh docs</code>" to see the documentation
- for Forrest.
- The documentation is generated in the <code>build/site/</code> directory.
- Logfiles are in the <code>build/tmp/context/WEB-INF/logs/</code> directory.
- </p>
- </answer>
-</faq>
-
-<faq>
- <question>
- I gather that I will be able to use the Forrest infrastructure to build
- my own website.
- </question>
- <answer>
- <p>
- That is correct. Many of us want to do that, and that is partially why we
- are working here. Forrest is designed to not only build websites for
- the various Apache projects, but also so that you can apply your own skins
- to your own content. Try this ...
- "<code>./build.sh clean docs -Duse.skin=basic</code>"
- then copy the basic skin to make your own.
- </p>
- <p>
- The <link href="site:forrestbot">forrestbot</link> is under-development to
- automate the production of your documentation.
- </p>
- </answer>
-</faq>
-
-<faq>
- <question>
- Why am i a little confused by the Forrest documentation?
- </question>
- <answer>
- <p>
- Sorry, we are working on that for the next release. Forrest development has
- been very fast recently. Some of the documentation refers to old methods.
- Your best bet is to start with the
- <link href="site:your-project">Using Forrest</link> document.
- </p>
- </answer>
-</faq>
-
-<faq>
- <question>
- How can i help?
- </question>
- <answer>
- <p>
- Join the forrest-dev <link href="site:mail-lists">mailing list</link>
- and help to discuss it. Read the
- <link href="site:primer">Forrest Primer</link> for an overview.
- See the
- <link href="site:todo">To Do List </link> and choose something that
- interests you.
- </p>
- </answer>
-</faq>
-
-<faq>
- <question>
- Why is build docs failing on subsequent builds?
- </question>
- <answer>
- <p>
- It is a bug. Workaround: <code>./build.sh clean docs</code> every time.
- There is an entry on the <link href="site:todo">To Do List</link>.
- </p>
- </answer>
-</faq>
-
+ <part id="getting_started">
+ <title>Getting Started</title>
+ <faq id="checked_out_now_what">
+ <question>
+ I have checked out a working copy of <code>xml-forrest</code> CVS, now what?
+ </question>
+ <answer>
+ <p>
+ Run "<code>./build.sh docs</code>" to see the documentation
+ for Forrest.
+ The documentation is generated in the <code>build/site/</code> directory.
+ Logfiles are in the <code>build/tmp/context/WEB-INF/logs/</code> directory.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="build_fails_subsequent_builds">
+ <question>
+ Why is build docs failing on subsequent builds?
+ </question>
+ <answer>
+ <p>
+ It is a bug. Workaround: <code>./build.sh clean docs</code> every time.
+ There is an entry on the <link href="site:todo">To Do List</link>.
+ </p>
+ </answer>
+ </faq>
+ </part>
+
+
+
+ <part id="technical">
+ <title>Technical</title>
+ <faq id="validation_error:doctype_root_null">
+ <question>
+ When building my project, I get an validation error: <code>Document root
+ element "site", must match DOCTYPE root "null".</code>.
+ </question>
+ <answer>
+ <p>
+ You are probably trying to build the project with an old version of
+ Forrest (built before 2003-01-08) that is incorrectly trying to validate
+ the <code>site.xml</code> file. If so, please update your Forrest
+ installation.
+ </p>
+ <p>
+ Alternatively, you may be building with an up-to-date Forrest, but have
+ overridden <code>forrest.validate.xdocs.excludes</code> in
+ <code>forrest.properties</code>. With the introduction of
+ <code>site.xml</code>, the above property must have <code>site.xml</code>
+ listed to prevent an attempt at DTD-based validation.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="index.html">
+ <question>
+ The tab link in my site incorrectly assumes that 'index.html' is present in
+ the linked-to directory. How do I fix this?
+ </question>
+ <answer>
+ <p>
+ In <code>tabs.xml</code>, use @href instead of @dir, and omit the trailing
+ '/'. That will leave which file to serve up to the sitemap. For example, if
+ the 'User Manual' tab should link to <code>manual/Introduction.html</code>,
+ <code>tabs.xml</code> should contain:
+ </p>
+ <source><![CDATA[
+ <tab label="User Manual" href="manual"/>
+ ]]></source>
+ <p>
+ and add this rule to the sitemap:
+ </p>
+ <source><![CDATA[
+ <map:match pattern="manual">
+ <map:redirect-to uri="manual/Introduction.html"/>
+ </map:match>
+ ]]></source>
+ </answer>
+ </faq>
+ </part>
+
+ <part id="general">
+ <title>General</title>
+
+ <faq id="strange-lookin">
+ <question>
+ Why do the generated documents look a little strange?
+ </question>
+ <answer>
+ <p>
+ Because we are in transition to the new document-v11.dtd
+ and there are still some stylesheets that need tweaking.
+ See the <link href="site:samples/document-v11">Demo document-v11</link>
+ and <link href="site:compliance">Standards Compliance</link>.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="own_website">
+ <question>
+ I gather that I will be able to use the Forrest infrastructure to build
+ my own website.
+ </question>
+ <answer>
+ <p>
+ That is correct. Many of us want to do that, and that is partially why we
+ are working here. Forrest is designed to not only build websites for
+ the various Apache projects, but also so that you can apply your own skins
+ to your own content. Try this ...
+ "<code>./build.sh clean docs -Duse.skin=basic</code>"
+ then copy the basic skin to make your own.
+ </p>
+ <p>
+ The <link href="site:forrestbot">forrestbot</link> is under-development to
+ automate the production of your documentation.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="obsolete_docs">
+ <question>
+ Why am i a little confused by the Forrest documentation?
+ </question>
+ <answer>
+ <p>
+ Sorry, we are working on that for the next release. Forrest development has
+ been very fast recently. Some of the documentation refers to old methods.
+ Your best bet is to start with the
+ <link href="site:your-project">Using Forrest</link> document.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="how_can_I_help">
+ <question>
+ How can i help?
+ </question>
+ <answer>
+ <p>
+ Join the forrest-dev <link href="site:mail-lists">mailing list</link>
+ and help to discuss it. Read the
+ <link href="site:primer">Forrest Primer</link> for an overview.
+ See the
+ <link href="site:todo">To Do List </link> and choose something that
+ interests you.
+ </p>
+ </answer>
+ </faq>
+ </part>
</faqs>
1.7 +5 -1 xml-forrest/src/resources/fresh-site/src/documentation/content/xdocs/site.xml
Index: site.xml
===================================================================
RCS file: /home/cvs/xml-forrest/src/resources/fresh-site/src/documentation/content/xdocs/site.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- site.xml 25 Jan 2003 11:30:28 -0000 1.6
+++ site.xml 27 Jan 2003 00:26:23 -0000 1.7
@@ -25,6 +25,7 @@
</sample>
<sample-ihtml label="Sample ihtml page" href="ihtml-sample.html"/>
<sample-ihtml label="Sample html page" href="ehtml-sample.html"/>
+ <faq label="FAQ" href="faq.html"/>
<changes label="Changes" href="changes.html"/>
<todo label="Todo" href="todo.html"/>
</about>
@@ -35,7 +36,10 @@
<external-refs>
<xml.apache.org href="http://xml.apache.org/">
- <forrest href="forrest/"/>
+ <forrest href="forrest/">
+ <validation href="validation.html"/>
+ <webapp href="your-project.html#webapp"/>
+ </forrest>
<cocoon href="cocoon/"/>
</xml.apache.org>
</external-refs>
1.1 xml-forrest/src/resources/fresh-site/src/documentation/content/xdocs/faq.xml
Index: faq.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.1//EN" "dtd/faq-v11.dtd">
<faqs title="Frequently Asked Questions">
<part id="docs">
<title>Documentation</title>
<faq id="forrest">
<question>
How can I help write documentation?
</question>
<answer>
<p>
This project uses <link href="ext:forrest">Apache Forrest</link> to
generate documentation from XML. Please download a copy of Forrest,
which can be used to <link
href="ext:forrest/validation">validate</link>, <link
href="ext:forrest/webapp">develop</link> and render a project site.
</p>
</answer>
</faq>
<!-- More faqs or parts here -->
</part>
<!-- More faqs or parts here -->
</faqs>
1.5 +27 -5 xml-forrest/src/resources/library/xslt/faq2document.xsl
Index: faq2document.xsl
===================================================================
RCS file: /home/cvs/xml-forrest/src/resources/library/xslt/faq2document.xsl,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- faq2document.xsl 1 Nov 2002 02:55:09 -0000 1.4
+++ faq2document.xsl 27 Jan 2003 00:26:23 -0000 1.5
@@ -28,7 +28,10 @@
<xsl:template match="part" mode="index">
<li>
- <link href="#part-{generate-id()}">
+ <link>
+ <xsl:attribute name="href">
+ <xsl:text>#</xsl:text><xsl:call-template name="generate-id"/>
+ </xsl:attribute>
<xsl:apply-templates select="title"/>
</link>
<ul>
@@ -39,16 +42,21 @@
<xsl:template match="faq" mode="index">
<li>
- <link href="#faq-{generate-id()}">
+ <link>
+ <xsl:attribute name="href">
+ <xsl:text>#</xsl:text><xsl:call-template name="generate-id"/>
+ </xsl:attribute>
<xsl:value-of select="question"/>
</link>
</li>
</xsl:template>
<xsl:template match="part">
- <anchor id="part-{generate-id()}"/>
<section>
- <title>
+ <xsl:attribute name="id">
+ <xsl:call-template name="generate-id"/>
+ </xsl:attribute>
+ <title>
<xsl:value-of select="title"/>
</title>
<xsl:apply-templates select="faq|part"/>
@@ -56,13 +64,27 @@
</xsl:template>
<xsl:template match="faq">
- <anchor id="faq-{generate-id()}"/>
<section>
+ <xsl:attribute name="id">
+ <xsl:call-template name="generate-id"/>
+ </xsl:attribute>
<title>
<xsl:value-of select="question"/>
</title>
<xsl:apply-templates/>
</section>
+ </xsl:template>
+
+ <xsl:template name="generate-id">
+ <xsl:message>## Got node <xsl:value-of select="local-name(.)"/></xsl:message>
+ <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>
<xsl:template match="question">