<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
 "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd" [
 ]>
<book label="langupdate" status="0.0.6">
  <bookinfo>
    <title>langupdate</title>
    <copyright>
      <year>2006-2008</year>
      <holder>Neil Williams</holder>
    </copyright>
    <date>Thu Jan  8 21:04:16 GMT 2009</date>
    <releaseinfo>Release: 0.0.6</releaseinfo>
    <legalnotice id="GPL">
      <title>The GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007</title>
      <para>This documentation is part of langupdate.</para>
      <para>langupdate is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 3 of the License, or
    (at your option) any later version.</para>
    <para>This program 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 General Public License for more details.</para>
    <para>You should have received a copy of the GNU General Public License
    along with this program.  If not, see 
    <ulink url="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</ulink>.
    </para>
      <note>
        <para>You can find a copy of the GNU General
Public Licence in the <filename>COPYING</filename>
file in the langupdate source or installed (e.g. in
/usr/share/doc/langupdate/) by your distribution.</para>
      </note>
    </legalnotice>
  </bookinfo>
  <chapter label="1" id="manpages"><title>LANGUPDATE</title>
<refentry id="langupdate">
  <refentryinfo>
    <productname>LANGUPDATE</productname>
    <productnumber>1</productnumber>
  </refentryinfo>
  <refmeta>
    <refentrytitle>langupdate</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo>Copyright FSF 1996-2006</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>langupdate</refname>
    <refpurpose>
    An apt frontend for the Emdebian implementation of 'tdebs'
    </refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>langupdate</command>
      <arg>
        <group>
          <arg>-n</arg> <arg>--dry-run </arg>
        </group>
      </arg>
      <arg>
        <group>
          <arg>--suite</arg>
        </group>
        <replaceable>string</replaceable>
      </arg>
      <arg>
        <group>
          <arg>-r</arg>
          <arg>--autoremove</arg>
        </group>
      </arg>
      <arg>
        <group>
          <arg>-m</arg>
          <arg>--mirror</arg>
        </group>
        <replaceable>string</replaceable>
      </arg>
      <arg>
        <group>
          <arg>-v</arg>
          <arg>--verbose</arg>
        </group>
        <replaceable>integer</replaceable>
      </arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>langupdate</command>
      <arg choice="req">
        <group>
          <arg>-?</arg>
          <arg>-h</arg>
          <arg>--help</arg>
          <arg>--version</arg>
        </group>
      </arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>Description</title>
    <para><emphasis>langupdate</emphasis> is a method for synchronising
    the translation file support with the list of installed packages and
    the list of locales supported on their own machine.
    </para>
    <para><emphasis>langupdate</emphasis> uses a temporary file for the
    sources.list and updates it from the list of supported locales each
    time langupdate is run, i.e. it combines the effects of 
    <computeroutput>apt-get update</computeroutput> with 
    <computeroutput>apt-get upgrade</computeroutput>. tdeb packages have
    no dependencies so 'dist-upgrade' is not required.
    </para>
  </refsect1>
  <refsect1>
    <title>Purpose</title>
    <para>Emdebian TDebs provide a method for splitting all translation files out of
    packages and into separate TDeb packages, organised by the locale root and
    source package. This allows individual users to only install translations
    files for the locales supported on their own machine and only for the
    packages installed at the time.</para>
    <para>Note that this functionality is not available for Debian TDebs
    and <command>langupdate</command> does not install any translation
    packages if only Debian packages are installed as these already contain
    all the translation files.</para>
    <para><command>langupdate</command> is intended to support Emdebian Grip
    where Emdebian packages can be mixed with Debian packages.
    </para>
    <refsect2>
      <title>Disc space is not cheap</title>
      <para>Debian packages collate all available translations into a
      single package which can easily lead to 250Mb of unused translation
      files on a typical installation. Emdebian generates a single
      package for every translation of each Emdebian package, leading
      to a tenfold increase in the number of binary packages built from
      each source package. To solve this problem, langupdate supports a
      secondary apt cache so that the main apt cache can be kept as
      small as possible.
      </para>
      <para><emphasis>langupdate</emphasis> then queries the secondary
      apt cache to get a list of all translation packages (tdebs) that
      match the list of locales supported on the device. This list is
      then compared with the list of installed binaries. The translation
      packages that match the installed package are then installed with
      <command>apt-get</command>.
      </para>
    </refsect2>
    <refsect2>
      <title>Why C and C++?</title>
      <para>There is no direct hook into <command>apt-get upgrade</command>
      and no easy way of reading the apt-cache from C without forking a
      call to apt-cache itself. So I use libapt-pkg which is a C++ library.
      The rest of the code is C because I prefer to use the memory
      management of glib2. If anyone fancies porting langupdate to just
      C++ for use on devices that do not have room for libglib2.0-0,
      patches are welcome.
      </para>
    </refsect2>
  </refsect1>
  <refsect1>
    <title>Commands</title>
    <variablelist>
        <varlistentry>
          <term>
            <option>-r</option>|<option>--autoremove</option>
          </term>
          <listitem>
            <para>Request apt to purge all orphaned TDebs - either where
            the package has been uninstalled or the locale has become
            unsupported.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>--version</option>
          </term>
          <listitem>
            <para>Display version of <emphasis>langupdate</emphasis>
            and exit.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <option>-?</option>|
            <option>-h</option>|<option>--help</option>
          </term>
          <listitem>
            <para>Display help message for <emphasis>langupdate</emphasis>
            and exit.</para>
          </listitem>
        </varlistentry>
     </variablelist>
  </refsect1>
  <refsect1>
    <title>Options</title>
    <refsect2>
      <title>langupdate options</title>
      <variablelist>
      <varlistentry>
        <term><option>-n</option>|<option>--dry-run</option>
        </term>
        <listitem>
          <para>Show the cache data without installing any packages.
          (In autoremove mode, show the list of packages to be removed
          without performing the purge.)
        </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-m</option>|<option>--mirror</option>
        <replaceable>MIRROR</replaceable></term>
        <listitem>
          <para>
          Override the default Emdebian mirror 
          (<emphasis>http://www.emdebian.org/locale/</emphasis>) and use a
          different one.
        </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--suite</option>
        <userinput> SUITE</userinput></term>
        <listitem>
          <para>
          Specify a different suite to check. Only suites supported by
          the chosen mirror will be usable. The default Emdebian mirror
          only supports <filename>testing</filename> and
          <filename>unstable</filename> or the codenames
          <filename>sid</filename>, <filename>lenny</filename> and
          (once Lenny is released) <filename>squeeze</filename>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--verbose</option>
        <userinput> integer</userinput></term>
        <listitem>
          <para>
          Increase the verbosity of messages, levels between 0 and 4
          are supported.
        </para>
        </listitem>
      </varlistentry>
      </variablelist>
    </refsect2>
  </refsect1>
  <refsect1>
    <title>langupdate and Debian</title>
    <para><command>langupdate</command> is primarily intended for Emdebian
    support and plans for TDebs in Debian are only at a planning stage.
    Emdebian packages can be identified by the <emphasis>em[0-9]</emphasis>
    version suffix:
    </para>
    <example id="emdebian_suffix">
      <title>Example of an Emdebian version suffix in use</title>
      <programlisting>
apt-cache show dpkg
Package: dpkg
Source: dpkg (1.14.23)
Version: 1.14.23em1
Architecture: amd64
Maintainer: Dpkg Developers &lt;debian-dpkg@lists.debian.org&gt;
Installed-Size: 1096
Pre-Depends: libc6 (>= 2.7-1), coreutils (>= 5.93-1), lzma
Replaces: manpages-de (&lt;= 0.4-3em1), manpages-pl (&lt;= 20051117-1em1)
Conflicts: apt (&lt;&lt; 0.7.7em1), aptitude (&lt;&lt; 0.4.7-1em1), dpkg-dev (&lt;&lt; 1.14.16em1), dpkg-iasearch (&lt;&lt; 0.11em1), sysvinit (&lt;&lt; 2.82-1em1)
Priority: required
Section: admin
Filename: pool/main/d/dpkg/dpkg_1.14.23em1_amd64.deb
Size: 447968
      </programlisting>
    </example>
    <para>Emdebian packages already have all <filename>/usr/share/locale/*</filename>
    content removed, so the Emdebian TDeb does not need to <emphasis>Replace:</emphasis>
    the Emdebian package. There is one Emdebian TDeb per source package per locale
    per architecture which could, potentially, have to <emphasis>Replace:</emphasis>
    multiple binary packages built from the one source package in Debian. Even if
    the sysadmin removes files from <filename>/usr/share/locale/</filename>
    manually, it is not trivial for <command>langupdate</command> to identify
    which files remain and therefore which TDebs could be safely installed.
    Therefore, <command>langupdate</command> compares the list of binary packages
    installed with the list of available TDebs and ignores TDebs where the binary
    package does not bear an Emdebian version suffix.
    </para>
    <para>Unless the system includes a mix of both Debian and Emdebian packages,
    <command>langupdate</command> will report that there is nothing to do.
    </para>
  </refsect1>
  <refsect1>
    <title>Bugs</title>
    <para>langupdate is heavily reliant on accurate data in the <filename>dpkg</filename>
    and <filename>apt</filename> data sources. The size of these data sources also
    has a significant impact on processing time, especially where a mix of Debian
    and Emdebian packages exist.
    </para>
    <para>Please attach the output of <command>apt-cache policy</command> to
    all bug reports against langupdate in Debian.
    </para>
  </refsect1>
  <refsect1>
    <title>Author</title>
    <para><emphasis>langupdate</emphasis> was written
      by Neil Williams <email>linux@codehelp.co.uk</email>.
    </para>
    <para>This  manual  page  was  written by Neil Williams
      <email>linux@codehelp.co.uk</email>
    </para>
  </refsect1>
  <refsect1>
    <title>Copyright</title>
    <para>This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 3 of the License, or
  (at your option) any later version.</para>
  <para>This program 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 General Public License for more details.</para>
  <para>You should have received a copy of the GNU General Public License
  along with this program.  If not, see 
  &lt;<ulink url="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</ulink>&gt;.
  </para>
  </refsect1>
</refentry>
</chapter>
</book>