Add DocBook version of deb-control(5) manpage

diff --git a/ChangeLog b/ChangeLog
index d7f6f52e147f673491e257d96b350b134dea19a9..1a1f68552eac55db32bfcf0272238595da75282c 100644 (file)
--- a/ChangeLog
+++ b/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.

diff --git a/man/en/deb-control.5.sgml b/man/en/deb-control.5.sgml
new file mode 100644 (file)
index 0000000..80a8179
--- /dev/null
+++ b/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>
+