scripts/deb-reversion.dbk

   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
   7 Process this file with an XSLT processor: `xsltproc \
   8 -''-nonet /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
   9 manpages/docbook.xsl manpage.dbk'.  A manual page
  10 <package>.<section> will be generated.  You may view the
  11 manual page with: nroff -man <package>.<section> | less'.  A
  12 typical entry in a Makefile or Makefile.am is:
  13
  14 DB2MAN=/usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
  15 manpages/docbook.xsl
  16 XP=xsltproc -''-nonet
  17
  18 manpage.1: manpage.dbk
  19         $(XP) $(DB2MAN) $<
  20
  21 The xsltproc binary is found in the xsltproc package.  The
  22 XSL files are in docbook-xsl.  Please remember that if you
  23 create the nroff version in one of the debian/rules file
  24 targets (such as build), you will need to include xsltproc
  25 and 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">log message</arg>
  78     </cmdsynopsis>
  79   </refsynopsisdiv>
  80
  81   <refsect1>
  82     <title>DESCRIPTION</title>
  83
  84     <para>
  85       &dhcommand; unpacks the specified .deb 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 .deb 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 .deb file, root privileges are required in order
 104       to have the correct permissions and ownerships in the resulting
 105       .deb 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 .deb's
 151             control 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 .deb 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 .deb file and
 186             modifying the changelog, and before packing up the new .deb
 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>fakeroot</refentrytitle>
 255         <manvolnum>1</manvolnum>
 256       </citerefentry>,
 257       <citerefentry>
 258         <refentrytitle>dpkg-deb</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 (e.g. amd64) 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 transfered
 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 -->