Debian Codegraph @

doc/imprimatur/README

raw
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: