Imprimatur Manual (split by chapter): | ![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
? |
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.
Imprimatur
is designed to be used as a Git submodule. If
your project uses git
, integrating it is quite
straightforward.
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.
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.
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.
makeinfo
and related tools about the location of
Imprimatur
files (in particular, ‘rendition.texi’) and
the selected rendition (see section Renditions).
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.
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.
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 |
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 |
![]() |
![]() |
![]() |
![]() |
![]() |
? |
Copyright © 2011 Sergey Poznyakoff
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.