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