[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: [PATCH] Create manpage deb-src-control(5)


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"


> +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

> +.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


> +example because they conflict with the used build system.


> +.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.

> +
> +.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.

> +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 


> +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.

> +
> +
> +.\" .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:

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>


Raphaël Hertzog ◈ Debian Developer

Follow my Debian News ▶ http://RaphaelHertzog.com (English)
                      ▶ http://RaphaelHertzog.fr (Français)

Reply to: