Repodoc script

1. Usage

It's quite important to remember that repodoc (currently) only works inside a Gentoo CVS dir structure. If you are a dev, you already should have one. If you are a gentoo contributor but not a dev, you can use the annoncvs Gentoo service to have a cvs working copy.

If you really don't like to have a full Gentoo CVS dir you can read the workaround instructions about how to recreate it.

To use repodoc, you just need to run as follow:

Code Listing 1.1: Running repodoc

# repodoc [params] <files>

How repodoc works

Repodoc is designed to check different errors which could appear on Gentoo docs. The code necessary for every kind of error is contained in a module. Repodoc is able to know what modules a doc needed in order to make a custom check for every doc attending to the type, language, etc. Please, read the module section carefully to know what they do.

Repodoc implements several ways to show the modules results. Check the frontend section to explore the different possibilities.

Modules

Modules are the main part of repodoc and all users should know what they do and what will be their output.

Module	Description
Banned	Checks the doc to detect certain text patterns that shouldn't appear or the user want to be notified when they do. You can see in the log, the line number where the pattern was found, the content of line and, marked on the content (usually by uppercase), the pattern. Also you can define your own user banned patterns via ~/.repodoc/config/patterns using the rule: "special\|basic $language\|all $banned-word\|$sed-pattern $id". special for sed-pattern or basic for banned-word. all for applying independently of the language. If you like to define your own patterns, please, see banned.module code in modules/ dir for more info and examples.
Dyn-meta	Checks dynamic generated docs (index, list and overview) if they have properly set up the link to metadoc.
Include	Checks the handbook index files to make sure the include chapter links exists.
Header	Checks if the file has the appropriate header tag to be used by CVS.
Lang	Checks (only in translations) if the attribute lang is set properly.
LangLinks	Checks (only in translations) if gentoo links point to an English doc and warn if a translation for the linked doc is available.
Length	Looks for lines longer than 80 chars with some exceptions: Header tag, comments, long links, code samples, pre tags, etc. It will show the lines which doesn't match these conditions. You can see in the log, the line number and content.
Links	Checks if the links defined on the doc are sane or if they are broken. Actually support all kinds of internal Gentoo cvs links (/proj/, /doc/, etc.), anchors and auto generated anchors (excluding handbook ones).
Metalinks	Checks the links in metadoc to be sure that the docs pointed by them exist and also takes care of check if there is a translation available in the links which point to English original docs.
Path	Checks if the path attribute points to the correct and absolute doc path.
Trans	Looks for different content into an original (English) doc and its i translation. Basically, it parses both files to extract useful xml tags and compares the result. Output with "+" means you have tags in translation which don't appear on the original doc, "-" means the translation lacks of some tags which appear on the English doc. You can see, just after the xml tag, its order inside a chapter or a section. The reference chapter and section are just behind. Please be careful using this module because is still under heavy development.
Up2date	Checks if the doc date and version tags are the same than the original English doc ones. Obviously, this module only is applied on translations and on docs which have both tags. If this module gives a warn, it could be because the doc is out of date or because you forgot to sync the version and date with the English one.
UTF-8	Checks the UTF-8 doc sanity. It uses part of implementation from glep31 thanks to ciaranm and adapted by ferdy. Provides better output than xmllint and allows to see if the problem is related to utf-8.
Version	Checks if the doc version tag is the same than the original English doc one. This module works on docs which only have version and no date tag, such as metadoc.
XML	Checks valid xml using xmllint. Also check the utf8 charset.

Repodoc frontends

Repodoc provides frontends to show info in different ways:

Default
List
Gtk

'Default' frontend: is used if no frontend parameter is passed to repodoc. Designed to show complete checks info about each doc.

Figure 1.1: Default frontend screenshot

'List' frontend: execute all tests (like default) but only shows one output per file. The output is the worst result found among all tests done on the doc.

Figure 1.2: List frontend screenshot (repodoc -o list [files])

From the output of list frontend above we can know:

metadoc passes all the test, yeah!
mysql-updagrading failed at least, one of the tests
alsa-guide has at least one warning but no major issues

'Gtk' frontend: presents the modules results in a graphical way, using the gtk libraries. The frontend is written in GTK# and it's enabled via USE flag.

Figure 1.3: GTK frontend screenshot (repodoc -o gtk [files])