Re: [PATCH] Create manpage deb-src-control(5)
Hi,
On Tue, 23 Nov 2010, Oxan van Leeuwen wrote:
> I participate in the Google Code-In and completed the task of writing a manpage
> for deb-src-control(5), the format of the debian/control files in source
> packages. I've also documented some fields in the deb-control(5) manpage.
Thanks for your help!
> man/Makefile.am | 1 +
> man/deb-control.5 | 26 ++++
> man/deb-src-control.5 | 323 +++++++++++++++++++++++++++++++++++++++++++++++++
You also have to record the manual page in man/po/po4a.cfg
so that it gets translated.
> --- a/man/deb-control.5
> +++ b/man/deb-control.5
> @@ -98,9 +98,35 @@ The upstream project home page URL.
> List of tags describing the qualities of the package. The description and
> list of supported tags can be found in the \fBdebtags\fP package.
> .TP
> +.BR Multi-Arch: " <same|foreign|allowed>"
> +This field is used to indicate how this package should behave on a multi-arch
> +installations. The value same means that the package is co-installable with
> +itself, but it must not be used to satisfy the dependency of any package of a
> +different architecture from itself. The foreign value means that the package is
> +not co-installable with itself, but should be allowed to satisfy the dependency
> +of a package of a different arch from itself. The allowed value allows
> +reverse-dependencies to indicate in their Depends field that they need a
> package
> +from a foreign architecture, but has no effect otherwise. This field should not
> +be present in packages with the Architecture: all field.
The values should be quoted `same', `foreign', `allowed' and you should
say "the value `foo'", because "the foreign/allowed value" is misleading...
> --- /dev/null
> +++ b/man/deb-src-control.5
> @@ -0,0 +1,323 @@
> +.\" Author: Oxan van Leeuwen
> +.\" Includes text from the deb-control manapge by Raul Miller
s/manapge/manual page/
> +.TH deb\-control 5 "2010-11-22" "Debian Project" "Debian"
deb\-src\-control
> +.SH DESCRIPTION
> +Each Debian source package contains the master `control' file, which contains
> +of at least 2 paragraphs, separated by a blank line. The first paragraph lists
"consists of at least 2" or "contains at least"
> +all information about the source package in general, while each following
> +paragraph describes exactly one binary package the source package builds.
I would drop the "the source package builds" (the source package might not
build all of them, depending on the architecture).
> +Each paragraph consists of a number of fields. Each field begins with a tag,
> +such as
> +.B Package
> +or
> +.B Section
> +(case insensitive), followed by a colon, and the body of the field. The
> +fields are delimited by field tags or empty lines (which ends a paragraph).
> +In other words, field text may be multiple lines in length, but the tools that
> +handle the file will generally join lines when processing the body of the
> field
> +(except in the case of the
> +.B Description
> +field, see below). Lines starting with a \fB'#'\fP are treated as comments.
I know this is copied from the existing manpage but I find the wording so
awkward and difficult to understand. And it doesn't make it clear that
multi-line fields are allowed but they have a precise structure to follow.
(i.e. supplementary lines must start with spaces).
I wouldn't mind if you tried to improve it :-)
> +.BR Standards-Version: " <version string>"
> +This documents the most recent version of the standards (which consists of the
> +Policy
> +Manual and referenced texts from the
I would add "Debian" before "Policy manual"
> +.B debian-policy
> +package) this package complies to.
> +
> +.TP
> +.BR DM-Upload-Allowed: " <yes|no>"
> +This fields allows the uploading of the package by Debian Maintainers, given
s/fields/field/, suggestion: "indicates whether the package can be
uploaded by Debian Maintainers appearing in the Maintainer or Uploaders
field"
> +.TP
> +.BR Build-Depends: " <package list>"
> +A list of packages that need to be installed and configured for this package
> +to build the architecture dependant packages (where Architecture is not all,
> +see below), for example development headers.
Not quite true. Those packages are always needed, whatever you build.
s/for this...$/to be able to build the source package./
> +.TP
> +.BR Build-Depends-Indep: " <package list>"
> +Same as Build-Depends, but for when building the architecture independent
> +packages. The Build-Depends are also installed in this case.
s/for/they are only needed/
> +.BR Build-Conflicts: " <package list>"
> +A list of packages that should not be installed when the package is build, for
s/build/built/
> +example because they conflict with the used build system.
s/conflict/interfere/
> +.TP
> +.BR Build-Conflicts-Indep: " <package list>"
> +Same as Build-Conflicts, but for when building the architecture independent
s/for/it must be taken into account only/
> +packages. The Build-Conflicts
> +
> +\n
Something forgotten here?
And "\n" looks weird to me. At least I haven't seen anything like that in
the current manual pages.
> +.TP
> +.BR Package: " <binary package name> (required)"
> +This field is used to name the binary package name. The same restrictions as
> +to a source package name apply.
> +
> +.TP
> +.BR Architecture: " <arch|all|any> (required)"
> +The architecture specifies on which type of hardware this package runs. For
> +packages that run on all architectures, use the
> +.B any
> +value. For packages that are architecture independent, such as shell and Perl
> +scripts or documentation, use the
> +.B all
> +value. To restrict the packages to a certain set of architectures, specify the
> +architecture names, separated by a space.
You can also use architecture wildcards.
http://www.debian.org/doc/debian-policy/ch-customized-programs.html#s-arch-wildcard-spec
http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Architecture
> +
> +.TP
> +.BR Package-Type: " <deb|udeb>"
> +This field indicates whether this binary package is an udeb for use in the
> +debian-installer. This field is not needed for normal packages.
It's a bit too restrictive, we might have other values in the future. I
would say that it's marker to define specific type of packages, that "deb"
is the default and implicit value, and that "udeb" is for size-constrained
packages used by the debian installer.
> +.SH USER-DEFINED FIELDS
> +It is allowed to add additional user-defined fields to the control file. The
> +tools will ignore these fields. If you want the fields to be copied over to
> +the output files, such as the binary packages, you need to use a custom naming
> +scheme: the fields should start with a X, followed by one or more of the
> +letters BCS and a hypen. If the letter B is used, the field will appear in the
> +control file in the binary package, see
> +.BR deb-control (5)
> +, for the letter S in the source package control file as constructed by
> +.BR dpkg-source (1)
> +and for the letter C in the upload control (.changes) files. Note that the BCS
s/files/file/
> +letters are stripped when they are copied over to the output files. A field as
> +XC-Approved-By will appear as X-Approved-By in the changes file and will not
> +appear in the binary or source package control files.
Actually the "X.*-" is stripped in its entirety. So you would get
"Approved-By" in the resulting file.
> +
> +
> +.SH EXAMPLE
> +.\" .RS
> +.nf
> +# Comment
> +Source: dpkg
> +Section: admin
> +Priority: required
> +Maintainer: Dpkg Developers <debian-dpkg@lists.debian.org>
> +Origin: debian
> +Bugs: debbugs://bugs.debian.org
I would drop Origin and Bugs, we told users they are not needed usually.
> +# this field is not used by the tools and gets only copied to the changes file
> +XC-Old-Version: 1.15.8.5
A better example featuring a double copy.
XBS-Upstream-Release-Status: stable
> +Package: dpkg-dev
> +Section: utils
> +Priority: optional
> +Architecture: all
> +# this is a (quite useless) custom field in the binary package
> +XB-Used-Technology: perl
Trying to find an example that is more plausible...
XB-Mentoring-Contact: Raphaël Hertzog <hertzog@debian.org>
:-)
Cheers,
--
Raphaël Hertzog ◈ Debian Developer
Follow my Debian News ▶ http://RaphaelHertzog.com (English)
▶ http://RaphaelHertzog.fr (Français)
Reply to: