Imprimatur
	A Texinfo Document Checker	Sergey Poznyakoff

Imprimatur Manual (split by chapter):

Section:

Chapter:

Doc:

?

4. Integrating and Using Imprimatur

This chapter describes how to integrate Imprimatur to your project and provides a brief overview on using it.

The project wishing to use Imprimatur must meet the following requirements: it must use Autoconf and Automake and it must use Git as a version control system.

4.1 Integration

Imprimatur is designed to be used as a Git submodule. If your project uses git, integrating it is quite straightforward.

1. First of all, you need to declare a submodule. To do so, change into the top source directory of your project and run:

   git submodule add git://git.gnu.org.ua/imprimatur.git imprimatur git submodule init

   This step needs to be done only once. The first command will clone the project to the directory ‘imprimatur’. If you want another name or need to place it deeper in the directory hierarchy, change the last argument accordingly. For example, to place Imprimatur to the directory ‘doc/aux’ use:

   git submodule add git://git.gnu.org.ua/imprimatur.git doc/aux

   The second command initializes the submodule.

2. Next step is to edit the top-level ‘Makefile.am’. Add ‘-I imprimatur’ to the ‘ACLOCAL_AMFLAGS’ variable, and ‘imprimatur’ directory to the ‘SUBDIRS’ variable. For example:

   ACLOCAL_AMFLAGS = -I m4 -I imprimatur SUBDIRS = imprimatur

   If you chose another directory name during the first step, use it instead of ‘imprimatur’ in the above example.

3. Next, you need to edit the ‘configure.ac’ file and add a call to ‘IMPRIMATUR_INIT’. Normally no parameters are needed, just like that:

   IMPRIMATUR_INIT

   However, if you cloned Imprimatur into a directory with another name, the actual directory name must be supplied as the first argument. For example:

   IMPRIMATUR_INIT(doc/aux)

   See section Initialization, for a detailed description of the ‘IMPRIMATUR_INIT’ macro.

4. Now edit the file ‘Makefile.am’ located in the subdirectory where you have your Texinfo sources.
   1. To the value of ‘AM_MAKEINFOFLAGS’ variable add ‘@IMPRIMATUR_MAKEINFOFLAGS@’. This will inform makeinfo and related tools about the location of Imprimatur files (in particular, ‘rendition.texi’) and the selected rendition (see section Renditions).
   2. Define the variable ‘imprimatur_INPUT’. It must contain the names of Texinfo sources to be verified by Imprimatur. Normally, the following definition is sufficient:

      imprimatur_INPUT=$(info_TEXINFOS) $(base_TEXINFOS)

      where base stands for the base name of your Texinfo document (e.g. ‘foo’, if it is named ‘foo.texi’).

      See section imprimatur_INPUT, for a discussion of this variable and its purposes.

   3. Include the file ‘imprimatur.mk’ from the Imprimatur directory using relative addressing. For example, if your documentation subdirectory is located at the same nesting level as the directory you cloned Imprimatur to, use:

      include ../imprimatur/imprimatur.mk

      Do not use Automake substitutions nor Makefile variables in the argument to include.

   4. If you plan to use the ‘check-docs.sh’ script, define a Makeinfo variable to access it, e.g.:

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

      See section check-docs.sh, for a discussion of this script.

   Let's summarize this step by an example:

   AM_MAKEINFOFLAGS = @IMPRIMATUR_MAKEINFOFLAGS@ imprimatur_INPUT=$(info_TEXINFOS) $(foo_TEXINFOS) include ../imprimatur/imprimatur.mk CHECK_DOCS=$(top_srcdir)/@IMPRIMATUR_MODULE_DIR@/check-docs.sh

4.2 How to Use Imprimatur

To use Imprimatur, you need to include the file ‘rendition.texi’ into your main Texifo source file:

@include rendition.texi

This file provides you with macros for annotating your documentation. These macros are described in detail in Texinfo Macros. Here we present a short overview.

The most common form of annotation is the ‘@FIXME’ macro. It introduces an editor's note about something that needs a revision or clarification. For example:

The @var{fmt} argument is a database format identifier.
If it is valid, the function returns expiration interval for that
format.  @FIXME{It is not clear how to obtain negative expiration
values.}

In ‘PROOF’ rendition, this Texinfo excerpt produces the following output:

The fmt argument is a database format identifier. If it is valid, the function returns expiration interval for that format.

Editor's note: It is not clear how to obtain negative expiration values.

In other renditions, the ‘@FIXME’ macro produces no output at all.

It is supposed that you will be progressively resolving your ‘@FIXME’s while reviewing your document. During this process you can obtain a listing of all pending ‘@FIXME’ notes bu running make imprimatur-fixmes, e.g.:

$ make imprimatur-fixmes
Unresolved FIXMEs:
functions.texi:2231: It is not clear how to obtain negative expiration

It is especially handy if you use ‘compile’ mode of GNU Emacs, as you can then easily move editing point to the place when a particular note appears by placing the cursor on the corresponding line and hitting Enter (see (emacs)Compilation Mode section `Compilation Mode' in The Emacs Editor).

Another common annotation is the ‘@UNREVISED’ macro. Placed after a sectioning command, it will draw reviewer's attention to nodes that need a revision. A listing of such nodes can be obtaining using the ‘imprimatur-unrevised’ rule:

$ make imprimatur-unrevised
Unrevised nodes:
mailfromd.texi:2567:@UNREVISED
functions.texi:1508:@UNREVISED

The ‘@UNREVISED’ macro produces output in ‘PROOF’ and ‘DISTRIB’ renditions. In ‘PUBLISH’ rendition it results in compilation error. This behavior is intended to help avoid unrevised nodes from appearing in final published texts.

When writing initial revision of a node you may need to mark a point where a cross-reference to another, not yet written node should be. The intent is to replace this mark with an actual cross-reference command when the node referred to has already been written. For that purpose Imprimatur provides three annotations: ‘@FIXME-ref’, ‘@FIXME-xref’, and ‘@FIXME-pxref’. These macros are similar to corresponding Texinfo commands, except that they take a single argument. In fact in ‘PUBLISH’ rendition these macros are equivalent to their Texinfo counterparts. In ‘PROOF’ and ‘DISTRIB’ rendition, however, they produce a cross-reference explicitly marked as referencing a non-existent node. For example:

Enable transcript of @acronym{SMTP} sessions to the log
channel.  @FIXME-xref{Logging and Debugging}.

This Texinfo fragment produces:

Enable transcript of SMTP sessions to the log channel. See Logging and Debugging (Editor's note: dangling link).

To list unresolved cross-reference use the ‘imprimatur-refs’ Makefile rule:

$ make imprimatur-refs
Unresolved cross-references:
options.texi:4951: Logging and Debugging

?