Imprimatur
	A Texinfo Document Checker	Sergey Poznyakoff

Imprimatur Manual (split by chapter):

Section:

Chapter:

Doc:

?

7. Makefile Rules

The file ‘imprimatur.mk’ contains Makefile rules for verifying the Texinfo documents. It should be included into ‘Makefile.am’ located in the directory where Texinfo sources reside. For example, if your documentation subdirectory is located at the same nesting level as the directory you cloned imprimatur into, then add the following statement:

include ../imprimatur/imprimatur.mk

Note that Automake is supposed to expand this statement, i.e. to replace it with the actual contents of ‘imprimatur.mk’ in the resulting ‘Makefile.in’. This is possible only if the argument to include is a literal string. Do not use Automake substitutions nor Makefile variables in the argument to include.

The rules defined in ‘imprimatur.mk’ operate on Texinfo documents listed in the variable ‘imprimatur_INPUT’

Makefile Variable: imprimatur_INPUT

Whitespace-delimited list of Texinfo source files to process. It is often convenient to specify source files via the ‘name_TEXINFOS’ Automake variables. For example, if your main source has the name ‘myproj.texi’ it would normally be added to the Makefile variable ‘info_TEXINFOS’ and the variable ‘myproj_TEXINFOS’ would contain subordinate Texinfo sources it depends on. Then, you would declare ‘imprimatur_INPUT’ as follows:

imprimatur_INPUT=$(info_TEXINFOS) $(myproj_TEXINFOS)

Once this variable is defined, you can use the following rules:

Makefile Rule: imprimatur-format

Checks whether the files contain tabs (ASCII 9). If so the following diagnostics is displayed:

Sources contain tabs; run make imprimatur-untabify

See imprimatur-untabify.

Makefile Rule: imprimatur-refs

Checks if the sources contain unresolved cross-references, i.e. any of the macros ‘FIXME-ref’, ‘FIXME-xref’ or ‘FIXME-pxref’ (see section FIXME-ref). If so, the prominent diagnostics is displayed and the rule exits with code 2. For example:

Unresolved cross-references: mailfromd.texi:3535: existing categories mailfromd.texi:4951: optimizer mailfromd.texi:9899: debug configuration functions.texi:1273: filter chains

Makefile Rule: imprimatur-fixmes

Checks whether the sources contain ‘@FIXME’ macros (see section FIXME). If so, list the location of each ‘@FIXME’ along with its content. If the content has several lines, only first of them is displayed. For example:

Unresolved FIXMEs: functions.texi:1518: Check references to 'Polling functions' functions.texi:1562: Give more details and references. functions.texi:2231: How to obtain negative

Makefile Rule: imprimatur-writemes

Checks whether the sources contain empty nodes, i.e. nodes marked with the ‘@WRITEME’ macro (see section WRITEME). If so, it displays locations of each ‘@WRITEME’, e.g.:

Empty nodes: calloutd.texi:6:@WRITEME mfdbtool.texi:148:@WRITEME

Makefile Rule: imprimatur-empty-nodes

An improved version of ‘imprimatur-writemes’. This rule reports nodes which do not have any text and those marked with the ‘@WRITEME’ macro.

Unlike the rest of rules, ‘imprimatur-empty-nodes’ analyzes files in ‘$(info_TEXINFOS)’. It reads each file and parses it, honoring any ‘@include’ statements.

This rule outputs to standard error the names and locations of empty nodes. For nodes marked with the ‘@WRITEME’ macro, location refers to the place where the macro was encountered and the actual node name is prefixed with ‘(@WRITEME)’, as shown in the example below:

Empty nodes: ./calloutd.texi:6: calloutd ./mfdbtool.texi:148: Configuring mfdbtool ./upgrade.texi:31: (@WRITEME) Upgrading from 7.0 to 8.0

If you wish to excerpt any of the input files from being verified by this rule, you can do so by adding the following pragmatic comment at the beginning of such files:

@c imprimatur-ignore

Makefile Rule: imprimatur-unrevised

Checks whether the sources contain nodes which need revision, i.e. the ones marked with the ‘@UNREVISED’ macro (see section UNREVISED). If so, display locations of each ‘@UNREVISED’, e.g.:

Unrevised nodes: mailfromd.texi:2567:@UNREVISED mailfromd.texi:2694:@UNREVISED

Makefile Rule: imprimatur-check-sentence-spacing

Checks if sentence spacing is correct throughout the sources. By default, American sentence spacing is assumed. French sentence spacing is used if IMPRIMATUR_INIT was called with the ‘frenchspacing’ option (see section frenchspacing).

If the sentence spacing is wrong, this rule displays the following diagnostics:

Sources contain single-space sentence separators. Run make imprimatur-fix-sentence-spacing to fix.

If French spacing is declared, the diagnostics will read:

Sources contain double-space sentence separators. Run make imprimatur-fix-sentence-spacing to fix.

Makefile Rule: imprimatur-fix-sentence-spacing

Fixes sentence spacing. The action of this rule depends on the setting of ‘frenchspacing’ option (see section frenchspacing).

Makefile Rule: imprimatur-basic-checks

Runs the following rules in that order:

imprimatur-format imprimatur-check-sentence-spacing imprimatur-refs imprimatur-fixmes imprimatur-empty-nodes imprimatur-unrevised

Makefile Rule: imprimatur-master-menu

Creates a master menu for each Texinfo file in ‘${info_TEXINFOS}’, taking into account included files.

This rule uses Emcas to create a master menu that follows the top node. The master menu includes every entry from all the other menus. It replaces any existing ordinary menu that follows the top node.

The effect of this rule differs from that of texinfo-master-menu (see texinfo-master-menu: (texinfo)Updating Commands section `Updating Commands' in Texinfo Manual) in that it takes into account included Texinfo files.

Makefile Rule: imprimatur-untabify

Converts all tabs in Texinfo files to multiple spaces, preserving columns. This rule uses emacs to do the job.

Makefile Rule: imprimatur-final

Runs ‘imprimatur-untabify’ and ‘imprimatur-master-menu’.

?