Re: Updated maint-guide contents, question on style
On Sun, May 01, 2011 at 06:27:40PM +0100, Justin B Rye wrote:
> [Third try. Maybe the attachment's too big? I'll compress it.]
>
> Chapter 4, required files.
Thanks a lot. I just committed this. Questions and comments as below.
Please proof proposed text.
> I'm making this chapter harder for myself by trying to harmonise its
> use of jargon with Policy. For a start in 4.1 there's the subtle
> difference between "control files" (meaning the ones named "control")
> and "control files" (.dsc files are also control files); though in
> this case we're safe thanks to DocBook's <filename> tags.
If you find any case which may be confusing, I think use of
<filename>debian/control</filename>
may be clearer. For now, I take simplicity of the current style.
> In the following couple of paragraphs I have changed a couple of
> things: "section" and "subsection" become "(archive) area" and
> "section".
Good catch.
> 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?
| 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.
+ Line 10 describes the CPU architectures the binary package can be
+ compiled for. This value are usually one of the following depending
+ 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
+ usually from compiler languages.
+ * <literal>Architecture: all</literal>
+ - The generated binary package is architecture independent one
+ usually generated from interpreter languages or
+ consisting of text or graphic data.
+
+ We leave line 10 as is since this is written in the C language.
+ dpkg-gencontrol(1) will fill in the appropriate CPU architecture
+ value for any machine this source package gets compiled on.
> The description of Suggests claimed that "all frontends will likely
...
> reversing it to say they probably *won't* do this.
Good catch. I must have forgot to edit copied text. Thanks.
...
> 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.
+ </para></footnote>
What do you think?
Osamu
Reply to: