Short Contents ************** Imprimatur 1 Preface 2 Introduction 3 Renditions 4 Integrating and Using Imprimatur 5 Initialization 6 Texinfo Macros 7 Makefile Rules 8 check-docs.sh 9 Reporting Bugs Appendix A GNU Free Documentation License Concept Index Table of Contents ***************** Imprimatur 1 Preface 2 Introduction 3 Renditions 4 Integrating and Using Imprimatur 4.1 Integration 4.2 How to Use Imprimatur 5 Initialization 6 Texinfo Macros 7 Makefile Rules 8 check-docs.sh 9 Reporting Bugs Appendix A GNU Free Documentation License A.1 ADDENDUM: How to use this License for your documents Concept Index Imprimatur ********** This edition of the `Imprimatur Manual', last updated 19 September 2011, documents `Imprimatur' Version 1.0. 1 Preface ********* `Imprimatur' is a set of Texinfo macros and Makefile rules to verify consistency and, to certain extent, completeness of Texinfo documentation. This package was inspired in part by Franc,ois Pinard's `rendition.texi' file we used in GNU tar's documentation. It was developed between 2005 and 2011 while writing documentation for several other free software projects its author maintains: GNU Mailutils, Dico and Pies, to name a few. It was reorganized into a standalone submodule project in 2011. 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 (*note Texinfo: (texinfo)Top.). 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. 3 Renditions ************ The basic concept used in `Imprimatur' is the document "rendition". The rendition defines how much editor's information and annotations should appear in the resulting document. There are three possible renditions: -- Rendition: PROOF This rendition is used for proofreading the document. It inserts all annotations in a prominent form, which makes it easy to revise the document. -- Rendition: DISTRIB This rendition is intended for the documentation distributed with the packaged versions and its online copies on the Web. It inserts most important annotations, so that the reader is aware about which parts of the document are not fully revised for adequacy. Dangling cross-references are also prominently marked as such (*note Dangling cross-reference::). -- Rendition: PUBLISH This rendition is intended for publishing printed copies of the documentation. It is supposed that by the time the document is ready for publishing, all editor's and proofreader's annotations and dangling references have been resolved and removed from the document. Consequently, the use of annotation macros in this rendition results in translation errors. This helps prevent publishing incomplete or inaccurate documentation. Default rendition is determined when configuring the package. It can be redefined when building the output, by using the `RENDITION' Makefile variable, e.g.: $ make RENDITION=PUBLISH 4 Integrating and Using Imprimatur ********************************** 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. 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) *Note Init::, 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. A. 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 (*note Renditions::). B. 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'). *Note imprimatur_INPUT: Rules, for a discussion of this variable and its purposes. C. 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._ D. 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 *Note 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 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 *note 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' (*note Compilation Mode: (emacs)Compilation Mode.). 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 5 Initialization **************** -- Autoconf Macro: IMPRIMATUR_INIT (DIR, OPTIONS) Initializes `Imprimatur' framework. Both arguments are optional. The DIR argument, if supplied, specifies the directory you cloned `Imprimatur' into. It defaults to `imprimatur', so that if you follow the default setup described in *note Usage:: you don't need to supply this argument. The OPTIONS argument is a whitespace-separated list of options. Following options are recognized: -- Option: PROOF Set the default rendition to `PROOF'. -- Option: DISTRIB Set the default rendition to `DISTRIB'. -- Option: PUBLISH Set the default rendition to `PUBLISH'. If none of these three options is given, `IMPRIMATUR_INIT' will select default rendition based on the version number of the hosting package, i.e. the `VERSION' variable, as set by `AC_INIT' macro. The version number should consist of up to three integers, separated by dots. The first integer is the "major number", the second one is the "minor number", and the third one is the "patchlevel". Given that, the following algorithm is used: 1. If patchlevel is present, then: a. If it is less than 50, `DISTRIB' rendition is selected. b. Otherwise, the package is considered an alpha release and `PROOF' rendition is selected. 2. If patchlevel is not present, `DISTRIB' is used. -- Option: frenchspacing Assume French sentence spacing. *Note frenchspacing: (texinfo)frenchspacing, for a description of the two possible sentence spacings. By default, American sentence spacing is assumed. This option affects the `imprimatur-check-sentence-spacing' Makefile rule, which verifies whether sentence spacing is used consistently throughout the document. *Note imprimatur-check-sentence-spacing::. -- Option: makedoc Enables creation of a separate makefile for building `Imprimatur' documentation. This file is called `Makedoc' and contains rules for building this manual in various output formats. With this option on, the `Makefile' in the `imprimatur' subdirectory will also contain several additional shortcut rules, namely: `make info' `make imprimatur.info' Creates the manual in info format (a shortcut for `make -f Makedoc imprimatur.info'). `make pdf' Creates a PDF output (a shortcut for `make -f Makedoc pfd'). `make dvi' Creates a DVI output. `make ps' Creates a PostScript output. This is intended mostly for `Imprimatur' maintainers, but you may use this option to build your own, perhaps customized, copies of this manual. -- Option: dist-info Distribute the `imprimatur.info' file. This option is valid only in conjunction with `makedoc'. The `IMPRIMATUR_INIT' macro defines several substitution variables, which you can use in your `Makefile.am' files. -- Substitution Variable: IMPRIMATUR_MODULE_DIR The name of the directory `Imprimatur' was cloned into. This name is relative to the top source directory. It helps address files from the `Imprimatur' subdirectory. For example: CHECK_DOCS=$(top_srcdir)/@IMPRIMATUR_MODULE_DIR@/check-docs.sh -- Substitution Variable: IMPRIMATUR_MAKEINFOFLAGS Additional options for `makeinfo' and compatible tools, which inform them about location of `Imprimatur' Texinfo files. You need to add this variable to your `AM_MAKEINFOFLAGS' variable: AM_MAKEINFOFLAGS = @IMPRIMATUR_MAKEINFOFLAGS@ -- Substitution Variable: RENDITION Default rendition. You may need this variable to inform various tools about the selected rendition level, e.g.: TEXI2DVI=texi2dvi -t '@set $(RENDITION)' Note, that `IMPRIMATUR_MAKEINFOFLAGS' includes the option `-D $(RENDITION)', so you don't need to define it explicitly if the tool in question uses this variable. 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 (*note imprimatur-fixmes: Rules.). 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. 7 Makefile Rules **************** The file `imprimatur.mk' contains Makefile rules for verifying the Texinfo documents. It should be included into `Makefile.am' located in the directory where Texinfo sources reside. For example, if your documentation subdirectory is located at the same nesting level as the directory you cloned `imprimatur' into, then add the following statement: include ../imprimatur/imprimatur.mk Note that Automake is supposed to expand this statement, i.e. to replace it with the actual contents of `imprimatur.mk' in the resulting `Makefile.in'. This is possible only if the argument to `include' is a literal string. Do not use Automake substitutions nor Makefile variables in the argument to include. The rules defined in `imprimatur.mk' operate on Texinfo documents listed in the variable `imprimatur_INPUT' -- Makefile Variable: imprimatur_INPUT Whitespace-delimited list of Texinfo source files to process. It is often convenient to specify source files via the `NAME_TEXINFOS' Automake variables. For example, if your main source has the name `myproj.texi' it would normally be added to the Makefile variable `info_TEXINFOS' and the variable `myproj_TEXINFOS' would contain subordinate Texinfo sources it depends on. Then, you would declare `imprimatur_INPUT' as follows: imprimatur_INPUT=$(info_TEXINFOS) $(myproj_TEXINFOS) Once this variable is defined, you can use the following rules: -- Makefile Rule: imprimatur-format Checks whether the files contain tabs (ASCII 9). If so the following diagnostics is displayed: Sources contain tabs; run make imprimatur-untabify *Note imprimatur-untabify::. -- Makefile Rule: imprimatur-refs Checks if the sources contain unresolved cross-references, i.e. any of the macros `FIXME-ref', `FIXME-xref' or `FIXME-pxref' (*note FIXME-ref: Macros.). If so, the prominent diagnostics is displayed and the rule exits with code 2. For example: Unresolved cross-references: mailfromd.texi:3535: existing categories mailfromd.texi:4951: optimizer mailfromd.texi:9899: debug configuration functions.texi:1273: filter chains -- Makefile Rule: imprimatur-fixmes Checks whether the sources contain `@FIXME' macros (*note FIXME: Macros.). If so, list the location of each `@FIXME' along with its content. If the content has several lines, only first of them is displayed. For example: Unresolved FIXMEs: functions.texi:1518: Check references to 'Polling functions' functions.texi:1562: Give more details and references. functions.texi:2231: How to obtain negative -- Makefile Rule: imprimatur-writemes Checks whether the sources contain empty nodes, i.e. nodes marked with the `@WRITEME' macro (*note WRITEME: Macros.). If so, it displays locations of each `@WRITEME', e.g.: Empty nodes: calloutd.texi:6:@WRITEME mfdbtool.texi:148:@WRITEME -- Makefile Rule: imprimatur-empty-nodes An improved version of `imprimatur-writemes'. This rule reports nodes which do not have any text and those marked with the `@WRITEME' macro. Unlike the rest of rules, `imprimatur-empty-nodes' analyzes files in `$(info_TEXINFOS)'. It reads each file and parses it, honoring any `@include' statements. This rule outputs to standard error the names and locations of empty nodes. For nodes marked with the `@WRITEME' macro, location refers to the place where the macro was encountered and the actual node name is prefixed with `(@WRITEME)', as shown in the example below: Empty nodes: ./calloutd.texi:6: calloutd ./mfdbtool.texi:148: Configuring mfdbtool ./upgrade.texi:31: (@WRITEME) Upgrading from 7.0 to 8.0 If you wish to excerpt any of the input files from being verified by this rule, you can do so by adding the following "pragmatic comment" at the beginning of such files: @c imprimatur-ignore -- Makefile Rule: imprimatur-unrevised Checks whether the sources contain nodes which need revision, i.e. the ones marked with the `@UNREVISED' macro (*note UNREVISED: Macros.). If so, display locations of each `@UNREVISED', e.g.: Unrevised nodes: mailfromd.texi:2567:@UNREVISED mailfromd.texi:2694:@UNREVISED -- Makefile Rule: imprimatur-check-sentence-spacing Checks if sentence spacing is correct throughout the sources. By default, American sentence spacing is assumed. French sentence spacing is used if `IMPRIMATUR_INIT' was called with the `frenchspacing' option (*note frenchspacing: Init.). If the sentence spacing is wrong, this rule displays the following diagnostics: Sources contain single-space sentence separators. Run make imprimatur-fix-sentence-spacing to fix. If French spacing is declared, the diagnostics will read: Sources contain double-space sentence separators. Run make imprimatur-fix-sentence-spacing to fix. -- Makefile Rule: imprimatur-fix-sentence-spacing Fixes sentence spacing. The action of this rule depends on the setting of `frenchspacing' option (*note frenchspacing: Init.). -- Makefile Rule: imprimatur-basic-checks Runs the following rules in that order: imprimatur-format imprimatur-check-sentence-spacing imprimatur-refs imprimatur-fixmes imprimatur-empty-nodes imprimatur-unrevised -- Makefile Rule: imprimatur-master-menu Creates a master menu for each Texinfo file in `${info_TEXINFOS}', taking into account included files. This rule uses `Emcas' to create a master menu that follows the top node. The master menu includes every entry from all the other menus. It replaces any existing ordinary menu that follows the top node. The effect of this rule differs from that of `texinfo-master-menu' (*note texinfo-master-menu: (texinfo)Updating Commands.) in that it takes into account included Texinfo files. -- Makefile Rule: imprimatur-untabify Converts all tabs in Texinfo files to multiple spaces, preserving columns. This rule uses `emacs' to do the job. -- Makefile Rule: imprimatur-final Runs `imprimatur-untabify' and `imprimatur-master-menu'. 8 check-docs.sh *************** The shell script `check-docs.sh' provides a mechanism for verifying if all items declared in a program are documented in its Texinfo docs. By "items" we mean here any external entities visible by the end user and designed for his use, such as command line options, configuration statements, external functions and the like. Any such item is supposed to have the following properties: "class" A descriptive name for the group of items this one belongs to. It is intended to be human readable and can consist of arbitrary number of characters. E.g. `Command line option' or `External function', or the like. The script prints class name at the beginning of its output. "identifier" A string of characters uniquely identifying this item among other items of the same class. E.g., a function name if the item is a function, or option name (without the leading dashes) if the item is a command line option. "declaration" A statement in the source code where this item is declared. E.g. a function declaration or option definition. The declaration must contain item identifier so that it can be extracted from it using a regular expression. "description" A statement in the Texinfo document which contains a description of this item. It must meet the same requirement as the declaration, i.e. it should be possible to define a regular expression for extracting the item identifier from the description. The script is invoked as follows: check-docs.sh CODE-SED DOC-SED SOURCES -- MAKEINFO-ARGS Notice mandatory double-dash. Its arguments are: CLASS Item class. Make sure you quote it, if it contains characters special for the shell. CODE-SED A regular expression to extract item identifiers from declarations. It must use a parenthesized group to mark the identifier (*note REPLACEMENT: (sed)The "s" Command.), and the `p' flag or command to output it (*note Print out the pattern space: (sed)Common Commands.). For example, the following expression extracts function name from its declaration in C code: s/^\([_a-zA-Z][_a-zA-Z0-9]*\) *(.*/\1/p It assumes that identifiers start in column 0 and is simplified a bit. DOC-SED A regular expression to extract item identifiers from descriptions. It is in all respects similar to CODE-SED. For example, the expression below extracts identifiers from `@defmac' statements: '/@defmac/s/@defmac *\([-a-zA-Z][-a-zA-Z0-9]*\).*/\1/p' SOURCES A list of source files to apply CODE-SED to. MAKEINFO-ARGS A command which produces preprocessed Texinfo source at its output. Normally, it is `makeinfo -E -' with some additional arguments. The DOC-SED expression is applied to its output. The `check-docs.sh' script collects identifiers produced by the two sed expressions and computes two sets of differences: identifiers missing from the docs, but present in the sources and the ones missing from the sources but present in the docs. If both lists are empty, the script exits silently with status `0'. Otherwise, it reports the differences and exits with status `1'. The script is normally used from Makefile rules in the `Makefile.am' file located in the documentation directory. You may have any number of such rules, each one for a particular class of items. It is recommended to declare a Makeinfo variable pointing to the script, such as: CHECK_DOCS = $(top_srcdir)/@IMPRIMATUR_MODULE_DIR@/check-docs.sh The MAKEINFO-ARGS parameter is usually as follows: $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -E - $(info_TEXINFOS) To illustrate this, here is a Makefile rule used by `Imprimatur' itself to verify that all rules from `imprimatur.mk' are documented: check-rules: @$(CHECK_DOCS) "Makefile rules" \ '/^imprimatur-.*:/s/:.*//p' \ 's/@deffn {Makefile Rule} *//p' \ imprimatur.mk -- \ $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) \ -I $(srcdir) -E - $(info_TEXINFOS) To illustrate its output, suppose that the rule `imprimatur-fixmes' is not documented. Then, you will get: $ make -k check-rules Not documented Makefile rules: imprimatur-fixmes Similarly, if the docs document rule `imprimatur-fixme' (presumably a typo: the `s' is missing), you'll get: $ make -k check-rules Non-existing Makefile rules: imprimatur-fixme In both cases, the exit code will indicate an error. 9 Reporting Bugs **************** Send bug reports and suggestions to . If you think you've found a bug, please be sure to include maximum information available to reliably reproduce, or at least to analyze it. Please, include the version of the package you are using and a description of the bug: what you did, what result did you get and how it differs from what you expected. If possible, include a short test case with the steps needed to reproduce the bug. Any errors, typos or omissions found in this manual also qualify as bugs. Please report them, if you happen to find any. Appendix A GNU Free Documentation License ***************************************** Version 1.2, November 2002 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition. The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H. Include an unaltered copy of this License. I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version. N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section. O. Preserve any Warranty Disclaimers. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements." 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See `http://www.gnu.org/copyleft/'. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. A.1 ADDENDUM: How to use this License for your documents ======================================================== To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: Copyright (C) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with...Texts." line with this: with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software. Concept Index ************* This is a general index of all issues discussed in this manual: AC_INIT: See 5. (line 354) ACLOCAL_AMFLAGS: See 4.1. (line 171) AM_MAKEINFOFLAGS <1>: See 5. (line 423) AM_MAKEINFOFLAGS: See 4.1. (line 199) annotation: See 2. (line 61) check-docs.sh <1>: See 8. (line 702) check-docs.sh: See 4.1. (line 227) configure.ac: See 4.1. (line 181) default rendition: See 5. (line 345) dist-info: See 5. (line 410) DISTRIB <1>: See 5. (line 349) DISTRIB: See 3. (line 117) doc/Makefile.am: See 4.1. (line 196) FDL, GNU Free Documentation License: See Appendix A. (line 843) FIXME: See 6. (line 478) FIXME-pxref: See 6. (line 514) FIXME-ref: See 6. (line 506) FIXME-xref: See 6. (line 510) Franc,ois Pinard: See 1. (line 47) frenchspacing: See 5. (line 372) git: See 4.1. (line 155) imprimatur: See 2. (line 92) imprimatur-basic-checks: See 7. (line 670) imprimatur-check-sentence-spacing: See 7. (line 649) imprimatur-empty-nodes: See 7. (line 614) imprimatur-final: See 7. (line 697) imprimatur-fix-sentence-spacing: See 7. (line 666) imprimatur-fixmes: See 7. (line 594) imprimatur-format: See 7. (line 574) imprimatur-ignore: See 7. (line 633) imprimatur-master-menu: See 7. (line 680) imprimatur-refs: See 7. (line 582) imprimatur-unrevised: See 7. (line 640) imprimatur-untabify: See 7. (line 693) imprimatur-writemes: See 7. (line 605) imprimatur.mk <1>: See 7. (line 542) imprimatur.mk: See 4.1. (line 217) IMPRIMATUR_INIT: See 5. (line 336) imprimatur_INPUT <1>: See 7. (line 561) imprimatur_INPUT: See 4.1. (line 205) IMPRIMATUR_MAKEINFOFLAGS <1>: See 5. (line 424) IMPRIMATUR_MAKEINFOFLAGS: See 4.1. (line 199) IMPRIMATUR_MODULE_DIR: See 5. (line 417) info_TEXINFOS: See 7. (line 561) Makedoc: See 5. (line 383) makedoc: See 5. (line 383) Makefile: See 7. (line 542) Makefile.am, top level: See 4.1. (line 171) PROOF <1>: See 5. (line 346) PROOF: See 3. (line 112) PUBLISH <1>: See 5. (line 352) PUBLISH: See 3. (line 125) RENDITION <1>: See 5. (line 431) RENDITION: See 3. (line 133) rendition, default: See 5. (line 345) rendition, defined: See 3. (line 106) rendition.texi <1>: See 6. (line 443) rendition.texi: See 4.2. (line 244) rules, Makefile: See 7. (line 542) SUBDIRS: See 4.1. (line 171) submodule: See 4.1. (line 155) Texinfo: See 2. (line 92) UNREVISED: See 6. (line 462) VERSION: See 5. (line 354) WRITEME: See 6. (line 448)