i've created a patch for jakarta-site2.xml which i hope should make things a little clearer. i've made the headers for the instructions about creating web pages for a project using anakia into subsections rather than sections and grouped them together under a single section. i've moved the section about how to modify the main (jakarta-site2) site pages above them. i've added a section describing how to go about modifying the web pages for a project which uses the standard method (ie anakia). this section is based around peter and scott comments (thanks, guys).
i've included the patch and the generated html (since the moved text makes the patch hard to read). are these changes any good? - robert
Index: xdocs/site/jakarta-site2.xml =================================================================== RCS file: /home/cvs/jakarta-site2/xdocs/site/jakarta-site2.xml,v retrieving revision 1.12 diff -u -r1.12 jakarta-site2.xml --- xdocs/site/jakarta-site2.xml 12 Jul 2001 16:32:15 -0000 1.12 +++ xdocs/site/jakarta-site2.xml 15 Jan 2002 19:51:19 -0000 @@ -41,70 +41,101 @@ </p> </section> - <section name="Using the jakarta-site2 module as a dependency"> +<section name="Modification of the Main Site Web Pages"> <p> -If you would like to use the jakarta-site2 module as a dependency for -your project, here are the instructions for how to do that. The benefit -of using it as a dependency is that you will be able to easily adopt the -look and feel of the entire Jakarta website while being able to continue -to have control over your own project's documentation navigation. It is -the recommended, but optional way to develop documentation for projects -hosted under the main Jakarta Project. +People who have accounts on apache.org can check in their changes to the +jakarta-site2 module directly. If you get an error such as "Access +denied: Insufficient Karma", then please send email to the [EMAIL PROTECTED] mailing list and we will grant you the +appropriate access. If you do not have an account, then please feel free +to send patches (<strong>against the .xml files and not the .html +files!</strong>) to the [EMAIL PROTECTED] mailing list. </p> - </section> - <section name="Doing it your way"> - -<p>For reasons of expediency, you might be tempted to do things in -your own way. Once you know HTML who needs Anakia, right? This is the -incorrect approach but we will explore it so that the basic steps for -updating your site on Jakarta become clearer. </p> - -<p>Assuming your project is called <em>myproject</em>, here are steps -you should follow:</p> - -<ol> - <li>Logon to the machine hosting the Jakarta web site.</li> - - <li>Create a directory named <code>myproject</code> under the - <code>/www/jakarta.apache.org/</code> directory.</li> +<p> +You should edit the .xml files and then run build.sh. After you have +done that, you should check in both the .xml files and the .html files. +Once your changes have been checked in, you can do the following: +</p> - <li>Copy your HTML files under the newly created directory.</li> +<source> +cd /www/jakarta.apache.org +cvs update index.html +cd site +cvs update +</source> - <li>That's it!</li> -</ol> +<p> +This will cause the files checked into the jakarta-site2/docs directory +to be checked out and updated on the live website. +</p> +</section> -<p>The new project's web-pages should be accessible under -<code>http://jakarta.apache.org/myproject</code>. </p> +<section name="Creating Web Pages For A (New) Project The Anakia Way"> + <subsection name="Using the jakarta-site2 module as a dependency"> + <p> + If you would like to use the jakarta-site2 module as a dependency for + your project, here are the instructions for how to do that. The benefit + of using it as a dependency is that you will be able to easily adopt the + look and feel of the entire Jakarta website while being able to continue + to have control over your own project's documentation navigation. It is + the recommended, but optional way to develop documentation for projects + hosted under the main Jakarta Project. + </p> + </subsection> -<p>The important point to remember is that <em>you are responsible for -updating your project pages</em>. This statement remains true even if -you switch to the recommended procedure described below.</p> - -<p>If you decide to place your project's web pages under CVS control, -then the pages should pertain to your project's CVS module and -<b>not</b> to the <code>jakarta-site2</code> module. For example, the -contents of <code>/www/jakarta.apache.org/regexp/CVS/Repository</code> -refer to <code>jakarta-regexp/docs</code> and in no way to the -<code>jakarta-site2</code> module. Ask for help if you don't see what -we are talking about.</p> - -<p>There are several problems with the do-it-your-way approach we have -just outlined. First, the <code>myproject</code> pages are not linked -to from the other Jakarta project pages. Your project is just -dangling off Jakarta. Second, your web-pages do not follow the same -look-and-feel as the other Jakarta projects. You can spend many hours -trying to imitate the same look and feel. However, the Jakarta -look-and-feel might change in the future. What will you do then? The -solution is described below. Read on.</p> + <subsection name="Doing it your way"> + + <p>For reasons of expediency, you might be tempted to do things in + your own way. Once you know HTML who needs Anakia, right? This is the + incorrect approach but we will explore it so that the basic steps for + updating your site on Jakarta become clearer. </p> + + <p>Assuming your project is called <em>myproject</em>, here are steps + you should follow:</p> + + <ol> + <li>Logon to the machine hosting the Jakarta web site.</li> + + <li>Create a directory named <code>myproject</code> under the + <code>/www/jakarta.apache.org/</code> directory.</li> + + <li>Copy your HTML files under the newly created directory.</li> + + <li>That's it!</li> + </ol> + + <p>The new project's web-pages should be accessible under + <code>http://jakarta.apache.org/myproject</code>. </p> + + <p>The important point to remember is that <em>you are responsible for + updating your project pages</em>. This statement remains true even if + you switch to the recommended procedure described below.</p> + + <p>If you decide to place your project's web pages under CVS control, + then the pages should pertain to your project's CVS module and + <b>not</b> to the <code>jakarta-site2</code> module. For example, the + contents of <code>/www/jakarta.apache.org/regexp/CVS/Repository</code> + refer to <code>jakarta-regexp/docs</code> and in no way to the + <code>jakarta-site2</code> module. Ask for help if you don't see what + we are talking about.</p> + + <p>There are several problems with the do-it-your-way approach we have + just outlined. First, the <code>myproject</code> pages are not linked + to from the other Jakarta project pages. Your project is just + dangling off Jakarta. Second, your web-pages do not follow the same + look-and-feel as the other Jakarta projects. You can spend many hours + trying to imitate the same look and feel. However, the Jakarta + look-and-feel might change in the future. What will you do then? The + solution is described below. Read on.</p> - </section> + </subsection> - <section name="How To: Get things from CVS"> -<p> -Check out the jakarta-site2 module into a directory that is "next" to -your current project directory. -</p> + <subsection name="How To: Get things from CVS"> + <p> + Check out the jakarta-site2 module into a directory that is "next" to + your current project directory. + </p> <source> cd /projects @@ -113,7 +144,7 @@ cvs -d /home/cvs co jakarta-velocity <-- example other project </source> -<p>Your directory structure should then look something like this:</p> + <p>Your directory structure should then look something like this:</p> <source> /projects @@ -122,9 +153,9 @@ /jakarta-velocity /jakarta-tomcat </source> - </section> + </subsection> - <section name="How To: From the included example"> + <subsection name="How To: From the included example"> <p> The jakarta-site2 module has an /examples directory. Within there is a jakarta-myproject directory that you can copy into your /projects @@ -139,14 +170,14 @@ the instructions below to get a feeling for where everything is and how things are configured. </p> - </section> + </subsection> - <section name="How To: From Scratch"> + <subsection name="How To: From Scratch"> -<p> -You should first create a directory structure within your project that -can be used to store your documentation: -</p> + <p> + You should first create a directory structure within your project that + can be used to store your documentation: + </p> <source> /projects @@ -166,54 +197,54 @@ file. See below. </source> -<p> -Copy the project.xml file from the jakarta-site2/xdocs/stylesheets/ -directory into your jakarta-myproject/xdocs/stylesheets/ directory and -modify it as needed to reflect the navigation needs of your project. If -you are going to provide links to other projects within the Jakarta -project, make sure to make their href attribute based on the "document -root". For example, if your project links to the Ant project, then the -href should be something like this: href="/ant/index.html" -</p> - -<p> -You will need to make a copy of the velocity.properties file from the -jakarta- site2 module. Place it into the xdocs directory as outlined -above. Within the file, you should modify the property shown below to -point to the stylesheets directory within the jakarta-site2 directory. -The path is relative to where the build.sh script is run from. This -tells Velocity where to look for the style.vsl file. Since you want the -same look and feel as the Jakarta website, you should at least start off -by using this file. -</p> - + <p> + Copy the project.xml file from the jakarta-site2/xdocs/stylesheets/ + directory into your jakarta-myproject/xdocs/stylesheets/ directory and + modify it as needed to reflect the navigation needs of your project. If + you are going to provide links to other projects within the Jakarta + project, make sure to make their href attribute based on the "document + root". For example, if your project links to the Ant project, then the + href should be something like this: href="/ant/index.html" + </p> + + <p> + You will need to make a copy of the velocity.properties file from the + jakarta- site2 module. Place it into the xdocs directory as outlined + above. Within the file, you should modify the property shown below to + point to the stylesheets directory within the jakarta-site2 directory. + The path is relative to where the build.sh script is run from. This + tells Velocity where to look for the style.vsl file. Since you want the + same look and feel as the Jakarta website, you should at least start off + by using this file. + </p> + <source> resource.loader.1.resource.path = ../jakarta-site2/xdocs/stylesheets </source> -<p> -Assuming that you are using <a href="/ant/index.html">Ant</a> as your -build tool for your project, you should then be able to copy/paste the -appropriate targets from the jakarta-site2/build.xml file into your own -build.xml file for your project. You will need to make sure that the jar -files in the jakarta-site2/lib directory are also added into your -classpath in your build.sh script. The reason is that Ant does not have -a way (that I know of) to add files to the classpath based on a -conditional set of requirements. In other words, you want to allow -people to build the rest of your project, but you do not want to require -your users to have the jakarta-site2 module checked out in order to do -so. You only want them to have to check out the jakarta-site2 module if -they are going to build their documentation. Unfortunately, this isn't -currently possible with Ant, therefore you need to specify the -jakarta-site2 .jar files in the build.sh classpath using the examples -below... -</p> - -<p> -Below is the stuff you should add to your build.xml file. Please note -that the path to the docs.src and docs.dest would be relative to the -directory where the build.sh script is run from. -</p> + <p> + Assuming that you are using <a href="/ant/index.html">Ant</a> as your + build tool for your project, you should then be able to copy/paste the + appropriate targets from the jakarta-site2/build.xml file into your own + build.xml file for your project. You will need to make sure that the jar + files in the jakarta-site2/lib directory are also added into your + classpath in your build.sh script. The reason is that Ant does not have + a way (that I know of) to add files to the classpath based on a + conditional set of requirements. In other words, you want to allow + people to build the rest of your project, but you do not want to require + your users to have the jakarta-site2 module checked out in order to do + so. You only want them to have to check out the jakarta-site2 module if + they are going to build their documentation. Unfortunately, this isn't + currently possible with Ant, therefore you need to specify the + jakarta-site2 .jar files in the build.sh classpath using the examples + below... + </p> + + <p> + Below is the stuff you should add to your build.xml file. Please note + that the path to the docs.src and docs.dest would be relative to the + directory where the build.sh script is run from. + </p> <source><![CDATA[ <property name="docs.src" value="./xdocs"/> @@ -251,15 +282,15 @@ </copy> </target>]]></source> -<p> -Below is an example of what your build.sh file should look like. What is -important to note is that it is building up the CLASSPATH to find the -.jar files for Anakia. Because it adds itself to the CLASSPATH after you -do, any .jar files in your project that duplicate the .jar files needed -by Anakia will take precedence. So, if there are issues with running -Anakia with a combined classpath, you can opt to make a separate build -script for running Anakia with its own CLASSPATH. -</p> + <p> + Below is an example of what your build.sh file should look like. What is + important to note is that it is building up the CLASSPATH to find the + .jar files for Anakia. Because it adds itself to the CLASSPATH after you + do, any .jar files in your project that duplicate the .jar files needed + by Anakia will take precedence. So, if there are issues with running + Anakia with a combined classpath, you can opt to make a separate build + script for running Anakia with its own CLASSPATH. + </p> <source><![CDATA[#!/bin/sh @@ -298,9 +329,9 @@ -buildfile ${BUILDFILE} \ "$@"]]></source> -</section> +</subsection> -<section name="Constructing your documentation"> +<subsection name="Constructing your documentation"> <p>Now, in order to build your website, all you need to do is:</p> <source>cd jakarta-myproject @@ -332,44 +363,58 @@ can do. If there are errors in your .xml file, they will be reported in the output of running your build.sh script. </p> -</section> +</subsection> -<section name="Tag Documentation"> +<subsection name="Tag Documentation"> <p> The list of tags which you can use within your XML/XHTML file are documented on another <a href="./jakarta-site-tags.html">page</a>. </p> +</subsection> </section> -<section name="Modification of the Website"> -<p> -People who have accounts on apache.org can check in their changes to the -jakarta-site2 module directly. If you get an error such as "Access -denied: Insufficient Karma", then please send email to the [EMAIL PROTECTED] mailing list and we will grant you the -appropriate access. If you do not have an account, then please feel free -to send patches (<strong>against the .xml files and not the .html -files!</strong>) to the [EMAIL PROTECTED] mailing list. -</p> - +<section name="Modifying Web Pages For An Existing Project"> <p> -You should edit the .xml files and then run build.sh. After you have -done that, you should check in both the .xml files and the .html files. -Once your changes have been checked in, you can do the following: +If your project doesn't use Anakia then you should +stop reading this and start reading the project's documents describing +how to build their web pages. From now on, we'll assume that you want to +make some improvements to pages created the standard way. +</p> +<p> +If you're not a committer, then you're almost done. You should submit +patches for project web pages to the development list in the same way +as any other patch. Make sure that you patch the xml files +in the xdocs directory rather than the html files in the docs directory. +That's it. Only committers need to read on. +</p> +<p> +The project's web pages are stored under +<code>/www/jakarta.apache.org/mySubProject</code>. +This directory should be just a check out of the project's <code>docs</code> +directory. +So, you can update the live web pages by updating that directory from CVS. +Here's the checklist to do just that: +<ol> +<li> generate documentation (project specific though most use anakia) </li> +<li> commit to CVS </li> +<li> SSH to jakarta.apache.org </li> +<li> cd /www/jakarta.apache.org/mySubProject</li> +<li> cvs login (This is because <code>anoncvs</code> requires a password. +Note that this only needs to happen the +<strong>FIRST</strong> time you update the website.) </li> +<li> cvs up </li> +<li> make sure that you have the correct permissions set for all the files you +updated </li> +<li> enjoy your new pages! </li> +</ol> </p> - -<source> -cd /www/jakarta.apache.org -cvs update index.html -cd site -cvs update -</source> - <p> -This will cause the files checked into the jakarta-site2/docs directory -to be checked out and updated on the live website. +It is possible that you might find that you don't have permission to do 3. +If this happens, just ask someone in the project who does or drop a note +to the [EMAIL PROTECTED] mailing list and someone will finish +off the update for you. </p> </section> + <section name="Feedback"> <p>
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
