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 <sect1>...<sect9> tags for sections in final markup, because this reduces the portability of sections. Use <section> instead. Similarly, although sections should each have an id attribute, the attribute should not use a section number (like "s2-some-section"). Use "sn-some-section" 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 id attribute, the attribute should not use a section number (like "s2-some-section"). Use "sn-some-section" 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 .