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 <[email protected]> > +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 <[email protected]> :-) Cheers, -- Raphaël Hertzog ◈ Debian Developer Follow my Debian News ▶ http://RaphaelHertzog.com (English) ▶ http://RaphaelHertzog.fr (Français) -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected] Archive: http://lists.debian.org/[email protected]
