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 2004/04/02 22:54:19 UTC
cvs commit: httpd-site/xdocs/docs-project docsformat.xml
slive 2004/04/02 12:54:19
Modified: docs/docs-project docsformat.html
xdocs/docs-project docsformat.xml
Log:
Some notes on generating a pdf file, and remove
an obsolete paragraph.
Revision Changes Path
1.28 +44 -5 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.27
retrieving revision 1.28
diff -u -d -b -u -r1.27 -r1.28
--- docsformat.html 28 Mar 2004 21:42:45 -0000 1.27
+++ docsformat.html 2 Apr 2004 20:54:17 -0000 1.28
@@ -79,11 +79,6 @@
is also available in <a href="mod_template.txt">mod_template.txt</a>.
Obviously, the file extension should be <code>xml</code>. It was
changed to make online viewing simpler.</p>
-<p>We are currently in the process of converting the remainder of the
-httpd-2.0 documentation into xml. The format used is a subset
-of the format used for the module documentation, with the exception
-of an added <related> section. The easiest way to learn the format
-is simply to look through a few of the existing xml files.</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 available from <a href="http://www-106.ibm.com/developerworks/xml/library/x-emacs/">IBM
@@ -155,6 +150,50 @@
tasks are written in perl, you'll need a working perl installation for this.
If not, you should take these steps manually or just drop a note onto
the project mailing list that someone else can do it.</p>
+ </blockquote>
+ </td></tr>
+</table>
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+ <tr><td bgcolor="#525D76">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <strong>Generating a PDF version</strong>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+<p>The PDF version of the docs is generated by transforming the xml
+files to LaTeX using the "latex-en" Ant target. The XSLT style files
+for the transformation are under <code>style/latex/</code>. Once you
+have the <code>.tex</code> equivalent of each <code>.xml</code> file,
+you can use <code>pdflatex</code> to convert this into a pdf file.
+Recommended versions of pdflatex can be obtained as part of TeTeX
+(unix) or MikTeX (win32), but any version of TeX should be fine, as
+long as it is sufficiently complete and modern. To generate the PDF,
+you should process the <code>sitemap.tex</code> file, which contains
+the main LaTeX document code and will include all the other files.
+The outputed PDF will then be called <code>sitemap.pdf</code>, which
+you can rename how you choose.</p>
+<p>Some notes about the XML to LaTeX conversion are necessary.
+Although HTML and LaTeX have many similarities, there are enough
+differences between the two to make targeting both outputs a difficult
+proposition. In particular, the method of handling tables is very
+different. To aid LaTeX in understanding tables designed for HTML, a
+<code><columnspec></code> section should be added to each table.
+Inside the <code><columnspec></code>, place a <code><column
+width=".xx"/></code> for each column in the table, where
+<code>xx</code> is the percentage of the line-width devoted to that
+column. This will let the conversion handle basic tables. More
+complex stuff (like spanning rows or columns) will not work.</p>
+<p>In addition, <code>pdflatex</code> does not know how to incorporate
+GIF files. So any graphics must be available in PNG format.</p>
+<p>Finally, there are various other restrictive assumptions embedded
+in the XSLT that work for the current docs, but may need to be
+modified in the future. For example, the code that transforms
+HTML-style links to LaTeX cross-references will work only with the
+main directory and one level of subdirectory. Also,
+<code><pre></code> sections are very likely not to work well
+in LaTeX because of differences in escaping and formatting rules
+in <code>verbatim</code> sections.</p>
</blockquote>
</td></tr>
</table>
1.16 +40 -6 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.15
retrieving revision 1.16
diff -u -d -b -u -r1.15 -r1.16
--- docsformat.xml 28 Mar 2004 21:42:45 -0000 1.15
+++ docsformat.xml 2 Apr 2004 20:54:19 -0000 1.16
@@ -21,12 +21,6 @@
Obviously, the file extension should be <code>xml</code>. It was
changed to make online viewing simpler.</p>
-<p>We are currently in the process of converting the remainder of the
-httpd-2.0 documentation into xml. The format used is a subset
-of the format used for the module documentation, with the exception
-of an added <related> section. The easiest way to learn the format
-is simply to look through a few of the existing xml files.</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 available from <a
@@ -98,6 +92,46 @@
If not, you should take these steps manually or just drop a note onto
the project mailing list that someone else can do it.</p>
+</section>
+
+<section><title>Generating a PDF version</title>
+
+<p>The PDF version of the docs is generated by transforming the xml
+files to LaTeX using the "latex-en" Ant target. The XSLT style files
+for the transformation are under <code>style/latex/</code>. Once you
+have the <code>.tex</code> equivalent of each <code>.xml</code> file,
+you can use <code>pdflatex</code> to convert this into a pdf file.
+Recommended versions of pdflatex can be obtained as part of TeTeX
+(unix) or MikTeX (win32), but any version of TeX should be fine, as
+long as it is sufficiently complete and modern. To generate the PDF,
+you should process the <code>sitemap.tex</code> file, which contains
+the main LaTeX document code and will include all the other files.
+The outputed PDF will then be called <code>sitemap.pdf</code>, which
+you can rename how you choose.</p>
+
+<p>Some notes about the XML to LaTeX conversion are necessary.
+Although HTML and LaTeX have many similarities, there are enough
+differences between the two to make targeting both outputs a difficult
+proposition. In particular, the method of handling tables is very
+different. To aid LaTeX in understanding tables designed for HTML, a
+<code><columnspec></code> section should be added to each table.
+Inside the <code><columnspec></code>, place a <code><column
+width=".xx"/></code> for each column in the table, where
+<code>xx</code> is the percentage of the line-width devoted to that
+column. This will let the conversion handle basic tables. More
+complex stuff (like spanning rows or columns) will not work.</p>
+
+<p>In addition, <code>pdflatex</code> does not know how to incorporate
+GIF files. So any graphics must be available in PNG format.</p>
+
+<p>Finally, there are various other restrictive assumptions embedded
+in the XSLT that work for the current docs, but may need to be
+modified in the future. For example, the code that transforms
+HTML-style links to LaTeX cross-references will work only with the
+main directory and one level of subdirectory. Also,
+<code><pre></code> sections are very likely not to work well
+in LaTeX because of differences in escaping and formatting rules
+in <code>verbatim</code> sections.</p>
</section>
</body>