Add DocBook version of deb-control(5) manpage

ChangeLog

@@ -1,3 +1,7 @@
+Sat Apr 13 22:59:25 CEST 2002 Wichert Akkerman <wichert@deephackmode.org>
+
+  * man/en/deb-control.5.sgml: DocBook version of deb-control manpage
+
 Sat Apr 13 18:07:48 CET 2002 peter karlsson <peterk@debian.org>
 
   * po/sv.po: Removed fuzzy translation.

man/en/deb-control.5.sgml

@@ -0,0 +1,426 @@
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+
+<refentry id="deb-control.5">
+  <refmeta>
+    <refentrytitle>deb-control</refentrytitle>
+    <manvolnum>5</manvolnum>
+    <refmiscinfo class="source">Debian Project</refmiscinfo>
+    <refmiscinfo class="manual">dpkg utilities</refmiscinfo>
+  </refmeta>
+
+  <refnamediv>
+    <refname>deb-control</refname>
+    <refpurpose>Debian packages' master control file format</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <synopsis><filename>control</filename></synopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>
+      Each Debian package contains the master <filename>control</filename>
+      file, which contains a number of fields. Each field begins with a tag,
+      such as <emphasis>Package</emphasis> or <emphasis>Version</emphasis>
+      (case insensitive), followed by a colon, and the body of the field.
+      Fields are delimited only by field tags. In other words, field text may
+      be multiple lines in length, but the installation tools will generally
+      join lines when processing the body of the field (except in the case of
+      the <emphasis>Description</emphasis> field, see below).
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Required Fields</title>
+
+    <variablelist>
+      <varlistentry>
+	<term>
+	  <cmdsynopsis>
+	    <arg choice="plain">Package: <replaceable>package_name</replaceable></arg>
+	  </cmdsynopsis>
+	</term>
+
+	<listitem>
+	  <para>
+	    The value of this field determines the package name, and is used to
+	    generate file names by most installation tools.
+	  </para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>
+	  <cmdsynopsis>
+	    <arg choice="plain">Version: <replaceable>version_string</replaceable></arg>
+	  </cmdsynopsis>
+	</term>
+
+	<listitem>
+	  <para>
+	    Typically, this is the original package's version number in
+	    whatever form the program's author uses. It may also include a
+	    Debian revision number (for non-native packages). If both version
+	    and revision are supplied, they are seperated by a hyphen
+	    (<keycap>-</keycap>. For this reason, the original version may not
+	    have a hyphen in its version number.
+	  </para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>
+	  <cmdsynopsis>
+	    <arg choice="plain">Maintainer: <replaceable>fullname</replaceable> <replaceable>email</replaceable></arg>
+	  </cmdsynopsis>
+	</term>
+
+	<listitem>
+	  <para>
+	    Should be in the format `Joe Bloggs &lt;jbloggs@foo.com&gt;', and
+	    is typically the person who created the package, as opposed to the
+	    author of the software that was packaged.
+	  </para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>
+	  <cmdsynopsis>
+	    <arg choice="plain">Description: <replaceable>short description</replaceable><sbr> <replaceable>long description</replaceable></arg>
+	  </cmdsynopsis>
+	</term>
+
+	<listitem>
+	  <para>
+	    The format for the package description is a short brief summary on
+	    the first line (after the "Description" field). The following lines
+	    can be used as a longer, more detailed description. Each line of
+	    the long description must be preceded by a space, and blank lines
+	    in the long desription must contain a single '.' following the
+	    preceding space.
+	  </para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Optional Fields</title>
+
+    <variablelist>
+      <varlistentry>
+	<term>
+	  <cmdsynopsis>
+	    <arg choice="plain">Section: <replaceable>section</replaceable></arg>
+	  </cmdsynopsis>
+	</term>
+
+	<listitem>
+	  <para>
+	    This is a general field that gives the package a category based on
+	    the software that it installs. Some common sections are `utils',
+	    `net', `mail', `text', `x11' etc.
+	  </para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>
+	  <cmdsynopsis>
+	    <arg choice="plain">Priority: <replaceable>priority</replaceable></arg>
+	  </cmdsynopsis>
+	</term>
+
+	<listitem>
+	  <para>
+	    Sets the importance of this package in relation to the system as a
+	    whole.  Common priorities are `required', `standard', `optional',
+	    `extra' etc.
+	  </para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>
+      In Debian, the <emphasis>Section</emphasis> and
+      <emphasis>Priority</emphasis> fields have a defined set of accepted
+      values based on the Policy Manual. They are used to decide how the
+      packages are layed out in the archive. A list of these can be
+      obtained from the latest version of
+      <emphasis>debian-policy</emphasis> package.
+    </para>
+
+    <variablelist>
+      <varlistentry>
+	<term>
+	  <cmdsynopsis>
+	    <arg choice="plain">Essential: 
+	      <group choice="req">
+	        <arg>yes</arg>
+		<arg>no</arg>
+	      </group>
+	    </arg>
+	  </cmdsynopsis>
+	</term>
+
+	<listitem>
+	  <para>
+	    This field is usually only needed when the answer is `yes'. It
+	    denotes a package that is required for proper operation of the
+	    system. <command>dpkg</command> or any other installation tool will
+	    not allow an <emphasis>Essential</emphasis> package to be removed
+	    (at least not without using one of the force options).
+	  </para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>
+	  <cmdsynopsis>
+	    <arg choice="plain">Architecture:
+	      <group choice="req">
+	        <arg>&lt;arch&gt;</arg>
+		<arg>all</arg>
+	      </group>
+	    </arg>
+	  </cmdsynopsis>
+	</term>
+
+	<listitem>
+	  <para>
+	    The architecture specifies which type of hardware this package was
+	    compiled for. Common architectures are `i386', `m68k', `sparc',
+	    `alpha', `powerpc' etc. Note that the <emphasis>all</emphasis>
+	    option is meant for packages that are architecture independent.
+	    Some examples of this are shell or python scripts, or
+	    documentation.
+	  </para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>
+	  <cmdsynopsis>
+	    <arg choice="plain">Source: <replaceable>source_name</replaceable></arg>
+	  </cmdsynopsis>
+	</term>
+
+	<listitem>
+	  <para>
+	    The name of the source package that this binary package came from,
+	    if different than the name of the package itself.
+	  </para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>
+	  <cmdsynopsis>
+	    <arg choice="plain" rep="repeat">Depends: <replaceable>package</replaceable></arg>
+	  </cmdsynopsis>
+	</term>
+
+	<listitem>
+	  <para>
+	    List of packages that are required for this package to provide a
+	    non-trivial amount of functionality.  The package maintenance
+	    software will not allow a package to be installed if the packages
+	    listed in its <emphasis>Depends</emphasis> field are not installed
+	    (at least not without using the force options), and will run the
+	    postinst scripts of packages listed in Depends: fields before those
+	    of the packages which depend on them, and run prerm scripts before.
+	  </para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>
+	  <cmdsynopsis>
+	    <arg choice="plain" rep="repeat">Pre-Depends: <replaceable>package</replaceable></arg>
+	  </cmdsynopsis>
+	</term>
+
+	<listitem>
+	  <para>
+	    List of packages that must be installed <emphasis>and</emphasis>
+	    configured before this one can be installed. This is usually used
+	    in the case where this package requires another package for running
+	    its preinst script.
+	  </para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>
+	  <cmdsynopsis>
+	    <arg choice="plain" rep="repeat">Recommends: <replaceable>package</replaceable></arg>
+	  </cmdsynopsis>
+	</term>
+
+	<listitem>
+	  <para>
+	    Lists packages that would be found together with this one in all
+	    but unusual installations.  The package maintenance software will
+	    warn the user if they install a package without those listed in its
+	    <emphasis>Recommends</emphasis> field.
+	  </para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>
+	  <cmdsynopsis>
+	    <arg choice="plain" rep="repeat">Suggests: <replaceable>package</replaceable></arg>
+	  </cmdsynopsis>
+	</term>
+
+	<listitem>
+	  <para>
+	    Lists packages that are related to this one and can perhaps enhance
+	    its usefulness, but without which installing this package is
+	    perfectly reasonable.
+	  </para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>
+      The syntax of <emphasis>Depends</emphasis>,
+      <emphasis>Pre-Depends</emphasis>, <emphasis>Recommends</emphasis> and
+      <emphasis>Suggests</emphasis> fields is a list of groups of alternative
+      packages.  Each group is a list of packages separated by vertical bar (or
+      <keysym>pipe</keysym>) symbols, `<keycode>|</keycode>'.  The groups are
+      separated by commas.  Commas are to be read as `AND', and pipes as `OR',
+      with pipes binding more tightly.  Each item is a package name optionally
+      followed by a version number specification in parentheses.
+    </para>
+
+    <para>
+      A version number may start with a `&gt;&gt;', in which case any later
+      version will match, and may specify or omit the Debian packaging revision
+      (separated by a hyphen). Accepted version relationships are "&gt;&gt;"
+      for greater than, "&lt;&lt;" for less than, "&gt;=" for greater than or
+      equal to, "&lt;=" for less than or equal to, and "=" for equal to.
+    </para>
+
+    <variablelist>
+      <varlistentry>
+	<term>
+	  <cmdsynopsis>
+	    <arg choice="plain" rep="repeat">Conflicts: <replaceable>package</replaceable></arg>
+	  </cmdsynopsis>
+	</term>
+
+	<listitem>
+	  <para>
+	    Lists packages that conflict with this one, for example by
+	    containing files with the same names. The package maintenance
+	    software will not allow conflicting packages to be installed at the
+	    same time. Two conflicting packages should each include a
+	    <emphasis>Conflicts</emphasis> line mentioning the other.
+	  </para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>
+	  <cmdsynopsis>
+	    <arg choice="plain" rep="repeat">Replaces: <replaceable>package</replaceable></arg>
+	  </cmdsynopsis>
+	</term>
+
+	<listitem>
+	  <para>
+	    List of packages files from which this one replaces. This is used
+	    for allowing this package to overwrite the files of another package
+	    and is usually used with the <emphasis>Conflicts</emphasis> field
+	    to force removal of the other package, if this one also has the
+	    same files as the conflicted package.
+	  </para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>
+	  <cmdsynopsis>
+	    <arg choice="plain" rep="repeat">Provides: <replaceable>package</replaceable></arg>
+	  </cmdsynopsis>
+	</term>
+
+	<listitem>
+	  <para>
+	    This is a list of virtual packages that this one provides. Usuaully
+	    this is used in the case of several packages all providing the same
+	    service. For example, sendmail and exim can can serve as a mail
+	    server, so they provide a common package (`mail-transport-agent')
+	    on which other packages can depend. This will allow sendmail or
+	    exim to serve as a valid option to satisy the dependency. This
+	    prevents the packages that depend on a mail server from having to
+	    know the package names for all of them, and using `|' to separate
+	    the list.
+	  </para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>
+      The syntax of <emphasis>Conflicts</emphasis>,
+      <emphasis>Replaces</emphasis> and <emphasis>Provides</emphasis> is a list
+      of package names, separated by commas (and optional whitespace). In the
+      <emphasis>Conflicts</emphasis> field, the comma should be read as `OR'.
+      An optional version can also be given with the same syntax as above for
+      the <emphasis>Conflicts</emphasis> and <emphasis>Replaces</emphasis>
+      fields.
+    </para>
+  </refsect1>
+
+  <refsect1><title>Example</title>
+
+    <literallayout>
+Package: grep
+Essential: yes
+Priority: required
+Section: base
+Maintainer: Wichert Akkerman &lt;wakkerma@debian.org&gt;
+Architecture: sparc
+Version: 2.4-1
+Pre-Depends: libc6 (&gt;= 2.0.105)
+Provides: rgrep
+Conflicts: rgrep
+Description: GNU grep, egrep and fgrep.
+ The GNU family of grep utilities may be the "fastest grep in the west".
+ GNU grep is based on a fast lazy-state deterministic matcher (about
+ twice as fast as stock Unix egrep) hybridized with a Boyer-Moore-Gosper
+ search for a fixed string that eliminates impossible text from being
+ considered by the full regexp matcher without necessarily having to
+ look at every character. The result is typically many times faster
+ than Unix grep or egrep. (Regular expressions containing backreferencing
+ will run more slowly, however.)
+     </literallayout>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry>
+        <refentrytitle>deb</refentrytitle>
+	<manvolnum>5</manvolnum>
+      </citerefentry>,
+
+      <citerefentry>
+        <refentrytitle>dpkg</refentrytitle>
+	<manvolnum>8</manvolnum>
+      </citerefentry>,
+
+      <citerefentry>
+        <refentrytitle>dpkg-deb</refentrytitle>
+	<manvolnum>1</manvolnum>
+      </citerefentry>
+    </para>
+  </refsect1>
+</refentry>
+