Archive:Useful Documentation Scripts

We do not expect every writer or editor to be an extremely experienced system administrator. This page is part of the overall effort to lower entry barriers to the DocsProject. Some of the scripts here are also used in various FDP processes.

DocBook preparation
The DocsProject does not use DocBook  tags for sections in final markup, because this reduces the portability of sections. Use  instead. Similarly, although sections should each have an  attribute, the attribute should not use a section number (like  ). Use  instead.

The following command will fix this irregularity:

sed -i 's/<\(\/\)\?sect[0-9] /<\1section/g' my-docbook-file.xml

Similarly, although sections should each have an  attribute, the attribute should not use a section number (like  ). Use  instead.

The following command will fix this irregularity:

sed -i 's/id="s[0-9] -/id="sn-/g' my-docbook-file.xml

GNU Emacs is the standard tool for DocsProject work. Although contributors may use any tool they wish for initial markup and drafts, most DocsProject contributors  use Emacs for markup and editing. Emacs recognizes "sentences" as being groups of words followed by a period (or "full stop") and two spaces. The convention of following a period with two spaces has fallen out of the mainstream. This short command will take care of most instances of this irregularity:

sed -i 's/\. \([A-Z] \)/\. \1/g' my-docbook-file.xml

Docbook Validation
GavinHenry was getting quite fed up when running:

make html

and the xml not being valid because of typos, so he wrote a tiny wrapper for xmllint, a xmlto program.


 * validxml (html version)


 * Actual script

It's a Perl program.

Or you could just use (previously undocumented) the document build system feature:

make validate-xml make validate-xml-en_US

Package Listing
This Python script can be used for listing packages for the  ReleaseNotes.