gnome-doc-utils

gnome-doc-utils is a super handy package that comes with a bunch of tools for working on documentation in the Gnome project. It's your go-to solution for building docs and managing auxiliary files right from your source tree. Plus, it includes the essential DocBook XSLT stylesheets previously distributed with Yelp. With Gnome version 2.8 and beyond, gnome-doc-utils becomes a requirement for using XSLT with Yelp.

Testing with gnome-doc-utils

The test directory is where the real fun begins! It's packed with various tests for gnome-doc-utils. Explore directories like testdocn (with n as a positive number), which mimic source trees for documentation, mirroring actual project layouts. Additionally, the testdocs folder houses unit tests by Norm and his team for the DocBook stylesheets.

Documentation Directory

For insights on using gnome-doc-utils effectively, head to the doc directory! Usually, gnome-doc-utils itself is the key to building this documentation, and mechanisms are available for a smooth start.

XSLT Files in gnome-doc-utils

The xslt directory boasts a collection of all the XSLT files you'll ever need. Notable sections include xslt/docbook housing the DocBook XSLT files and xslt/gettext featuring handy utilities for automatic text translation.

A Playground for Ideas

The sandbox directory, though not always included, is an excellent space for experimenting with new concepts, especially if you have a CVS checkout.

Translation Tools Available

If your focus is on translation, don't miss the xml2po directory! Developed by Danilo Segan, this tool facilitates the translation of various XML formats, making it ideal for DocBook projects.

Your Testing Ground!

Explore your build system using any of the testdoc directories mentioned earlier. These mimic real projects, offering a perfect environment for testing. With gnome-doc-utils building its documentation (found under doc), it's essentially testing itself!

Pushing Your Limits with Tests

If you're keen on thoroughly testing the DocBook stylesheets, navigate to test/testdocs. Here, you'll discover unit tests from docbook-testdocs. A simple 'make' command will help effortlessly build each test!

If you need a larger document to work on, try transforming resources like the Gnome User Guide or the Gnumeric Manual—they make splendid test documents.

Your Path Forward!

Dive into gnome-doc-utils for incremental improvements. Whether working on building tools or implementing XSLT elements, take your time to understand the nuances. Generate an HTML report of implemented elements using XML Starlet with a 'make report.html' command in the xslt/docbook/html directory.

Additionally, xsldoc, a part of gnome-doc-utils itself, provides inline documentation. Feel free to explore and contribute! Find xsldoc's output under doc/xslt.