Return-Path: 
 <forrest-cvs-return-519-apmail-xml-forrest-dev-archive=xml.apache.org@xml.apache.org>
Delivered-To: apmail-xml-forrest-dev-archive@xml.apache.org
Received: (qmail 13383 invoked by uid 500); 27 Jan 2003 00:26:24 -0000
Mailing-List: contact forrest-cvs-help@xml.apache.org; run by ezmlm
Precedence: bulk
list-help: <mailto:forrest-cvs-help@xml.apache.org>
list-unsubscribe: <mailto:forrest-cvs-unsubscribe@xml.apache.org>
list-post: <mailto:forrest-cvs@xml.apache.org>
Reply-To: forrest-dev@xml.apache.org
Delivered-To: mailing list forrest-cvs@xml.apache.org
Received: (qmail 13372 invoked from network); 27 Jan 2003 00:26:24 -0000
Received: from icarus.apache.org (208.185.179.13)
  by daedalus.apache.org with SMTP; 27 Jan 2003 00:26:24 -0000
Received: (qmail 83901 invoked by uid 1352); 27 Jan 2003 00:26:23 -0000
Date: 27 Jan 2003 00:26:23 -0000
Message-ID: <20030127002623.83900.qmail@icarus.apache.org>
From: jefft@apache.org
To: xml-forrest-cvs@apache.org
Subject: cvs commit: xml-forrest/src/resources/library/xslt faq2document.xsl
X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N

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 &quot;<code>./build.sh docs</code>&quot; 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 ...
  -   &quot;<code>./build.sh clean docs -Duse.skin=basic</code>&quot;
  -   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 &quot;<code>./build.sh docs</code>&quot; 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 ...
  +          &quot;<code>./build.sh clean docs -Duse.skin=basic</code>&quot;
  +          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">