| 1 |
Imprimatur README |
| 2 |
Copyright (C) 2011 Sergey Poznyakoff |
| 3 |
See the end of file for copying conditions. |
| 4 |
|
| 5 |
* Introduction |
| 6 |
|
| 7 |
This file contains brief information about installing and configuring |
| 8 |
Imprimatur. It is *not* intended as a replacement for the |
| 9 |
documentation, and is provided as a brief reference only. |
| 10 |
The complete documentation in Texinfo format is included. To build |
| 11 |
it, change to the imprimatur subdirectory and run `makeinfo |
| 12 |
imprimatur'. |
| 13 |
|
| 14 |
Complete documentation in various formats is available online from the |
| 15 |
following URL: |
| 16 |
|
| 17 |
http://www.gnu.org.ua/software/imprimatur/manual |
| 18 |
|
| 19 |
* Overview |
| 20 |
|
| 21 |
Imprimatur provides Texinfo macros for various editing tasks such as |
| 22 |
adding editor notes and annotations, as well as makeinfo rules for |
| 23 |
verifying texinfo document structure, format, and (to a certain |
| 24 |
extent) content coverage. |
| 25 |
|
| 26 |
In particular, it provides a mechanism for verifying whether the |
| 27 |
entities, such as command line options, configuration file statements, |
| 28 |
library functions, and the like, which are defined in a set of source |
| 29 |
files are also described in the Texinfo document. |
| 30 |
|
| 31 |
* Installation |
| 32 |
|
| 33 |
To use Imprimatur in your project, follow these steps: |
| 34 |
|
| 35 |
** Import the package as a submodule |
| 36 |
|
| 37 |
This needs to be done only once: |
| 38 |
|
| 39 |
git submodule add git://git.gnu.org.ua/imprimatur.git imprimatur |
| 40 |
git submodule init |
| 41 |
|
| 42 |
The `submodule add' command takes two arguments: the submodule |
| 43 |
repository, which should be exactly as shown above, and the pathname |
| 44 |
of the cloned submodule in your project. This latter is entirely at |
| 45 |
your option. Throughout this document we will suppose that the module |
| 46 |
pathname is `imprimatur'. You will need to adjust the examples if you chose |
| 47 |
another name for it. |
| 48 |
|
| 49 |
** Edit the toplevel Makefile.am |
| 50 |
|
| 51 |
Add `-I imprimatur' to the ACLOCAL_AMFLAGS variable, and `imprimatur' |
| 52 |
to the SUBDIRS variable. For example: |
| 53 |
|
| 54 |
ACLOCAL_AMFLAGS = -I m4 -I imprimatur |
| 55 |
SUBDIRS = imprimatur |
| 56 |
|
| 57 |
** Edit the configure.ac file |
| 58 |
|
| 59 |
Add a call to IMPRIMATUR_INIT. Normally no parameters are needed. |
| 60 |
However, if you cloned Imprimatur into a directory with another name, |
| 61 |
the actual directory name must be supplied as the first argument. For |
| 62 |
example, if you used this submodule command |
| 63 |
|
| 64 |
git submodule add git://git.gnu.org.ua/imprimatur.git somedir |
| 65 |
|
| 66 |
then use |
| 67 |
|
| 68 |
IMPRIMATUR_INIT(somedir) |
| 69 |
|
| 70 |
in your configure.ac |
| 71 |
|
| 72 |
** Edit Makefile.am in your doc subdirectory |
| 73 |
|
| 74 |
Apply the following changes to the Makefile.am located in the |
| 75 |
subdirectory where you have your Texinfo sources: |
| 76 |
|
| 77 |
1. To AM_MAKEINFOFLAGS add @IMPRIMATUR_MAKEINFOFLAGS@ |
| 78 |
2. Define the variable `imprimatur_INPUT'. It must contain the |
| 79 |
names of Texinfo sources to be verified by Imprimatur. Normally, |
| 80 |
the following definition is sufficient: |
| 81 |
|
| 82 |
imprimatur_INPUT=$(info_TEXINFOS) $(<BASE>_TEXINFOS) |
| 83 |
|
| 84 |
where <BASE> stands for the base name of your Texinfo document (e.g. |
| 85 |
"foo", if it is named "foo.texi"). |
| 86 |
3. Include imprimatur.mk using relative addressing. For example, if |
| 87 |
your documentation subdirectory is located at the same nesting level |
| 88 |
as the directory you cloned Imprimatur to, use: |
| 89 |
|
| 90 |
include ../imprimatur/imprimatur.mk |
| 91 |
|
| 92 |
Do not use Automake substitutions nor Makefile variables in the |
| 93 |
argument to include. |
| 94 |
4. If you plan to use the `check-docs.sh' script, define the following |
| 95 |
variable: |
| 96 |
|
| 97 |
CHECK_DOCS=$(top_srcdir)/@IMPRIMATUR_MODULE_DIR@/check-docs.sh |
| 98 |
|
| 99 |
For example: |
| 100 |
|
| 101 |
AM_MAKEINFOFLAGS = @IMPRIMATUR_MAKEINFOFLAGS@ |
| 102 |
imprimatur_INPUT=$(info_TEXINFOS) $(foo_TEXINFOS) |
| 103 |
include ../imprimatur/imprimatur.mk |
| 104 |
CHECK_DOCS=$(top_srcdir)/@IMPRIMATUR_MODULE_DIR@/check-docs.sh |
| 105 |
|
| 106 |
** Include `rendition.texi' into your main Texinfo source. |
| 107 |
|
| 108 |
* Bug reporting. |
| 109 |
|
| 110 |
Send bug reports to <[email protected]>. |
| 111 |
|
| 112 |
^L |
| 113 |
* Copyright information: |
| 114 |
|
| 115 |
Copyright (C) 2011 Sergey Poznyakoff |
| 116 |
|
| 117 |
Permission is granted to anyone to make or distribute verbatim copies |
| 118 |
of this document as received, in any medium, provided that the |
| 119 |
copyright notice and this permission notice are preserved, |
| 120 |
thus giving the recipient permission to redistribute in turn. |
| 121 |
|
| 122 |
Permission is granted to distribute modified versions |
| 123 |
of this document, or of portions of it, |
| 124 |
under the above conditions, provided also that they |
| 125 |
carry prominent notices stating who last changed them. |
| 126 |
|
| 127 |
|
| 128 |
Local Variables: |
| 129 |
mode: outline |
| 130 |
paragraph-separate: "[ ]*$" |
| 131 |
version-control: never |
| 132 |
End: |