2. Introduction

Creating a documentation for software is a difficult task which is equally important as writing the software itself. In particular, it is important that the documentation be consistent with the software it describes and that it cover all aspects of its functionality and usage.

Usually the documentation, as well as the program itself, is not written in one pass. Rather it is created in a series of edits and proofreadings. During this process the author often needs to insert annotations which are not intended for the end user, but which, instead, serve as a reminder for the author himself about pending editing tasks. One may, for example, put a note saying that certain paragraph needs to be reworded or that some feature needs to be explained in greater detail and return to that note later in order to fix it. Quite often several authors take part in creating the documentation. In this case such annotations help coordinate their work.

When preparing the document for publishing, it is important to make sure that all such notes has been revised and none of them remain in the document.

Keeping documentation in sync with the software is another challenging task. After adding a new feature the author not always edits the documentation to reflect that. In fact, quite often it is impossible or undesirable, because the feature may imply some further changes to another parts of the program, and the author may prefer to update the docs when all the changes will have been finished. In this case, putting annotations in appropriate places of the document will remind him that certain parts of it have become inaccurate and need to be attended later.

Imprimatur(1) aims to facilitate all these tasks. It is intended for documents written in Texinfo (see Texinfo: (texinfo)Top section `Top' in Texinfo Manual). The package provides a mechanism for editor's annotations and a set of Makefile rules for verifying the consistency of the document.

Footnotes

(1)

Imprimatur’ is Latin for ‘let it be printed’. Historically, this term was used to indicate that there are no obstacles for printing a book.