Menu
▾
▴
[Plplot-cvs] SF.net SVN: plplot:[8795] trunk/www/documentation.php.in
|
From: <ai...@us...> - 2008-09-22 23:43:48
|
Revision: 8795
http://plplot.svn.sourceforge.net/plplot/?rev=8795&view=rev
Author: airwin
Date: 2008-09-22 23:43:36 +0000 (Mon, 22 Sep 2008)
Log Message:
-----------
Update website comments about our DocBook-based documentation system.
Modified Paths:
--------------
trunk/www/documentation.php.in
Modified: trunk/www/documentation.php.in
===================================================================
--- trunk/www/documentation.php.in 2008-09-22 20:18:14 UTC (rev 8794)
+++ trunk/www/documentation.php.in 2008-09-22 23:43:36 UTC (rev 8795)
@@ -13,6 +13,12 @@
<div id="contentwrapper">
<div id="leftside">
<h3>PLplot Documentation</h3>
+<p>
+For those wishing to make some contribution to PLplot, helping out with the documentation is a good place to start. DocBook/XML syntax is quite straightforward to understand if you simply follow the form of what is already done in the files in the doc/docbook/src subdirectory of the source tree. However, if you want to dig a little deeper into DocBook, then this on-line book, <a href="http://www.docbook.org/tdg/en/html/docbook.html">"DocBook: The Definitive Guide"</a>, is an excellent reference.
+</p>
+<p>
+The documentation results below have been generated from our DocBook/XML source files in doc/docbook/src using a variety of DocBook backend tools. The documentation build happens automatically (only on Linux since the required tools are only available for that O/S) with our CMake-based build system if you specify the cmake option -DBUILD_DOC=ON. For more details about building this documentation and testing it, please look at the file doc/docbook/README.developers in the source tree.
+</p>
<ul class="arrowlist">
<li> <a href="docbook-manual/@BASE_HTML@">Browse the latest on-line documentation</a> </li>
<li> <a href="docbook-manual/@BASE@.ps.gz">PostScript form of documentation (<?php $size = 0.1*(int)(filesize("docbook-manual/@BASE@.ps.gz")/1024/102.4); echo $size;?> MB)</a> </li>
@@ -22,113 +28,6 @@
<li> <a href="docbook-manual/@BASE_MAN@.tar.gz">Man pages tarball (API chapter in nroff format) (<?php $size = (int)(filesize("docbook-manual/@BASE_MAN@.tar.gz")/1024); echo $size;?> KB)</a> </li>
<li> <a href="docbook-manual/@BASE_HTML@.tar.gz">HTML results tarball (<?php $size = (int)(filesize("docbook-manual/@BASE_HTML@.tar.gz")/1024); echo $size;?> KB)</a> </li>
</ul>
- <h4>The Current PLplot Documentation Project</h4>
- <p>
- The previous form of the <a href="http://plplot.sf.net">PLplot</a>
- documentation was quite extensive but had two issues. (1) It was
- written in LaTeXinfo form which is no longer supported. (2) It was
- dated (no documentation updates since 1995 because of issue [1]). To
- address issue (1) <a
- href="mailto:rafael_at_debian_dot_org_REMOVE_THE_UNDERSCORES">Rafael
- Laboissiere</a> with some help from <a
- href="mailto:irwin_at_beluga_dot_phys_dot_uvic_dot_ca_REMOVE_THE_UNDERSCORES">Alan
- W. Irwin</a> converted the existing documentation from LaTeXinfo to
- DocBook 4.1 XML form. As a result of this conversion project all
- chapters of the <a
- href="ftp://dino.ph.utexas.edu/plplot/docs/plplot.ps.gz">original
- documentation</a> are now available in the above different forms
- resulting from processing the DocBook source. Issue (2) is being
- addressed by <a
- href="mailto:irwin_at_beluga_dot_phys_dot_uvic_dot_ca_REMOVE_THE_UNDERSCORES">Alan
- W. Irwin</a> with some help from <a
- href="mailto:rafael_at_debian_dot_org_REMOVE_THE_UNDERSCORES">Rafael
- Laboissiere</a>, and others are encouraged to participate as well.
- Descriptions of each function in the API have been greatly improved
- as a first step in this aspect of the project.
- </p>
- <p>
- The DocBook source of the documentation is now under svn control at
- the <a href=http://sourceforge.net/projects/plplot/>PLplot
- sourceforge project site</a>. To build the documentation, follow the
- svn instructions at that site to synchronise your local PLplot
- directory tree with the svn repository (using svn checkout or svn
- update as appropriate). Then follow the directions in
- plplot/doc/docbook/README.developers to build the above results. If
- you do not have svn write access, please post your suggested
- documentation changes to <a
- href="mailto:ir...@be...">Alan W. Irwin</a> as a patch
- file on one of the *.xml DocBook source files. The XML (Extensible
- Markup Language) syntax for DocBook is straightforward and can easily
- be inferred from the existing DocBook XML files, but there is <a
- href="http://www.oasis-open.org/docbook/documentation/reference/index.html">excellent
- documentation</a> of DocBook as well, if you really need it.
- </p>
-
- <h4>Motivation for using DocBook</h4>
- <p>
- It is
- <a href="http://www.oasis-open.org/docbook/documentation/reference/index.html">well
- documented!</a> ;-)
- </p>
-
- <p>
- <a href="http://www.oreilly.com/davenport/">DocBook</a> fulfils
- documentation needs using industry-standard DTD's (Document Type
- Definition's) based on XML. The idea is that the documenter uses
- logical markup, and the typesetting details (fonts, spacing, layout,
- etc.) are taken care of by the DTD's. This important and powerful
- distinction between logical markup and typesetting allows documenters
- to concentrate on producing documentation while the look and feel of
- the results can be adjusted afterward by adjusting the DTD's through
- so-called driver files.
- </p>
-
- <p>
- DocBook is gaining a lot of momentum now: <a
- href="http://www.ora.com">O'Reilly</a> uses it to compose their
- books, the <a href="http://www.linuxdoc.org/">Linux Documentation
- Project</a> uses it (<a
- href="http://www.linuxdoc.org/LDP/LDP-Author-Guide/index.html">see
- this</a>), the <a href="http://www.kde.org">KDE project</a> uses it
- (<a href="http://i18n.kde.org/teams/en/">see this</a>), the <a
- href="http://www.gnome.org">Gnome project</a> uses it (<a
- href="http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/">see
- this</a>), and the latest version of <a
- href="http://www.sgmltools.org">SGML-Tools</a> is based on
- DocBook. Another big project that will use DocBook for <a
- href="ftp://ftp.ggi-project.org/pub/ggi/doc/">its documentation</a>
- is the <a href="http://www.ggi-project.org/">General Graphics
- Interface (GGI) Project</a>.
- </p>
-
- <p>
- DocBook is just a DT definition. The <a
- href="http://www.jclark.com/jade/">jade</a> suite or the <a
- href="http://openjade.sourceforge.net">OpenJade</a> suite and
- appropriate perl extension modules can be used to convert from the
- XML sources using several different back ends (currently for the
- PLplot project, man pages corresponding to each function documented
- in the API chapter and the complete PLplot documentation in HTML,
- dvi, postscript, pdf, and info forms).
- </p>
-
- <p>
- There are at least two nice aspects to using DocBook. First, the
- source is suitable for CVS control (see above). Second, it is
- possible to parse the source with existing XML parsers. Thus, for
- example, we process the XML form of the API chapter (api.xml) with a
- perl script to generate our man pages for each function in the API.
- </p>
-
- <h4>Contact</h4>
- <p>
- If you are interested in contributing to this project, please
- contact <a
- href="mailto:rafael_at_debian_dot_org_REMOVE_THE_UNDERSCORES">Rafael
- Laboissiere</a> or <a
- href="mailto:mailto:irwin_at_beluga_dot_phys_dot_uvic_dot_ca_REMOVE_THE_UNDERSCORES">Alan
- W. Irwin</a>
- </p>
</div>
<?php pageSidebar(); ?>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
