Repodoc script
1.
Usage
How to use repodoc?
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' 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]) |
 |
The contents of this document are licensed under the Creative Commons -
Attribution / Share Alike license.
|
