Imprimatur
	A Texinfo Document Checker	Sergey Poznyakoff

Imprimatur Manual (split by chapter):

Section:

Chapter:

Doc:

?

8. check-docs.sh

The shell script ‘check-docs.sh’ provides a mechanism for verifying if all items declared in a program are documented in its Texinfo docs. By items we mean here any external entities visible by the end user and designed for his use, such as command line options, configuration statements, external functions and the like. Any such item is supposed to have the following properties:

class

A descriptive name for the group of items this one belongs to. It is intended to be human readable and can consist of arbitrary number of characters. E.g. ‘Command line option’ or ‘External function’, or the like.

The script prints class name at the beginning of its output.

identifier

A string of characters uniquely identifying this item among other items of the same class. E.g., a function name if the item is a function, or option name (without the leading dashes) if the item is a command line option.

declaration

A statement in the source code where this item is declared. E.g. a function declaration or option definition. The declaration must contain item identifier so that it can be extracted from it using a regular expression.

description

A statement in the Texinfo document which contains a description of this item. It must meet the same requirement as the declaration, i.e. it should be possible to define a regular expression for extracting the item identifier from the description.

The script is invoked as follows:

check-docs.sh code-sed doc-sed sources -- makeinfo-args

Notice mandatory double-dash.

Its arguments are:

class

Item class. Make sure you quote it, if it contains characters special for the shell.

code-sed

A regular expression to extract item identifiers from declarations. It must use a parenthesized group to mark the identifier (see (sed)The "s" Command section `REPLACEMENT' in Sed Manual), and the ‘p’ flag or command to output it (see (sed)Common Commands section `Print out the pattern space' in Sed Manual).

For example, the following expression extracts function name from its declaration in C code:

s/^\([_a-zA-Z][_a-zA-Z0-9]*\) *(.*/\1/p

It assumes that identifiers start in column 0 and is simplified a bit.

doc-sed

A regular expression to extract item identifiers from descriptions. It is in all respects similar to code-sed.

For example, the expression below extracts identifiers from ‘@defmac’ statements:

'/@defmac/s/@defmac *\([-a-zA-Z][-a-zA-Z0-9]*\).*/\1/p'

sources

A list of source files to apply code-sed to.

makeinfo-args

A command which produces preprocessed Texinfo source at its output. Normally, it is makeinfo -E - with some additional arguments. The doc-sed expression is applied to its output.

The ‘check-docs.sh’ script collects identifiers produced by the two sed expressions and computes two sets of differences: identifiers missing from the docs, but present in the sources and the ones missing from the sources but present in the docs. If both lists are empty, the script exits silently with status ‘0’. Otherwise, it reports the differences and exits with status ‘1’.

The script is normally used from Makefile rules in the ‘Makefile.am’ file located in the documentation directory. You may have any number of such rules, each one for a particular class of items. It is recommended to declare a Makeinfo variable pointing to the script, such as:

CHECK_DOCS = $(top_srcdir)/@IMPRIMATUR_MODULE_DIR@/check-docs.sh

The makeinfo-args parameter is usually as follows:

$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -E - $(info_TEXINFOS) 

To illustrate this, here is a Makefile rule used by Imprimatur itself to verify that all rules from ‘imprimatur.mk’ are documented:

check-rules:
        @$(CHECK_DOCS) "Makefile rules" \
         '/^imprimatur-.*:/s/:.*//p' \
         's/@deffn {Makefile Rule}  *//p' \
         imprimatur.mk -- \
         $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) \
                -I $(srcdir) -E - $(info_TEXINFOS)

To illustrate its output, suppose that the rule ‘imprimatur-fixmes’ is not documented. Then, you will get:

$ make -k check-rules
Not documented Makefile rules:
imprimatur-fixmes

Similarly, if the docs document rule ‘imprimatur-fixme’ (presumably a typo: the ‘s’ is missing), you'll get:

$ make -k check-rules
Non-existing Makefile rules:
imprimatur-fixme

In both cases, the exit code will indicate an error.

?