You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by sl...@apache.org on 2002/05/23 17:33:52 UTC
cvs commit: httpd-site/xdocs/docs-project docsformat.xml mod_template.txt
slive 02/05/23 08:33:51
Modified: docs/docs-project docsformat.html mod_template.txt
xdocs/docs-project docsformat.xml mod_template.txt
Log:
Update the documentation instructions with the info for the new
transformation system.
Revision Changes Path
1.5 +21 -13 httpd-site/docs/docs-project/docsformat.html
Index: docsformat.html
===================================================================
RCS file: /home/cvs/httpd-site/docs/docs-project/docsformat.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -b -u -r1.4 -r1.5
--- docsformat.html 16 May 2002 07:06:44 -0000 1.4
+++ docsformat.html 23 May 2002 15:33:51 -0000 1.5
@@ -79,7 +79,7 @@
viewing simpler.</p>
<p>To assure that your documentation follows the defined format, you
should parse it using the DTD. Some help using Emacs with XML files
-is availble from <a href="http://www-106.ibm.com/developerworks/xml/library/x-emacs/">IBM
+is available from <a href="http://www-106.ibm.com/developerworks/xml/library/x-emacs/">IBM
developerWorks</a>.</p>
</blockquote>
</td></tr>
@@ -94,25 +94,33 @@
<blockquote>
<p>The easiest way to view the tranformed docs is simply to open the
xml file directly in a recent verions of MSIE, Netscape, or Mozilla.
-All these browsers will read the xsl file and perform the
-transformation for you automatically, so you can see what the final
-output will look like. This means that you can work on the docs and
-check your work without any special transformation setup.</p>
+(MSIE 6 seems to work consistently. Some people have had luck with
+Netscape 6+ and Mozilla, but others have not.) These browsers
+will read the xsl file and perform the transformation for you
+automatically, so you can see what the final output will look like.
+This means that you can work on the docs and check your work without
+any special transformation setup.</p>
<p>For the final presentation, it is still necessary to transform to
-html to accomodate older browsers. Any standards-compliant xslt
-engine should do. The one we will discuss here is Xalan+Xerces Java.
-These are all Apache projects distributed under the Apache
-license.</p>
+html to accomodate older browsers. Although any standards-compliant
+xslt engine should do, changing engines can lead to massive diffs on
+the transformed files. Therefore, we have chosen a single recommended
+transformation system based on Xalan+Xerces Java and Ant. These are
+all Apache projects distributed under the Apache license.</p>
<p>Assuming that you already have <code>httpd-2.0/docs/manual</code>
checked out from CVS, the requirements to do the transformation are a
Java 1.2 JVM (which you can obtain free from Sun), and the jars for
the <a href="http://xml.apache.org/xalan-j/getstarted.html">Xalan
distribution</a>. If you just want to transform one document at a
time, you can simple follow the directions on the Xalan webpage.</p>
-<p>You can grab all of the JARs required in a tarball located
-<a href="http://httpd.apache.org/dev/dist/httpd-docs-lib.tar.gz">here</a>.</p>
-<p>Eventually, we will need a better system for updating the
-transformations on all the documents at once.</p>
+<p>To update all documents, you should use the JARs located <a href="http://httpd.apache.org/dev/dist/httpd-docs-lib.tar.gz">here</a>.
+We are using a specially modified version of Ant to allow for our
+language-specific filename extensions. Extract this from the
+<code>httpd-2.0/docs/manual/style/</code> directory and it will create
+a <code>lib</code> directory with the appropriate jar files. Then run
+<code>build.sh</code> to perform the transformation. If you are
+running under win32, build.sh will work if cygwin is installed, or you
+can setup your environment and run java by hand.
+</p>
</blockquote>
</td></tr>
</table>
1.2 +1 -1 httpd-site/docs/docs-project/mod_template.txt
Index: mod_template.txt
===================================================================
RCS file: /home/cvs/httpd-site/docs/docs-project/mod_template.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -b -u -r1.1 -r1.2
--- mod_template.txt 12 Mar 2002 20:56:44 -0000 1.1
+++ mod_template.txt 23 May 2002 15:33:51 -0000 1.2
@@ -1,6 +1,6 @@
<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
-<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!--<modulesynopsis> is the root tag and must surround all other tags.
The sequence of tags is important and must be followed in order for
1.5 +22 -13 httpd-site/xdocs/docs-project/docsformat.xml
Index: docsformat.xml
===================================================================
RCS file: /home/cvs/httpd-site/xdocs/docs-project/docsformat.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -b -u -r1.4 -r1.5
--- docsformat.xml 16 May 2002 07:06:44 -0000 1.4
+++ docsformat.xml 23 May 2002 15:33:51 -0000 1.5
@@ -23,7 +23,7 @@
<p>To assure that your documentation follows the defined format, you
should parse it using the DTD. Some help using Emacs with XML files
-is availble from <a
+is available from <a
href="http://www-106.ibm.com/developerworks/xml/library/x-emacs/">IBM
developerWorks</a>.</p>
@@ -33,16 +33,19 @@
<p>The easiest way to view the tranformed docs is simply to open the
xml file directly in a recent verions of MSIE, Netscape, or Mozilla.
-All these browsers will read the xsl file and perform the
-transformation for you automatically, so you can see what the final
-output will look like. This means that you can work on the docs and
-check your work without any special transformation setup.</p>
+(MSIE 6 seems to work consistently. Some people have had luck with
+Netscape 6+ and Mozilla, but others have not.) These browsers
+will read the xsl file and perform the transformation for you
+automatically, so you can see what the final output will look like.
+This means that you can work on the docs and check your work without
+any special transformation setup.</p>
<p>For the final presentation, it is still necessary to transform to
-html to accomodate older browsers. Any standards-compliant xslt
-engine should do. The one we will discuss here is Xalan+Xerces Java.
-These are all Apache projects distributed under the Apache
-license.</p>
+html to accomodate older browsers. Although any standards-compliant
+xslt engine should do, changing engines can lead to massive diffs on
+the transformed files. Therefore, we have chosen a single recommended
+transformation system based on Xalan+Xerces Java and Ant. These are
+all Apache projects distributed under the Apache license.</p>
<p>Assuming that you already have <code>httpd-2.0/docs/manual</code>
checked out from CVS, the requirements to do the transformation are a
@@ -51,11 +54,17 @@
distribution</a>. If you just want to transform one document at a
time, you can simple follow the directions on the Xalan webpage.</p>
-<p>You can grab all of the JARs required in a tarball located
-<a href="http://httpd.apache.org/dev/dist/httpd-docs-lib.tar.gz">here</a>.</p>
+<p>To update all documents, you should use the JARs located <a
+href="http://httpd.apache.org/dev/dist/httpd-docs-lib.tar.gz">here</a>.
+We are using a specially modified version of Ant to allow for our
+language-specific filename extensions. Extract this from the
+<code>httpd-2.0/docs/manual/style/</code> directory and it will create
+a <code>lib</code> directory with the appropriate jar files. Then run
+<code>build.sh</code> to perform the transformation. If you are
+running under win32, build.sh will work if cygwin is installed, or you
+can setup your environment and run java by hand.
+</p>
-<p>Eventually, we will need a better system for updating the
-transformations on all the documents at once.</p>
</section>
<section><title>Special Files</title>
1.2 +1 -1 httpd-site/xdocs/docs-project/mod_template.txt
Index: mod_template.txt
===================================================================
RCS file: /home/cvs/httpd-site/xdocs/docs-project/mod_template.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -b -u -r1.1 -r1.2
--- mod_template.txt 12 Mar 2002 20:56:44 -0000 1.1
+++ mod_template.txt 23 May 2002 15:33:51 -0000 1.2
@@ -1,6 +1,6 @@
<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
-<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!--<modulesynopsis> is the root tag and must surround all other tags.
The sequence of tags is important and must be followed in order for