Imprimatur
	A Texinfo Document Checker	Sergey Poznyakoff

Imprimatur Manual (split by node):

Section:

Chapter:

Doc:

?

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

Imprimatur Manual (split by node):

Section:

Chapter:

Doc:

?