1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
|
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"/usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd" [
<!ENTITY debian "Debian GNU/Linux">
<!ENTITY dhprg "<command>headache</command>">
]>
<!--**********************************************************************-->
<!-- Headache manpage -->
<!-- -->
<!-- Copyright (C) 2003-2006 Sylvain Le Gall <gildor@debian.org> -->
<!-- -->
<!-- This library is free software; you can redistribute it and/or -->
<!-- modify it under the terms of the GNU Lesser General Public -->
<!-- License as published by the Free Software Foundation; either -->
<!-- version 2.1 of the License, or (at your option) any later version; -->
<!-- with the OCaml static compilation exception. -->
<!-- -->
<!-- This library is distributed in the hope that it will be useful, -->
<!-- but WITHOUT ANY WARRANTY; without even the implied warranty of -->
<!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -->
<!-- Lesser General Public License for more details. -->
<!-- -->
<!-- You should have received a copy of the GNU Lesser General Public -->
<!-- License along with this library; if not, write to the Free Software -->
<!-- Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, -->
<!-- MA 02110-1301, USA. -->
<!-- -->
<!-- Contact: gildor@debian.org -->
<!--**********************************************************************-->
<refentry>
<refentryinfo>
<author>
<firstname>Sylvain</firstname>
<surname>Le Gall</surname>
<email>gildor@debian.org</email>
</author>
<copyright>
<year>2003, 2004, 2005, 2006</year>
<holder>Sylvain Le Gall</holder>
</copyright>
<date>Feb 15, 2004</date>
</refentryinfo>
<refmeta>
<refentrytitle>HEADACHE</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>&dhprg;</refname>
<refpurpose>A program to manage the license of your source
file.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
&dhprg;
<arg>-h
<replaceable>file</replaceable>
</arg>
<arg>-c
<replaceable>file</replaceable>
</arg>
<arg>-r</arg>
<group>
<arg choice="plain">-help</arg>
<arg choice="plain">--help</arg>
</group>
<arg choice="plain" rep="repeat">
<replaceable>file</replaceable>
</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>This manual page documents briefly the &dhprg; command.</para>
<para>This manual page was written for the &debian; distribution
because the original program does not have a manual page.</para>
<para>It is a common usage to put at the beginning of source code files a
short header giving, for instance, some copyright information. &dhprg;
is a simple and lightweight tool for managing easily these headers.
Among its functionalities, one may mention:
<itemizedlist>
<listitem>
<para>Headers must generally be generated as comments in source code
files. &dhprg; deals with different files types and generates for
each of them headers in an appropriate format.</para>
</listitem>
<listitem>
<para>Headers automatically detects existing headers and removes them.
Thus, you can use it to update headers in a set of files.</para>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1>
<title>COMMAND LINE OPTIONS</title>
<variablelist>
<varlistentry>
<term><filename>file</filename></term>
<listitem>
<para>Name of one file to process</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-h <filename>file</filename></term>
<listitem>
<para>Create a header with text coming from
<filename>file</filename></para>
</listitem>
</varlistentry>
<varlistentry>
<term>-c <filename>file</filename></term>
<listitem>
<para>Read the given configuration
<filename>file</filename></para>
</listitem>
</varlistentry>
<varlistentry>
<term>-help</term>
<term>--help</term>
<listitem>
<para>Display the option list of &dhprg;</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>USAGE</title>
<para>Let us illustrate the use of this tool with a small example. Assume
you have a small project mixing C and Caml code consisting in three
files 'foo.c', 'bar.ml' and 'bar.mli'', and you want to equip them with
some header. First of all, write a header file, i.e. a plain text file
including the information headers must mention. An example of such a
file is given in figure 1. In the following, we assume this file is
named 'myheader' and is in the same directory as source files.</para>
<para>Then, in order to generate headers, just run the command :
<command>&dhprg; -h <filename>myheader</filename>
<filename>foo.c</filename>
<filename>bar.ml</filename>
<filename>bar.mli</filename>
</command>
</para>
<para>Each file is equipped with an header including the text given in the
header file 'myheader', surrounded by some extra characters depending on
its format making it a comment (e.g. '(*' and '*)' in '.ml' files). If
you update the header file 'myheader', you simply need to re-run the above
command to update headers in source code files.</para>
<para>Similarly, running :
<command>&dhprg; -r
<filename>foo.c</filename>
<filename>bar.ml</filename>
<filename>bar.mli</filename>
</command>
removes any existing in files 'foo.c', 'bar.ml' and 'bar.mli'. Files
which do not have a header are kept unchanged.</para>
</refsect1>
<refsect1>
<title>CONFIGURATION FILE</title>
<para>File types and format of header may be specified by a configuration
file. By default, the default builtin configuration file given in figure
2 is used. You can also use your own configuration file thanks to the
<option>-c</option> option :
<command>&dhprg;
-c <filename>myconfig</filename>
-h <filename>myheader</filename>
<filename>foo.c</filename>
<filename>bar.ml</filename>
<filename>bar.mli</filename>
</command></para>
<para>In order to write your own configuration, you can follow the example
given in figure 2. A configuration file consists in a list of entries
separated by the character '|'. Each of them is made of two parts
separated by an '->'.</para>
<para>The first one is a regular expression. (Regular expression are
enclosed within double quotes and have the same syntax as in Gnu
Emacs.) &dhprg; determines file types according to file basenames;
thus, each file is dealt with using the first line its name matches.
</para>
<para>The second one describes the format of headers for files of this
type. It consists of the name of a model (e.g. 'frame'), possibly
followed by a list of arguments. Arguments are named: 'open:"(*"'
means that the value of the argument 'open' is '(*'.
&dhprg; currently supports three models and a special keyword:</para>
<variablelist>
<varlistentry>
<term>frame</term>
<listitem>
<para>With this model, headers are generated in a frame. This
model requires three arguments: 'open' and 'close' (the opening and
closing sequences for comments) and 'line' (the character used to
make the horizontal lines of the frame). Two optional arguments may
be used 'margin' (a string printed between the left and right side
of the frame and the border, by default two spaces) and 'width' (the
width of the inside of the frame, default is 68).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>lines</term>
<listitem>
<para>Headers are typeset between two lines. Three arguments must
be provided: 'open' and 'close' (the opening and closing sequences
for comments), 'line' (the character used to make the horizontal
lines). Three optional arguments are allowed: 'begin' (a string
typeset at the beginning of each line, by default two spaces),
'last' (a string typeset at the beginning of the last line) and
'width' (the width of the lines, default is 70).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>no</term>
<listitem>
<para>This model generates no header and has no argument.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>skip</term>
<listitem>
<para>Skip line corresponding to one of the "match" parameters
regexp. For this kind of line, every first part pattern that matches
the file basename is taken into account.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><filename>/usr/share/doc/headache/manual.html</filename></para>
</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>This manual page was written by
<personname>
<firstname>Sylvain</firstname>
<surname>Le Gall</surname>
</personname>
<email>gildor@debian.org</email>
Permission is granted to copy, distribute and/or modify this document
under the terms of the <acronym>GNU</acronym> Lesser General Public
License, Version 2.1 or any later version published by the Free Software
Foundation; considering as source code all the file that enable the
production of this manpage.</para>
</refsect1>
</refentry>
|
