Mallard is a markup language which was created explicitly for writing topic-oriented documentation. It is used for a number of projects, most notably for GNOME developer and user documentation.
For the purposes of this guide, we will assume that your Mallard pages are in the <project>/docs/C/ directory.
The usual workflow for writing Mallard pages should be relatively consistent:
- Write the pages
- Spell check
- Check licenses, attribution and revision information
- Run yelp-check to validate
- Preview the pages
- Commit and push your changes
yelp-tools is a set of tools which will make working with Mallard easier. yelp-tools are available for installation in the Apertis SDK.
yelp-tools contains a number of useful tools:
- yelp-build, for building Mallard pages into HTML and other formats
- yelp-check, a set of validation tools
- yelp-new, for creating Mallard template pages
Of these tools, yelp-check is the most useful for writers. It allows you to validate the page, check that all the links work correctly, that all pages are included, that licenses are specified correctly, that all media files exist and so on. For more information on how to use the validation tools, run yelp-check validate.
A typical pre-commit validation run should include:
$ yelp-check validate docs/C/*.page $ yelp-check license --totals docs/C/*.page $ yelp-check links docs/C/*.page
Note that you need to have internet access to be able to run yelp-check validate.
View your pages
You can use Yelp, an application which is shipped with the Apertis SDK, to preview your Mallard pages or you can use yelp-build which comes as part of yelp-tools to generate HTML or another format that you can view.
If you have Yelp installed, you can run the following command in a terminal from your project directory:
$ yelp docs/C/
Build the docs
Make sure that you have yelp-tools installed. To build HTML from your Mallard pages, run the following command in a terminal from your project directory:
$ yelp-build html -o html-docs /docs/C/.
You will find the HTML docs in the <project>/html-docs directory once they are built.
You can also build other formats and use caches for larger projects. For more information, see the yelp-build documentation.