Re: Updated maint-guide contents, question on style
Osamu Aoki wrote:
> Thanks a lot. I just committed this. Questions and comments as below.
> Please proof proposed text.
Meanwhile I've noticed quite a few (mostly very dull) things that
still needed changing after my patch 4a, so here's 4b. Fortunately
it's only a few kb.
>> It's possible that the explanation in 4.1 about the Architecture line
>> of the control file needs to be updated, now that architecture can
>> mean "kernel" as well as "broad CPU-type category".
>
> If we mention anything, I think it is best to keep it as link to Policy
> as footnote. This itself is pedantic topic for new maintainers.
>
> Maybe, explaining difference in usage for all and any may help NM.
> I see 2 places mentioning *Architecture*.
>
> | Source packages which have binary packages with Architecture: any are
> | rebuilt by the autobuilder. Since this autobuilder procedure installs
> | only the packages listed in the Build-Depends field before running
> | debian/rules build (see Section 6.2, “Autobuilder”), the Build-Depends
> | field needs to list practically all the required packages and
> | Build-Depends-indep is rarely used.
>
> Maybe add a bit more words like "rebuilt by the autobuilder for each CPU
> architecture. Since this autobuilder ..." here too. oK?
I suppose it's true that inserting "for each architecture" makes it
clearer, but leave out the word "CPU" - the point I was trying to make
is that "architecture" as defined in Policy isn't just a matter of
hardware. After all, one of my machines dualboots i386/kfreebsd-i386
and another can run either i386 or amd64...
> | Line 10 describes the CPU architectures the binary package can be
> | compiled for. We'll leave this as any because dpkg-gencontrol(1) will
> | fill in the appropriate value for any machine this package gets compiled
> | on.
Since line 10 itself contains the field-name "Architecture:", we could
if we wanted simply bypass the whole issue here and say:
Line 10 describes the platforms the binary package can be
But here are typofixes anyway:
> + Line 10 describes the CPU architectures the binary package can be
> + compiled for. This value are usually one of the following depending
is
> + on the type of the binary package.
> + <footnote><para>See
> + <ulink url="http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Architecture";>Debian Policy Manua 5.6.8 "Architecture"</ulink>
> + for exact details.
> + </para></footnote>
> + * <literal>Architecture: any</literal>
> + - The geneated binary package is architecture dependent one
^r is an
> + usually from compiler languages.
in a compiled language.
> + * <literal>Architecture: all</literal>
> + - The generated binary package is architecture independent one
is an
> + usually generated from interpreter languages or
> + consisting of text or graphic data.
usually consisting of text, images, or scripts in an interpreted language
> +
> + We leave line 10 as is since this is written in the C language.
in C.
> + dpkg-gencontrol(1) will fill in the appropriate CPU architecture
architecture
> + value for any machine this source package gets compiled on.
[...]
>> 4.4.1 ends by recommending "info make". Unfortunately these days
>> that's in the non-free package make-doc.
>
> I guess we can still install pre-GFDL version from old archive and
> may be FREE. But that is not the worth the efforts. I can add following at the
> end.
>
> + <footnote><para>Since Debian considers the way the GFDL license is used for
> + make-doc to be non-free based on DFSG, make-doc is in non-free archive.
^the ^the ^area.
> + </para></footnote>
>
> What do you think?
Re-reading the end of 4.4.1 just makes me more worried:
# You are probably confused now, but it will all be clear upon
# examination of the rules file that dh_make gives us as a default. You
# should also read info make for more information.
Not only is info make hard to get hold of, but the claim that all will
be clear seems overoptimistic, given that the example dh_make will
offer consists of "%:\n\tdh $@". Point at the upstream Makefile,
perhaps? (Though it seems cruel to expect people to work out how to
write Makefiles just from reading them...)
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
--- maint-guide.en.dbk.pristine 2011-05-02 20:40:28.208922660 +0100
+++ maint-guide.en.dbk 2011-05-02 21:29:18.648925606 +0100
@@ -1891,7 +1891,7 @@
<literal>debian/rules build</literal> (see <xref
linkend="autobuilder"/>), the <literal>Build-Depends</literal> field
needs to list practically all the required packages and
-<literal>Build-Depends-indep</literal> is rarely used.
+<literal>Build-Depends-Indep</literal> is rarely used.
</para>
</listitem>
<listitem>
@@ -1909,7 +1909,7 @@
<literal>Build-Depends</literal> field to be on the safe side.
<footnote><para> This somewhat strange situation is a feature well documented
in the <ulink url="&policy-build-depends-indep;">Debian Policy
-Manual, Footnotes 48</ulink>. This is not due to the use of the
+Manual, Footnotes 55</ulink>. This is not due to the use of the
<command>dh</command> command in the <filename>debian/rules</filename> file but
due to how the <command>dpkg-buildpackage</command> works. The same situation
applies to the <ulink url="https://bugs.launchpad.net/launchpad-buildd/+bug/238141";>auto build system
@@ -1935,7 +1935,7 @@
$ dpkg -S libfoo.so.6
</screen>
<para>
-Then just take <literal>-dev</literal> version of every package as a
+Then just take the <literal>-dev</literal> version of every package as a
<literal>Build-Depends</literal> entry. If you use <command>ldd</command> for
this purpose, it will report indirect lib dependencies as well, resulting in
the problem of excessive build dependencies.
@@ -1981,7 +1981,7 @@
</para>
<para>
The package management tools usually behave the same way when dealing with
-these relations; if not, it will be explained. (see <citerefentry>
+these relations; if not, it will be explained. (See <citerefentry>
<refentrytitle>dpkg</refentrytitle> <manvolnum>8</manvolnum> </citerefentry>,
<citerefentry> <refentrytitle>dselect</refentrytitle> <manvolnum>8</manvolnum>
</citerefentry>, <citerefentry> <refentrytitle>apt</refentrytitle>
@@ -2099,7 +2099,7 @@
named package. These versions are listed in parentheses after each individual
package name, and should contain a relation from the list below followed
by the version number. The relations allowed are: <literal><<</literal>,
-<literal><=</literal>, <literal>=</literal>, <literal>>=</literal> and
+<literal><=</literal>, <literal>=</literal>, <literal>>=</literal>, and
<literal>>></literal> for strictly lower, lower or equal, exactly equal,
greater or equal, and strictly greater, respectively. For example,
</para>
@@ -2125,7 +2125,7 @@
<para>
<citerefentry> <refentrytitle>dh_perl</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> calculates Perl dependencies. It generates a list of a
-dependency on <literal>perl</literal> or <literal>perlapi</literal> for each binary package. This list is used for
+dependencies on <literal>perl</literal> or <literal>perlapi</literal> for each binary package. This list is used for
substituting <literal>${perl:Depends}</literal>.
</para>
<para>
@@ -2167,7 +2167,7 @@
</para>
<para>
We can insert <literal>Vcs-*</literal> fields to document the Version Control
-System (VCS) location between line 6 and 7.
+System (VCS) location between lines 6 and 7.
<footnote><para>See
<ulink url="&devref-bpp-vcs;">Debian Developer's Reference, 6.2.5. "Version Control System location"</ulink>.
</para></footnote>
@@ -2226,11 +2226,11 @@
gpl2</literal> option here to get a template file for the <systemitem role="package">gentoo</systemitem> package released under GPL-2.
</para>
<para>
-You must fill in missing information such as the place you got the package
-from, the actual copyright notice and their license to complete this file. For
-the common free software licenses such as GNU GPL-1, GNU GPL-2, GNU GPL-3,
-LGPL-2, LGPL-2.1, LGPL-3, GNU FDL-1.2, GNU FDL-1.3, Apache-2.0 or the Artistic
-license, you can just refer to the appropriate file in the
+You must fill in missing information to complete this file, such as the place you got the package
+from, the actual copyright notice, and the license. For certain
+common free software licenses (GNU GPL-1, GNU GPL-2, GNU GPL-3,
+LGPL-2, LGPL-2.1, LGPL-3, GNU FDL-1.2, GNU FDL-1.3, Apache-2.0, or the Artistic
+license), you can just refer to the appropriate file in the
<filename>/usr/share/common-licenses/</filename> directory that exists on every
Debian system. Otherwise, you must include the complete license.
</para>
@@ -2326,7 +2326,7 @@
created by the upstream authors, which you will later install as
<filename>/usr/share/doc/gentoo/changelog.gz</filename>). Let's assume your
ITP (Intent To Package) bug report number was <literal>12345</literal>. New
-lines must be inserted just before the uppermost line that begins with
+lines must be inserted just below the uppermost line that begins with
<literal>*</literal> (asterisk). You can do it with <citerefentry>
<refentrytitle>dch</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>, or
manually with a text editor.
@@ -2428,7 +2428,7 @@
Rules that you want to execute are invoked as command line arguments (for
example, <literal>./debian/rules build</literal> or <literal>fakeroot make -f
debian/rules binary</literal>). After the target name, you can name the
-dependency, program or file that the rule depends on. After that, there can be
+dependency, program, or file that the rule depends on. After that, there can be
any number of commands, indented with
<literal><replaceable>TAB</replaceable></literal>. A new rule begins with the
target declaration in the first column. Empty lines and lines beginning with
@@ -2463,7 +2463,7 @@
</screen>
<para>
(I've added the line numbers. In the actual <filename>rules</filename> file,
-the leading white spaces are TAB codes.)
+the leading spaces are a TAB code.)
</para>
<para>
You are probably familiar with lines like line 1 from shell and Perl scripts.
@@ -2487,7 +2487,7 @@
targets", which then call a single program, <command>dh</command>, with the target
name. <footnote><para> This uses the new <systemitem role="package">debhelper</systemitem> v7 features. Its design concepts are
explained in <ulink url="&debhelper-slides;">Not Your
-Grandpa's Debhelper</ulink> presented at Debconf9 by the <systemitem role="package">debhelper</systemitem> upstream. Under
+Grandpa's Debhelper</ulink> presented at DebConf9 by the <systemitem role="package">debhelper</systemitem> upstream. Under
<literal>lenny</literal>, <command>dh_make</command> created a much more
complicated <filename>rules</filename> file with explicit rules
and many <command>dh_*</command> scripts listed for each one, most of
@@ -2605,7 +2605,7 @@
<command>dh_*</command> scripts do exactly, and what their other options are,
please read their respective manual pages and the <systemitem role="package">debhelper</systemitem> documentation. </para> </footnote> There
are a few notable ones that are worth giving (over)simplified explanations here assuming
-typical build environment based on a <filename>Makefile</filename>.
+a typical build environment based on a <filename>Makefile</filename>.
<footnote><para> These commands support other build environments such as
<filename>setup.py</filename> which can be listed by executing
<literal>dh_auto_build --list</literal> in a package source directory. </para>
@@ -2994,8 +2994,8 @@
The <command>dh_installchangelogs</command> command requires
<filename>FIXES</filename> as its argument to install it. <footnote><para> The
<filename>debian/changelog</filename> and <filename>debian/NEWS</filename>
-files are always automatically installed. The upstream changelog is searched
-by converting filenames to the lower case and matching them with the
+files are always automatically installed. The upstream changelog is ound
+by converting filenames to lower case and matching them against
<filename>changelog</filename>, <filename>changes</filename>,
<filename>changelog.txt</filename>, and <filename>changes.txt</filename>.
</para> </footnote>
Reply to: