Imprimatur
	A Texinfo Document Checker	Sergey Poznyakoff

Imprimatur Manual (split by chapter):

Section:

Chapter:

Doc:

?

6. Texinfo Macros

The file ‘rendition.texi’ defines helper macros which serve to annotate Texinfo sources. Expansion of these macros depends on the rendition of the document.

Macro: WRITEME

Use this macro to mark the nodes which need to be written. Normally, you would place it immediately after a sectioning command. When in ‘PUBLISH’ rendition, this macro forces compilation error, because one would hardly want empty nodes to appear in the published document. Otherwise, it produces the following text:

Editor's note: This node is to be written.

Macro: UNREVISED

Use this macro to mark the nodes which need a revision. Normally, you would place it immediately after a sectioning command.

This macro acts similarly to ‘@WRITEME’. When in ‘PUBLISH’ rendition, it forces a compilation error. In ‘PROOF’ and ‘DISTRIB’ renditions, it produces the following expansion:

Editor's note: The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised.

Macro: FIXME (text)

The ‘@FIXME’ macro adds an editor's note to the file. The argument text gives the content of the note.

The purpose of the note is to draw reviewer's attention to something near this point of the document. It is of some importance only to the author and reviewers of the document, so it produces output only in ‘PROOF’ revision. Consider, for example, this text:

The @option{-I @var{DIR}} command line option adds a directory to the program's search path. @FIXME{Document the initial value of the search path.}

In ‘PROOF’ rendition it would produce the following:

The ‘-I DIR’ command line option adds a directory to the program's search path.

Editor's note: Document the initial value of the search path.

The three macros below serve as placeholders for the corresponding cross-reference commands:

Macro: FIXME-ref (text)

Use this macro for ‘@ref’-style cross-references. In ‘PUBLISH’ rendition it is entirely equivalent to @ref{text}.

Macro: FIXME-xref (text)

Use this macro for ‘@xref’-style cross-references. In ‘PUBLISH’ rendition it is equivalent to @xref{text}.

Macro: FIXME-pxref (text)

Use this macro for ‘@pxref’-style cross-references. In ‘PUBLISH’ rendition it is entirely equivalent to @pxref{text}.

Use one of these macros when you need to add a cross-reference to a node or anchor which does not exist yet. They will create a dangling reference which allows for translating Texinfo source without errors, and at the same time serves as a reminder to you that the node referred to still needs to be written (see section imprimatur-fixmes). Once you create the node, you will fix the reference by simply removing the ‘FIXME-’ prefix after the ‘@’ sign.

To illustrate the output produced by these macros, consider the following Texinfo fragment:

@FIXME-xref{regexp}, for more information about regular expressions.

In ‘PROOF’ mode it produces:

See regexp (Editor's note: dangling link), for more information about regular expressions.

In ‘DISTRIB’ rendition, the output is:

See regexp, for more information about regular expressions.

?