Gnome-doc-utils is a set of utilities designed for the Gnome project to help with documentation tasks.
The gnome-doc-utils package is a collection of utilities specifically designed for the Gnome project's documentation needs. Among its features are utilities for building documentation and auxiliary files in your project's source tree. It also includes the DocBook XSLT stylesheets that were originally distributed with Yelp. In Gnome 2.8 and beyond, gnome-doc-utils is a necessary requirement for XSLT with Yelp.
The test directory within gnome-doc-utils contains a variety of tests to evaluate its overall performance. These tests come in the form of directories labeled testdocn, where n represents a positive integer. Each directory contains skeleton source trees which include documentation designed to emulate an actual project with the same layout. Furthermore, the directory labeled testdocs includes unit tests from docbook-testdocs, which were created by Norm and Co. for the DocBook stylesheets. A README file is also provided with instructions on how to modify any of the files within gnome-doc-utils CVS.
The doc directory contains all of the documentation for gnome-doc-utils. In most cases, gnome-doc-utils will need to be used to build its own documentation. Luckily, mechanisms are in place for a smooth bootstrapping process.
For all of the XSLT within gnome-doc-utils, there is the xslt directory. Of particular note is the xslt/docbook directory, which contains the DocBook XSLT. Additionally, xslt/gettext contains an XSLT gettext utility for automatically translating text.
The sandbox directory is not distributed and only appears for those who have a CVS checkout. The sandbox function allows developers to experiment and play around with new ideas without fear of affecting the core gnome-doc-utils functionality.
Lastly, the xml2po directory includes the xml2po tool created by Danilo Segan for arbitrary XML format translation. It is used by gnome-doc-utils for DocBook translation.
Testing for gnome-doc-utils can be done by utilizing any of the testdocn directories. These directories are set up to behave exactly like a real project, with skeleton source trees ready for evaluation. Gnome-doc-utils utilizes itself to build its documentation, under the doc directory, essentially making itself a test subject.
For testing the DocBook stylesheets, use the test/testdocs directory. These tests were taken from the docbook-testdocs package on docbook.sourceforge.net and created by Norm and Co. Each test generally tests a small number of related DocBook elements. Additional tests may be added by following the instructions in test/testdocs/README. Transforming large documents with gnome-doc-utils XSLT is also an excellent way to test its features.
When it comes to hacking and enhancing gnome-doc-utils, incremental improvements are essential for success. Modifications to gnome-doc-utils.m4 and gnome-doc-utils.make can be tested by building test docs and noting what doesn't work. Gnome-doc-utils.make has a list of all the high-level targets that should be fully supported. Improvements to the DocBook XSLT involve finding an element that isn't implemented and implementing it. For those with XML Starlet installed, a nice HTML report on the status of element implementation can be obtained with "make report.html" in the xslt/docbook/html directory. The XSLT is also documented with xsldoc, which is installed with gnome-doc-utils. Feel free to modify xsldoc and add documentation to the manual under doc/xslt.
The test directory within gnome-doc-utils contains a variety of tests to evaluate its overall performance. These tests come in the form of directories labeled testdocn, where n represents a positive integer. Each directory contains skeleton source trees which include documentation designed to emulate an actual project with the same layout. Furthermore, the directory labeled testdocs includes unit tests from docbook-testdocs, which were created by Norm and Co. for the DocBook stylesheets. A README file is also provided with instructions on how to modify any of the files within gnome-doc-utils CVS.
The doc directory contains all of the documentation for gnome-doc-utils. In most cases, gnome-doc-utils will need to be used to build its own documentation. Luckily, mechanisms are in place for a smooth bootstrapping process.
For all of the XSLT within gnome-doc-utils, there is the xslt directory. Of particular note is the xslt/docbook directory, which contains the DocBook XSLT. Additionally, xslt/gettext contains an XSLT gettext utility for automatically translating text.
The sandbox directory is not distributed and only appears for those who have a CVS checkout. The sandbox function allows developers to experiment and play around with new ideas without fear of affecting the core gnome-doc-utils functionality.
Lastly, the xml2po directory includes the xml2po tool created by Danilo Segan for arbitrary XML format translation. It is used by gnome-doc-utils for DocBook translation.
Testing for gnome-doc-utils can be done by utilizing any of the testdocn directories. These directories are set up to behave exactly like a real project, with skeleton source trees ready for evaluation. Gnome-doc-utils utilizes itself to build its documentation, under the doc directory, essentially making itself a test subject.
For testing the DocBook stylesheets, use the test/testdocs directory. These tests were taken from the docbook-testdocs package on docbook.sourceforge.net and created by Norm and Co. Each test generally tests a small number of related DocBook elements. Additional tests may be added by following the instructions in test/testdocs/README. Transforming large documents with gnome-doc-utils XSLT is also an excellent way to test its features.
When it comes to hacking and enhancing gnome-doc-utils, incremental improvements are essential for success. Modifications to gnome-doc-utils.m4 and gnome-doc-utils.make can be tested by building test docs and noting what doesn't work. Gnome-doc-utils.make has a list of all the high-level targets that should be fully supported. Improvements to the DocBook XSLT involve finding an element that isn't implemented and implementing it. For those with XML Starlet installed, a nice HTML report on the status of element implementation can be obtained with "make report.html" in the xslt/docbook/html directory. The XSLT is also documented with xsldoc, which is installed with gnome-doc-utils. Feel free to modify xsldoc and add documentation to the manual under doc/xslt.
What's New
Version 0.18.0: N/A