Re: Question on title and explanation of shuffles
Oops, I forgot the attachment on my last message, so I'll confuse
things by adding it to this one.
> I was making all section title of be followed by file(s) in Chapter 4
> and 5. You kept "file" for all titles in Chapter 4 and 1 title in
Did I? No, surely I took them out in Chapter 4. 5.15 looks like an
oversight.
> Chapter 5. But you removed "file" from most titles in Chapter 5.
>
> Any reason? What do you suggest to make some consistency?
This was tricky. Partly it was to avoid falling into the trap of
talking about a "'control' file" (as opposed to "control file");
partly it was because when you're introducing a file whose name the
reader isn't expected to recognise it's more idiomatic to refer to it
as "the file 'package.manpages'" (whereas if the name is
well-understood and helps the reader identify what kind of file it is,
it's more idiomatic to say it as "the README file"). Likewise "put it
in the directory ~/.shfqk" but "put it in the /tmp directory".
Of course, I was encouraged by the fact they're all wrapped in
<filename> tags.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
--- maint-guide.en.dbk.pristine 2011-04-30 12:52:45.588927791 +0100
+++ maint-guide.en.dbk 2011-04-30 18:09:40.025258209 +0100
@@ -585,28 +585,30 @@
Let's start by creating a package of your own (or, even better,
adopting an existing one).
</para>
-<section id="workflow"><title>Workflow of the Debian package building</title>
+<section id="workflow"><title>Debian package building workflow</title>
<para>
-If you are making a Debian package with an upstream program,
-typical workflow of the Debian package building involves generating several
-specifically named files for each step as the following.
+If you are making a Debian package with an upstream program, the
+typical workflow of Debian package building involves generating several
+specifically named files for each step as follows.
</para>
<itemizedlist>
<listitem>
-<para>We obtain an upstream program file usually in a compressed tar format.</para>
+<para>Get a copy of the upstream software, usually in a compressed tar format.</para>
<itemizedlist>
<listitem><literal><replaceable>package</replaceable>-<replaceable>version</replaceable>.tar.gz</literal></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
-We create a non-native Debian source package in the <literal>3.0 (quilt)</literal> format, which refers to the set of input files for
-the Debian package building, by adding Debian package modifications to the upstream program under the <filename>debian</filename> directory.
+Add Debian-specific packaging modifications to the upstream program under the
+<filename>debian</filename> directory, and create a non-native source package
+(that is, the set of input files used for Debian package building) in
+<literal>3.0 (quilt)</literal> format .
</para>
<itemizedlist>
<listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>.orig.tar.gz</literal></listitem>
<listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.debian.tar.gz</literal>
- <footnote><para>For the older non-native Debian source package in the <literal>1.0</literal> format,
+ <footnote><para>For the older style of non-native Debian source packages in <literal>1.0</literal> format,
<literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.diff.gz</literal>
is used instead. </para></footnote></listitem>
<listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.dsc</literal></listitem>
@@ -614,7 +616,7 @@
</listitem>
<listitem>
<para>
-We build Debian binary packages, which are ordinary installable package files in <literal>.deb</literal> format (or <literal>.udeb</literal> format, used by the Debian Installer), from the Debian source package.
+Build Debian binary packages, which are ordinary installable package files in <literal>.deb</literal> format (or <literal>.udeb</literal> format, used by the Debian Installer) from the Debian source package.
</para>
<itemizedlist>
<listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>
@@ -625,22 +627,17 @@
Please note that the character separating
<literal><replaceable>package</replaceable></literal> and
<literal><replaceable>version</replaceable></literal> was changed from
-<literal>-</literal> (hyphen) to <literal>_</literal> (underscore).
+<literal>-</literal> (hyphen) in the tarball name to
+<literal>_</literal> (underscore) in the Debian package filenames.
</para>
<para>
-Here,
-<literal><replaceable>package</replaceable></literal> part of the file name is substituted by the
-<emphasis role="strong">package name</emphasis>,
-<literal><replaceable>version</replaceable></literal> part of it is substituted by the
-<emphasis role="strong">upstream version</emphasis>,
-<literal><replaceable>revision</replaceable></literal> part of it is substituted by the
-<emphasis role="strong">Debian revision</emphasis>,
-<literal><replaceable>arch</replaceable></literal> part of it is substituted by the
-<emphasis role="strong">package architecture</emphasis>.
-<footnote><para>
-The <emphasis role="strong">package name</emphasis>, <emphasis
-role="strong">upstream version</emphasis>, and <emphasis role="strong">Debian
-revision</emphasis> must be adjusted to comply with the Debian Policy Manual:
+In the file names above, replace
+the <literal><replaceable>package</replaceable></literal> part with the <emphasis role="strong">package name</emphasis>,
+the <literal><replaceable>version</replaceable></literal> part with the <emphasis role="strong">upstream version</emphasis>,
+the <literal><replaceable>revision</replaceable></literal> part with the <emphasis role="strong">Debian revision</emphasis>,
+and the <literal><replaceable>arch</replaceable></literal> part with the <emphasis role="strong">package architecture</emphasis>,
+as defined in the Debian Policy Manual.
+<footnote> <para> See
<ulink url="&policy-source;">5.6.1 Source</ulink>,
<ulink url="&policy-package;">5.6.7 Package</ulink>, and
<ulink url="&policy-version;">5.6.12 Version</ulink>.
@@ -649,13 +646,13 @@
and is automatically assigned by the package build process.</para></footnote>
</para>
<para>
-If you are making a Debian specific package without an upstream program instead,
-typical workflow of the Debian package building is simpler.
+If instead you are making a Debian-specific package with no upstream, the
+typical workflow of Debian package building is simpler.
</para>
<itemizedlist>
<listitem>
<para>
-We create a native Debian source package in the <literal>3.0 (native)</literal>
+Create a native Debian source package in the <literal>3.0 (native)</literal>
format using a single compressed tar file in which all files are included.
</para>
<itemizedlist>
@@ -665,7 +662,7 @@
</listitem>
<listitem>
<para>
-We build Debian binary packages from the native Debian source package.
+Build Debian binary packages from the native Debian source package.
</para>
<itemizedlist>
<listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>
@@ -673,7 +670,7 @@
</listitem>
</itemizedlist>
<para>
-In the following, each step of this is explained with detailed examples.
+Each step of this outline is explained with detailed examples in later sections.
</para>
</section>
<section id="choose"><title>Choose your program</title>
@@ -867,13 +864,12 @@
<listitem><para>Simple packages</para>
<itemizedlist>
<listitem><para>single binary package, arch = all (collection of data such as wallpaper graphics)</para></listitem>
- <listitem><para>single binary package, arch = all (executables written in the POSIX shell language)</para></listitem>
- <listitem><para>single binary package, arch = all (executables written in interpreter languages)</para></listitem>
+ <listitem><para>single binary package, arch = all (executables written in an interpreted language such as POSIX shell)</para></listitem>
</itemizedlist>
</listitem>
<listitem><para>Intermediate complexity packages</para>
<itemizedlist>
- <listitem><para>single binary package, arch = any (executables written in compiler languages such as C and C++)</para></listitem>
+ <listitem><para>single binary package, arch = any (executables written in compiled languages such as C and C++)</para></listitem>
<listitem><para>multiple binary packages, arch = any + all (packages for executables + documentation)</para></listitem>
<listitem><para>upstream source in a format other than <filename>tar.gz</filename> or <filename>tar.bz2</filename></para></listitem>
<listitem><para>upstream source containing undistributable contents</para></listitem>
@@ -883,7 +879,7 @@
<itemizedlist>
<listitem><para>interpreter module package used by other packages</para></listitem>
<listitem><para>generic library package used by other packages</para></listitem>
- <listitem><para>multiple binary packages containing a library package</para></listitem>
+ <listitem><para>multiple binary packages including a library package</para></listitem>
<listitem><para>source package with multiple upstream sources</para></listitem>
<listitem><para>kernel module packages</para></listitem>
<listitem><para>kernel patch packages</para></listitem>
@@ -893,8 +889,8 @@
</itemizedlist>
<para>
Packaging high complexity packages is not too hard, but it requires a bit more
-knowledge. You should seek specific guidances for every complexity. For
-example, some interpreter languages have their policy.
+knowledge. You should seek specific guidance for every complex feature. For
+example, some languages have their own sub-policy documents:
</para>
<itemizedlist>
<listitem><para><ulink url="&policy-perl;">Perl policy</ulink></para></listitem>
@@ -902,14 +898,14 @@
<listitem><para><ulink url="&policy-java;">Java policy</ulink></para></listitem>
</itemizedlist>
<para>
-There is another old Latin saying: <emphasis>Fabricando fit fabe</emphasis>
-(Practice makes perfect). It is <emphasis>highly</emphasis> recommended to
-practice and experiment all the steps of Debian packaging with simple packages
+There is another old Latin saying: <emphasis>fabricando fit faber</emphasis>
+(practice makes perfect). It is <emphasis>highly</emphasis> recommended to
+practice and experiment with all the steps of Debian packaging with simple packages
while reading this tutorial. A trivial upstream tarball
-<filename>hello-sh-1.0.tar.gz</filename> created with the following may offer
-you a good starting point.<footnote><para>Do not worry about missing
+<filename>hello-sh-1.0.tar.gz</filename> created as followings may offer
+a good starting point.<footnote><para>Do not worry about the missing
<filename>Makefile</filename>. You can install the <command>hello</command>
-command by simply using <command>debhelper</command> as in
+command by simply using <command>debhelper</command> as in
<xref linkend="install"/>, or by modifying the upstream source to add a new
<filename>Makefile</filename> with the <literal>install</literal> target as in
<xref linkend="modify"/>.</para></footnote>
@@ -1104,9 +1100,8 @@
<section id="namever"><title>Package name and version</title>
<para>
If the upstream source comes as <filename>gentoo-0.9.12.tar.gz</filename>, you can
-consider
-<emphasis role="strong">package name</emphasis> to be <literal>gentoo</literal> and
-<emphasis role="strong">upstream version</emphasis> to be <literal>0.9.12</literal>.
+take <literal>gentoo</literal> as the (source) <emphasis role="strong">package name</emphasis>
+and <literal>0.9.12</literal> as the <emphasis role="strong">upstream version</emphasis>.
These are used in the <filename>debian/changelog</filename> file described later in
<xref linkend="changelog"/>, too.
</para>
@@ -1114,7 +1109,7 @@
Although this simple approach works most of the times, you may need to adjust
<emphasis role="strong">package name</emphasis> and
<emphasis role="strong">upstream version</emphasis> by renaming the upstream
-source to follow the Debian Policy and the existing convention.
+source to follow Debian Policy and existing convention.
</para>
<para>
You must choose the <emphasis role="strong">package name</emphasis>
@@ -1123,7 +1118,7 @@
(<literal>-</literal>) signs, and periods (<literal>.</literal>). It must be
at least two characters long, must start with an alphanumeric character, and
must not be the same as existing ones.
-It is good idea to keep its length within 30 characters.
+It is a good idea to keep its length within 30 characters.
<footnote><para>The default package name field length of <command>aptitude</command> is 30. For more than 90% of packages, the package name is less than 24 characters.</para></footnote>
</para>
<!--
@@ -1139,9 +1134,8 @@
Default aptitude setting display up to 30 chars (98.3%).
-->
<para>
-If upstream source uses generic words such as <literal>test-suite</literal> as
-its name, it is good idea to rename it not to contaminate name space for the
-package name and to identify its contents explicitly.
+If upstream uses some generic term such as <literal>test-suite</literal> for
+its name, it is a good idea to rename it to identify its contents explicitly and avoid namespace pollution.
<footnote><para>If you follow the
<ulink url="&devref-newpackage;">Debian Developer's Reference 5.1. "New packages"</ulink>,
the ITP process will usually catch this kind of issues.</para></footnote>
@@ -1179,15 +1173,15 @@
90chars as max for file name of binary debs (package+up+deb+arch+.deb)
-->
<para>
-If the upstream software does not use normal version system like
+If upstream does not use a normal versioning scheme such as
<literal>2.30.32</literal> but uses some kind of date such as
-<literal>09Oct23</literal>, a random codename string or a VCS hash value as a part
-of version, make sure to remove them from the
+<literal>09Oct23</literal>, a random codename string, or a VCS hash value as part
+of the version, make sure to remove them from the
<emphasis role="strong">upstream version</emphasis>. Such information can be
recorded in the <filename>debian/changelog</filename> file. If you need to
invent a version string, use the <literal>YYYYMMDD</literal> format such as
<literal>20110429</literal> as upstream version. This ensures that
-<command>dpkg</command> properly sees later versions as upgrades.
+<command>dpkg</command> interprets later versions correctly as upgrades.
</para>
<para>
Version strings <footnote><para>Version strings may be
@@ -1200,20 +1194,23 @@
See <xref linkend="newrevision"/> for how the
<emphasis role="strong">Debian revision</emphasis> is incremented.
</para></footnote>
-can be compared with <citerefentry> <refentrytitle>dpkg</refentrytitle> <manvolnum>1</manvolnum> </citerefentry> as the following.
+can be compared using <citerefentry>
+<refentrytitle>dpkg</refentrytitle> <manvolnum>1</manvolnum> </citerefentry> as follows.
</para>
<screen>
$ dpkg --compare-versions <replaceable>ver1</replaceable> <replaceable>op</replaceable> <replaceable>ver2</replaceable>
</screen>
<para>
-The version comparison rule can be summarized as the following.
+The version comparison rule can be summarized as:
</para>
<itemizedlist>
-<listitem><para>The strings are compared from the head to the tail.</para></listitem>
-<listitem><para>Alphabets are larger than numbers.</para></listitem>
-<listitem><para>Numbers are compared as the integer.</para></listitem>
-<listitem><para>Alphabets are compared in the ASCII code order.</para></listitem>
-<listitem><para>There are some special rules for periods (<literal>.</literal>), plus (<literal>+</literal>) and tildes (<literal>~</literal>) as the followings.</para>
+<listitem><para>Strings are compared from the head to the tail.</para></listitem>
+<listitem><para>Letters are larger than digits.</para></listitem>
+<listitem><para>Numbers are compared as integers.</para></listitem>
+<listitem><para>Letters are compared in ASCII code order.</para></listitem>
+<listitem><para>There are special rules for period
+(<literal>.</literal>), plus (<literal>+</literal>), and tilde
+(<literal>~</literal>) characters, as follows.</para>
<para>
<literal>0.0</literal> <
<literal>0.5</literal> <
@@ -1230,7 +1227,7 @@
</listitem>
</itemizedlist>
<para>
-One of the tricky case happens when the upstream releases
+One tricky case occurs when upstream releases
<filename>gentoo-0.9.12-ReleaseCandidate-99.tar.gz</filename> as the
pre-release of <filename>gentoo-0.9.12.tar.gz</filename>. You need to make
sure that the upgrade works properly by renaming the upstream source to
@@ -1353,16 +1350,17 @@
<para>
Please note that the source file does not need to contain any build system
discussed in <xref linkend="simplemake"/> and <xref linkend="portable"/>. It
-could be just a collection of graphics data etc. Installation of files may be
-enabled by <systemitem role="package">debhelper</systemitem> configuration
-files such as <filename>debian/install</filename> (see
-<xref linkend="install"/>) only.
+could be just a collection of graphical data etc. Installation of files may be
+carried out using only <systemitem role="package">debhelper</systemitem> configuration
+files such as <filename>debian/install</filename> (see
+<xref linkend="install"/>).
</para>
</section>
<section id="native-dh-make"><title>Initial native Debian package</title>
<para>
-Debian native packages are simpler to manage if they contain source files you
-manage only for Debian, possibly only for local uses. If you have source
+If a package contains source files you are only maintaining for Debian,
+possibly only for local use, it may be simpler to create it as a Debian
+native package. If you have source
files in <filename>~/mypackage-1.0</filename>, you can create an initial native
Debian package for it by issuing the <command>dh_make</command> command as
follows.
@@ -4009,15 +4007,15 @@
<ulink url="&keycreate;">Creating a new GPG key</ulink> and
<ulink url="&keysigning; ">Debian Wiki on Keysigning</ulink>.
</para></footnote>
-If you are building Debian packages only for your local use, you can skip
+If you are building Debian packages only for your own local use, you can skip
promptings for the GPG signatures on the <filename>.dsc</filename> file and the
-<filename>.changes</filename> file as:
+<filename>.changes</filename> file like this:
</para>
<screen>
$ dpkg-buildpackage -us -uc
</screen>
<para>
-For the non-native Debian package, e.g.,
+For a non-native Debian package, e.g.,
<systemitem role="package">gentoo</systemitem>, you will see the following
files in the parent directory (<filename>~/gentoo</filename>) after building
packages:
@@ -4105,7 +4103,7 @@
they'll know the file is corrupt or has been tampered with.
</para>
<para>
-For the native Debian package, e.g.,
+For a native Debian package, e.g.,
<systemitem role="package">mypackage</systemitem>, you will see the following
files in the parent directory after building packages:
</para>
@@ -4115,7 +4113,7 @@
<filename>mypackage_1.0.tar.gz</filename>
</para>
<para>
-This is the source code tarball merely created from the
+This is the source code tarball created from the
<filename>mypackage-1.0</filename> directory by the
<command>dpkg-source</command>. (Its suffix is not <filename>orig.tar.gz</filename>.)
</para>
@@ -4263,9 +4261,9 @@
$ debuild
</screen>
<para>
-Here, if you are building Debian packages only for your local use, you can skip
+Here, if you are building Debian packages only for your own local use, you can skip
promptings for the GPG signatures on the <filename>.dsc</filename> file and the
-<filename>.changes</filename> file as:
+<filename>.changes</filename> file like this:
</para>
<screen>
$ debuild -us -uc
@@ -4859,7 +4857,7 @@
$ debuild -sa
</screen>
<para>
-For the <command>debuild</command> command:
+For the <command>pdebuild</command> command:
</para>
<screen>
$ pdebuild --debbuildopts -sa
@@ -4891,7 +4889,7 @@
$ debuild -v<replaceable>1.2</replaceable>
</screen>
<para>
-For the <command>debuild</command> command:
+For the <command>pdebuild</command> command:
</para>
<screen>
$ pdebuild --debbuildopts "-v<replaceable>1.2</replaceable>"
@@ -5014,11 +5012,11 @@
</listitem>
</itemizedlist>
<para>
-One of the tricky case happens when you make a local package to experiment with
-the packaging before uploading to the official archive with the normal version,
+One tricky case can occur when you make a local package to experiment with
+the packaging before uploading the normal version to the official archive,
e.g.,
<literal><replaceable>1.0.1</replaceable>-<replaceable>1</replaceable></literal>.
-For the smoother upgrade, it is a good idea to create a
+For smoother upgrades, it is a good idea to create a
<filename>changelog</filename> entry with a version string as
<literal><replaceable>1.0.1</replaceable>-<replaceable>1~rc1</replaceable></literal>.
You may unclutter <filename>changelog</filename>
Reply to: