1<?xml version='1.0' encoding='ISO-8859-1'?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4
5<!--
6
7Process this file with an XSLT processor: `xsltproc \
8-''-nonet /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
9manpages/docbook.xsl manpage.dbk'.  A manual page
10<package>.<section> will be generated.  You may view the
11manual page with: nroff -man <package>.<section> | less'.  A
12typical entry in a Makefile or Makefile.am is:
13
14DB2MAN=/usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
15manpages/docbook.xsl
16XP=xsltproc -''-nonet
17
18manpage.1: manpage.dbk
19        $(XP) $(DB2MAN) $<
20
21The xsltproc binary is found in the xsltproc package.  The
22XSL files are in docbook-xsl.  Please remember that if you
23create the nroff version in one of the debian/rules file
24targets (such as build), you will need to include xsltproc
25and docbook-xsl in your Build-Depends control field.
26
27-->
28
29  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
30  <!ENTITY dhfirstname "<firstname>martin f.</firstname>">
31  <!ENTITY dhsurname   "<surname>krafft</surname>">
32  <!ENTITY dhmaintfirstname "<firstname>Julian</firstname>">
33  <!ENTITY dhmaintsurname   "<surname>Gilbey</surname>">
34  <!-- Please adjust the date whenever revising the manpage. -->
35  <!ENTITY dhdate      "<date>Feb 13, 2006</date>">
36  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
37       allowed: see man(7), man(1). -->
38  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
39  <!ENTITY dhemail     "<email>madduck@debian.org</email>">
40  <!ENTITY dhmaintemail "<email>jdg@debian.org</email>">
41  <!ENTITY dhusername  "martin f. krafft">
42  <!ENTITY dhmaintusername  "Julian Gilbey">
43  <!ENTITY dhucpackage "<refentrytitle>deb-reversion</refentrytitle>">
44  <!ENTITY dhpackage   "deb-reversion">
45  <!ENTITY dhcommand   "deb-reversion">
46
47  <!ENTITY debian      "<productname>Debian</productname>">
48  <!ENTITY gnu         "<acronym>GNU</acronym>">
49  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
50]>
51
52<refentry>
53  <refentryinfo>
54    <address>
55      &dhemail;
56    </address>
57    &dhdate;
58  </refentryinfo>
59  <refmeta>
60    &dhucpackage;
61
62    &dhsection;
63  </refmeta>
64  <refnamediv>
65    <refname>&dhcommand;</refname>
66
67    <refpurpose>simple script to change the version of a .deb file</refpurpose>
68  </refnamediv>
69
70  <refsynopsisdiv>
71    <cmdsynopsis>
72      <command>&dhcommand;</command>
73      <arg choice="opt">
74        <replaceable>options</replaceable>
75      </arg>
76      <replaceable> .deb-file</replaceable>
77      <arg choice="opt" rep="repeat"><replaceable>log message</replaceable></arg>
78    </cmdsynopsis>
79  </refsynopsisdiv>
80
81  <refsect1>
82    <title>DESCRIPTION</title>
83
84    <para>
85      <command>&dhcommand;</command> unpacks the specified <filename>.deb</filename> file, changes the version
86      number in the relevant locations, appends a Debian
87      <filename>changelog</filename> entry with the specified
88      contents, and creates a new <filename>.deb</filename> file with the updated version.
89    </para>
90
91    <para>
92      By default, the tool creates a new version number suitable for
93      local changes, such that the new package will be greater than
94      the current one, but lesser than any future, official Debian
95      packages.  With <option>-v <replaceable
96      class="parameter">version</replaceable></option>, the version
97      number can be specified directly.  On the other hand, the
98      <option>-c</option> simply calculates the new version number but
99      does not generate a new package.
100    </para>
101
102    <para>
103      When building a <filename>.deb</filename> file, root privileges are required in order
104      to have the correct permissions and ownerships in the resulting
105      <filename>.deb</filename> file.  This can be achieved either by running
106      <command>&dhcommand;</command> as root or running under
107      <citerefentry><refentrytitle>fakeroot</refentrytitle>
108        <manvolnum>1</manvolnum></citerefentry>, as 'fakeroot
109      &dhcommand; foo.deb'.
110    </para>
111
112    <para>
113      With <option>-k <replaceable
114      class="parameter">hook</replaceable></option>, a hook script may
115      be specified, which is run on the unpacked binary packages just
116      before it is repacked. If you want to write changelog entries
117      from within the hook, use '<command>dch -a -- <replaceable
118      class="parameter">your message</replaceable></command>'.
119      (Alternatively, do not give a changelog entry on the
120      <command>&dhcommand;</command> command line and
121      <command>dch</command> will be called automatically.)  The hook
122      command must be placed in quotes if it has more than one word;
123      it is called via <command>sh -c</command>.
124    </para>
125  </refsect1>
126
127  <refsect1>
128    <title>OPTIONS</title>
129    <variablelist>
130      <varlistentry>
131        <term><option>-v</option> <replaceable class="parameter">new-version</replaceable></term>
132        <term><option>--new-version</option> <replaceable class="parameter">new-version</replaceable></term>
133        <listitem>
134          <para>
135            Specifies the version number to be used for the new
136            version.  Passed to <citerefentry>
137              <refentrytitle>dch</refentrytitle>
138              <manvolnum>1</manvolnum>
139            </citerefentry>.
140          </para>
141        </listitem>
142      </varlistentry>
143
144      <varlistentry>
145        <term><option>-o</option> <replaceable class="parameter">old-version</replaceable></term>
146        <term><option>--old-version</option> <replaceable class="parameter">old-version</replaceable></term>
147        <listitem>
148          <para>
149            Specifies the version number to be used as the old
150            version instead of the version stored in the <filename>.deb</filename>'s
151            <filename>control</filename> file.
152          </para>
153        </listitem>
154      </varlistentry>
155
156      <varlistentry>
157        <term><option>-c</option></term>
158        <term><option>--calculate-only</option></term>
159        <listitem>
160          <para>
161            Only calculate and display the new version number which
162            would be used; do not build a new <filename>.deb</filename> file.  Cannot be
163            used in conjunction with <option>-v</option>.
164          </para>
165        </listitem>
166      </varlistentry>
167
168      <varlistentry>
169        <term><option>-s</option> <replaceable class="parameter">string</replaceable></term>
170        <term><option>--string</option> <replaceable class="parameter">string</replaceable></term>
171        <listitem>
172          <para>
173            Instead of using 'LOCAL.' as the version string to append
174            to the old version number, use <replaceable
175            class="parameter">string</replaceable> instead.
176          </para>
177        </listitem>
178      </varlistentry>
179
180      <varlistentry>
181        <term><option>-k</option> <replaceable class="parameter">hook-command</replaceable></term>
182        <term><option>--hook</option> <replaceable class="parameter">hook-command</replaceable></term>
183        <listitem>
184          <para>
185            A hook command to run after unpacking the old <filename>.deb</filename> file and
186            modifying the <filename>changelog</filename>, and before packing up the new <filename>.deb</filename>
187            file.  Must be in quotes if it is more than one (shell)
188            word.  Only one hook command may be specified; if you want
189            to perform more than this, you could specify 'bash' as the
190            hook command, and you will then be given a shell to work
191            in.
192          </para>
193        </listitem>
194      </varlistentry>
195
196      <varlistentry>
197        <term><option>-D</option></term>
198        <term><option>--debug</option></term>
199        <listitem>
200          <para>
201            Pass <option>--debug</option> to
202            <citerefentry>
203              <refentrytitle>dpkg-deb</refentrytitle>
204              <manvolnum>1</manvolnum>
205            </citerefentry>.
206          </para>
207        </listitem>
208      </varlistentry>
209
210      <varlistentry>
211        <term><option>-b</option></term>
212        <term><option>--force-bad-version</option></term>
213        <listitem>
214          <para>
215            Pass <option>--force-bad-version</option> to
216            <citerefentry>
217              <refentrytitle>dch</refentrytitle>
218              <manvolnum>1</manvolnum>
219            </citerefentry>
220          </para>
221        </listitem>
222      </varlistentry>
223
224      <varlistentry>
225        <term><option>-h</option></term>
226        <term><option>--help</option></term>
227        <listitem>
228          <para>
229            Display usage information.
230          </para>
231        </listitem>
232      </varlistentry>
233
234      <varlistentry>
235        <term><option>-V</option></term>
236        <term><option>--version</option></term>
237        <listitem>
238          <para>
239            Display version information.
240          </para>
241        </listitem>
242      </varlistentry>
243    </variablelist>
244  </refsect1>
245
246  <refsect1>
247    <title>SEE ALSO</title>
248    <para>
249      <citerefentry>
250        <refentrytitle>dch</refentrytitle>
251        <manvolnum>1</manvolnum>
252      </citerefentry>,
253      <citerefentry>
254        <refentrytitle>dpkg-deb</refentrytitle>
255        <manvolnum>1</manvolnum>
256      </citerefentry>,
257      <citerefentry>
258        <refentrytitle>fakeroot</refentrytitle>
259        <manvolnum>1</manvolnum>
260      </citerefentry>
261    </para>
262  </refsect1>
263
264  <refsect1>
265    <title>DISCLAIMER</title>
266    <para>
267      &dhpackage; is a tool intended to help porters with
268      modifying packages for other architectures, and to augment deb-repack,
269      which creates modified packages with identical version numbers as the
270      official packages. Chaos will ensue! With &dhpackage;, a proper version
271      number can be selected, which does not obstruct the next official
272      release but can be specifically pinned with APT or held with dpkg.
273    </para>
274
275    <para>
276      Please take note that &dhpackage; does not come without problems. While
277      it works fine in most cases, it may just not in yours. Especially,
278      please consider that it changes binary packages (only!) and hence can
279      break strict versioned dependencies between binary packages generated
280      from the same source. </para>
281
282    <para>
283      You are using this tool at your own risk and I shall not shed a tear if
284      your gerbil goes up in flames, your microwave attacks the stereo, or the
285      angry slamming of your fist spills your coffee into the keyboard, which
286      sets off a chain reaction resulting in a vast amount of money transferred
287      from your account to mine.
288    </para>
289  </refsect1>
290
291  <refsect1>
292    <title>AUTHOR</title>
293
294    <para>
295      &dhpackage; is Copyright 2004-5 by &dhusername; &dhemail; and
296      modifications are Copyright 2006 by &dhmaintusername; &dhmaintemail;.
297    </para>
298
299    <para>
300      Permission is granted to copy, distribute and/or modify this document
301      under the terms of the Artistic License:
302      <ulink>http://www.opensource.org/licenses/artistic-license.php</ulink>.
303      On Debian systems, the complete text of the Artistic License can be
304      found
305      in <filename>/usr/share/common-licenses/Artistic</filename>.
306    </para>
307
308    <para>
309      This manual page was written by &dhusername; &dhemail; and
310      modified by &dhmaintusername; &dhmaintemail;.
311    </para>
312
313  </refsect1>
314</refentry>
315
316<!--
317  Local Variables:
318  mode: xml
319  End:
320-->
321