<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [

<!--

Process this file with an XSLT processor: `xsltproc \
-''-nonet /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
manpages/docbook.xsl manpage.dbk'.  A manual page
<package>.<section> will be generated.  You may view the
manual page with: nroff -man <package>.<section> | less'.  A
typical entry in a Makefile or Makefile.am is:

DB2MAN=/usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
manpages/docbook.xsl
XP=xsltproc -''-nonet

manpage.1: manpage.dbk
        $(XP) $(DB2MAN) $<
    
The xsltproc binary is found in the xsltproc package.  The
XSL files are in docbook-xsl.  Please remember that if you
create the nroff version in one of the debian/rules file
targets (such as build), you will need to include xsltproc
and docbook-xsl in your Build-Depends control field.

-->

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>martin f.</firstname>">
  <!ENTITY dhsurname   "<surname>krafft</surname>">
  <!ENTITY dhmaintfirstname "<firstname>Julian</firstname>">
  <!ENTITY dhmaintsurname   "<surname>Gilbey</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>Feb 13, 2006</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  <!ENTITY dhemail     "<email>madduck@debian.org</email>">
  <!ENTITY dhmaintemail "<email>jdg@debian.org</email>">
  <!ENTITY dhusername  "martin f. krafft">
  <!ENTITY dhmaintusername  "Julian Gilbey">
  <!ENTITY dhucpackage "<refentrytitle>deb-reversion</refentrytitle>">
  <!ENTITY dhpackage   "deb-reversion">
  <!ENTITY dhcommand   "deb-reversion">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>&dhcommand;</refname>

    <refpurpose>simple script to change the version of a .deb file.</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhcommand;</command>
      <arg choice="opt">
        <replaceable>options</replaceable>
      </arg>
      <replaceable> .deb-file</replaceable>
      <arg choice="opt" rep="repeat">log message</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>

    <para>
      &dhcommand; unpacks the specified .deb file, changes the version
      number in the relevant locations, appends a Debian
      <filename>changelog</filename> entry with the specified
      contents, and creates a new .deb file with the updated version.
    </para>

    <para>
      By default, the tool creates a new version number suitable for
      local changes, such that the new package will be greater than
      the current one, but lesser than any future, official Debian
      packages.  With <option>-v <replaceable
      class="parameter">version</replaceable></option>, the version
      number can be specified directly.  On the other hand, the
      <option>-c</option> simply calculates the new version number but
      does not generate a new package.
    </para>

    <para>
      When building a .deb file, root privileges are required in order
      to have the correct permissions and ownerships in the resulting
      .deb file.  This can be achieved either by running
      <command>&dhcommand;</command> as root or running under
      <citerefentry><refentrytitle>fakeroot</refentrytitle>
	<manvolnum>1</manvolnum></citerefentry>, as 'fakeroot
      &dhcommand; foo.deb'.
    </para>

    <para>
      With <option>-k <replaceable
      class="parameter">hook</replaceable></option>, a hook script may
      be specified, which is run on the unpacked binary packages just
      before it is repacked. If you want to write changelog entries
      from within the hook, use '<command>dch -a -- <replaceable
      class="parameter">your message</replaceable></command>'.
      (Alternatively, do not give a changelog entry on the
      <command>&dhcommand;</command> command line and
      <command>dch</command> will be called automatically.)  The hook
      command must be placed in quotes if it has more than one word;
      it is called via <command>sh -c</command>.
    </para>
  </refsect1>

  <refsect1>
    <title>OPTIONS</title>
    <variablelist>
      <varlistentry>
	<term><option>-v</option> <replaceable class="parameter">new-version</replaceable></term>
	<term><option>--new-version</option> <replaceable class="parameter">new-version</replaceable></term>
	<listitem>
	  <para>
            Specifies the version number to be used for the new
            version.  Passed to <citerefentry>
	      <refentrytitle>dch</refentrytitle>
	      <manvolnum>1</manvolnum>
	    </citerefentry>.
          </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-o</option> <replaceable class="parameter">old-version</replaceable></term>
	<term><option>--old-version</option> <replaceable class="parameter">old-version</replaceable></term>
	<listitem>
	  <para>
            Specifies the version number to be used as the old
            version instead of the version stored in the .deb's
            control file.
          </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-c</option></term>
	<term><option>--calculate-only</option></term>
	<listitem>
	  <para>
            Only calculate and display the new version number which
            would be used; do not build a new .deb file.  Cannot be
            used in conjunction with <option>-v</option>.
          </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-s</option> <replaceable class="parameter">string</replaceable></term>
	<term><option>--string</option> <replaceable class="parameter">string</replaceable></term>
	<listitem>
	  <para>
            Instead of using 'LOCAL.' as the version string to append
            to the old version number, use <replaceable
            class="parameter">string</replaceable> instead.
          </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-k</option> <replaceable class="parameter">hook-command</replaceable></term>
	<term><option>--hook</option> <replaceable class="parameter">hook-command</replaceable></term>
	<listitem>
	  <para>
            A hook command to run after unpacking the old .deb file and
            modifying the changelog, and before packing up the new .deb
            file.  Must be in quotes if it is more than one (shell)
            word.  Only one hook command may be specified; if you want
            to perform more than this, you could specify 'bash' as the
            hook command, and you will then be given a shell to work
            in.
          </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-D</option></term>
	<term><option>--debug</option></term>
	<listitem>
	  <para>
            Pass <option>--debug</option> to
            <citerefentry>
	      <refentrytitle>dpkg-deb</refentrytitle>
	      <manvolnum>1</manvolnum>
	    </citerefentry>.
          </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-h</option></term>
	<term><option>--help</option></term>
	<listitem>
	  <para>
            Display usage information.
          </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-V</option></term>
	<term><option>--version</option></term>
	<listitem>
	  <para>
            Display version information.
          </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
	<refentrytitle>dch</refentrytitle>
	<manvolnum>1</manvolnum>
      </citerefentry>,
      <citerefentry>
	<refentrytitle>fakeroot</refentrytitle>
	<manvolnum>1</manvolnum>
      </citerefentry>,
      <citerefentry>
	<refentrytitle>dpkg-deb</refentrytitle>
	<manvolnum>1</manvolnum>
      </citerefentry>.
    </para>
  </refsect1>

  <refsect1>
    <title>DISCLAIMER</title>
    <para>
      &dhpackage; is a tool intended to help porters (e.g. amd64) with
      modifying packages for other architectures, and to augment deb-repack,
      which creates modified packages with identical version numbers as the
      official packages. Chaos will ensue! With &dhpackage;, a proper version
      number can be selected, which does not obstruct the next official
      release but can be specifically pinned with APT or held with dpkg.
    </para>

    <para>
      Please take note that &dhpackage; does not come without problems. While
      it works fine in most cases, it may just not in yours. Especially,
      please consider that it changes binary packages (only!) and hence can
      break strict versioned dependencies between binary packages generated
      from the same source. </para>

    <para>
      You are using this tool at your own risk and I shall not shed a tear if
      your gerbil goes up in flames, your microwave attacks the stereo, or the
      angry slamming of your fist spills your coffee into the keyboard, which
      sets off a chain reaction resulting in a vast amount of money transfered
      from your account to mine.
    </para>
  </refsect1>

  <refsect1>
    <title>AUTHOR</title>

    <para>
      &dhpackage; is Copyright 2004-5 by &dhusername; &dhemail; and
      modifications are Copyright 2006 by &dhmaintusername; &dhmaintemail;.
    </para>

    <para>
      Permission is granted to copy, distribute and/or modify this document
      under the terms of the Artistic License:
      <ulink>http://www.opensource.org/licenses/artistic-license.php</ulink>
      On Debian systems, the complete text of the Artistic License can be
      found
      in <filename>/usr/share/common-licenses/Artistic</filename>.
    </para>

    <para>
      This manual page was written by &dhusername; &dhemail; and
      modified by &dhmaintusername; &dhmaintemail;.
    </para>

  </refsect1>
</refentry>

<!--
  Local Variables: 
  mode: xml
  End: 
-->