[patch] Release Notes: corrections/comments/suggestions
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hello Rob,
While doing the Dutch translation, I have also done a review.
Attached is a patch that fixes some of the minor errors I came across.
In the patch I've also included some comments containing comments and
suggestions on the current version.
All my comments are marked <!-- FJP: -->
One other thing I noticed is that examples are currently indented too much
in the build documents and are sometimes preceded by two white lines
instead of one. Cause is the indentation in the source file.
Also, in the source file currently are used both tabs and spaces for
indentation.
Hope this helps,
Frans
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (GNU/Linux)
iD8DBQFBTwDjgm/Kwh6ICoQRAgR6AJwIDyKAo4IieB7WFkDbkUC4m4zzwQCeOND7
vItrhMbuPBwLvh0cQvnttBI=
=Y/H4
-----END PGP SIGNATURE-----
--- release-notes.en.sgml.orig 2004-09-17 00:02:03.000000000 +0200
+++ release-notes.en.sgml 2004-09-20 16:52:15.000000000 +0200
@@ -81,7 +81,9 @@
<![ %available-2.6 [
<p>On the &arch-title; architecture a 2.6 kernel is also available,
- this has kernel version &kernelversion-2.6;.</p>
+ this has kernel version &kernelversion-2.6;. Note that Debian's 2.6.8
+ kernel packages include the 2.6.8.1 kernel release and selected other
+ patches.</p>
]]>
<sect id="newinst"><heading>What's New in the Installation System?</heading>
@@ -100,7 +102,7 @@
<p>For full details of the new Debian installation system, users
are advised to read the Debian installation guide included on the
- first CD or at <url id="&url-install-manual;"></p>
+ first CD or at <url id="&url-install-manual;">.</p>
<![ %i386 [
@@ -126,12 +128,18 @@
disk image.<p></item>
</taglist>
-
+<!-- FJP: I feel the info about floppies should be removed from this table as
+ floppies are no longer the most used installation method. -->
+
<p>The kernel config files for these flavors can be found in their
respective directories in a file named 'kernel-config'.</p>
]]>
+<!-- FJP: Maybe a short description of available installation methods could be
+ added here: floppy, CD (netinst/business-card/full set), netboot,
+ hd-media, USB-stick. -->
+
<![ %available-2.6 [
<p>An installer using a 2.6 based kernel is available for
&arch-title;. For more details on how to use it please consult the
@@ -175,7 +183,7 @@
</example></p>
- <p>or on the Internet at: <url id="&url-install-manual;"></p>
+ <p>or on the Internet at: <url id="&url-install-manual;">.</p>
<p>The old &debian; installation system called
<prgn>boot-floppies</prgn> has been replaced by a new componentized and
@@ -201,7 +209,8 @@
<sect1 id="syntax"><heading>Important program syntax changes</heading>
<p>Debian attempts to avoid changing upstream packages, therefore
- changes in the original packages will be present in &debian;</p>
+ changes in the original packages will be present in &debian;.</p>
+<!-- FJP: The previous para does not seem logical; should maybe be rewritten -->
<p><em>No changes yet reported.</em></p>
@@ -222,7 +231,7 @@
<tt>dpkg --get-selections \*</tt>.</p>
<p>It's wise to inform all users in advance of any upgrades you're
- planning, although users accessing your system via ssh (at least)
+ planning, although users accessing your system via SSH (at least)
shouldn't notice much during the upgrade, and may want to continue
working. If you wish to take extra precautions, back up or unmount
user's partitions (<file>/home</file>) before upgrading. A reboot
@@ -238,15 +247,19 @@
because each of those services may well be terminated during the
upgrade, which can result in an <em/inaccessible/ system that is
only half-upgraded.</p>
+<!-- FJP: Not only xdm, but also gdm, kdm, ...
+ Maybe s/by <prgn/xdm//by display managers like <prgn/xdm/, <prgn/gdm/ or <prgn/kdm// -->
<sect1><heading>Disabling APT Pinning</heading>
<p>If you have configured APT to install certain packages from a
- distribution other than stable (e.g from testing) you may have to
+ distribution other than stable (e.g from testing), you may have to
change your APT pinning configuration (stored in
- <file>/etc/apt/preferences</file> to allow the upgrade of packages to
+ <file>/etc/apt/preferences</file>) to allow the upgrade of packages to
the versions in the new stable release. Further information on APT
pinning can be found in <manref name="apt_preferences" section="5">.</p>
+<!-- FJP: Couldn't the advise to hold such packages prevent the upgrade of e.g.
+ libc6 if the package depends on the old version! -->
</sect1>
@@ -295,7 +308,7 @@
rename it or put an epoch in the version, you must put it on hold
to prevent it from being upgraded. The `hold' package state can be
changed either by using <prgn/dselect/ (in the Select menu, use
- the `H' and `G' keys to hold and unhold, respectively), or by
+ the `=' key to toggle the `hold' state), or by
editing the file produced by
<example>
@@ -316,7 +329,7 @@
<sect1><heading>Special Considerations for SSH Users</heading>
<p>The commercial SSH located in the <package/ssh/ package before
- release 2.2 or in the <package/ssh-nonfree/ in release 2.2 has
+ release 2.2 or in the <package/ssh-nonfree/ package in release 2.2 has
been replaced by the DFSG free <package/ssh/ package (OpenSSH) in
this release. The commercial SSH collection is no longer present.
The <package/ssh/ package includes a Debconf question which will
@@ -343,6 +356,8 @@
method with <prgn/dselect/, as described here. The built-in
dependency analysis enables smooth upgrades and easy
installations.</p>
+<!-- FJP: Is dselect still the preferred method? A little bit further down in
+ 'Upgrading packages' aptitude is preferred! -->
<p>You should <em/not/ be doing any major package upgrades with
access methods other than <prgn/apt/ in <prgn/dselect/, because
@@ -375,10 +390,19 @@
<file>/etc/apt/sources.list</file> to use other mirrors,
preferably a mirror that is network-wise closest to you.</p>
- <p>Otherwise, Debian HTTP or FTP mirror addresses can be found at
+<!-- FJP: Why is 'default configuration' relevant here? We are talking about
+ upgrading existing installations; we really have no idea what
+ apt-sources users will have set up here (maybe just a Woody CD-set).
+ Note: D-I sets the default configuration to a mirror based on
+ the selected country and not the 'main' servers. -->
+
+ <p>Debian HTTP or FTP mirror addresses can be found at
<url id="&url-debian-mirrors;"> (look at the "Full list of
- mirrors" section). HTTP mirrors are generally speedier than ftp
+ mirrors" section). HTTP mirrors are generally speedier than FTP
mirrors.</p>
+<!-- FJP: 'Otherwise' does not refer back to anything here, so I deleted it
+ (unless the intention was to refer to local intr_a_net HTTP
+ servers in the previous para). -->
<p>For example, suppose your closest Debian mirror is
<tt>&url-debian-mirror-eg;/</tt>. When inspecting that mirror
@@ -410,7 +434,7 @@
(<tt/#/) in front of them.</p>
<p>Any package needed for installation that is fetched from the
- network is stored in the <file>/var/cache/apt/archives</file>
+ network is stored in <file>/var/cache/apt/archives</file>
(and the <file>partial/</file> subdirectory, during download), so
you must make sure you have enough space before attempting to
start the installation. With a reasonably extended Debian
@@ -453,8 +477,13 @@
<sect1 id="cdroms"><heading>Adding APT CD-ROM Sources</heading>
+<!-- FJP: Are these instructions also valid for adding DVD's? -->
+
<p>See above if you need to first install the latest version of
<package/apt/ and <package/dpkg/ packages, as described above.</p>
+<!-- FJP: See above [...], as described above is a bit double.
+ Also, I don't think the need to update the package tools and how
+ to do that has been descibed 'above' yet. -->
<p>If you want to use CDs <em/only/, comment out the existing
"<tt/deb/" lines in <file>/etc/apt/sources.list</file> by placing
@@ -463,7 +492,7 @@
<p>Make sure there is a line in <file>/etc/fstab</file> that
enables mounting your CD-ROM drive at the <file>/cdrom</file>
mount point (the exact <file>/cdrom</file> mount point is required
- for <prgn/apt-cdrom/).For example, if <file>/dev/hdc</file> is
+ for <prgn/apt-cdrom/). For example, if <file>/dev/hdc</file> is
your CD-ROM drive, <file>/etc/fstab</file> should contain a line
like:
@@ -514,7 +543,7 @@
<p>Next ensure that the APT source entries (in
<file>/etc/apt/sources.list</file>) refer to the <tt>'stable'</tt>
- distribution and does not refer to it by its codename (e.g.
+ distribution and do not refer to it by its codename (e.g.
<tt>&oldreleasename;</tt>).
<p>It is strongly recommended that you use the
@@ -542,6 +571,8 @@
<p>Provided that you have a working APT configuration as described
above this will install the &oldreleasename; version of
<prgn>aptitude</prgn>.</p>
+<!-- FJP: Will it really? Haven't we have just instructed users to point
+ everything to the new release? -->
<p>First <prgn>aptitude</prgn> needs to fetch a list of new and
updated packages for the new release. This is done by executing:</p>
@@ -551,7 +582,9 @@
</example></p>
<p>Once <prgn>aptitude</prgn> has information on all the available
- packages the system is almost ready to be fully upgraded.</p>
+ packages, the system is almost ready to be fully upgraded.</p>
+<!-- FJP: Why 'almost'? The next command will perform the upgrade.
+ 'Almost' implies the user needs to do something else first... -->
<p><example>
aptitude -f --with-suggests --with-recommends dist-upgrade
@@ -647,7 +680,9 @@
split in that release; go back and read <ref id="renames"> and
<ref id="splits"> to see the list of packages split in this
release.</p>
-
+<!-- FJP: Why should the Release Notes of the previous release be consulted? -->
+<!-- FJP: 'go back and read'? This info comes later in this doc. -->
+
<p>Read
<file>/usr/share/doc/xfree86-common/README.Debian-upgrade</file> for
more info on the upgrade of the X window system packages. This is
@@ -672,6 +707,7 @@
<p>To upgrade your kernel you must first choose the kernel most
apropriate for your subarchitecture. A list of kernels available for
you to install can be found with:
+<!-- FJP: s/subarchitecture/subarchitecture and processor/ ??? -->
<example>
@@ -705,7 +741,7 @@
including the Debian Guide, Debian New Maintainers Guide, and Debian
FAQ are available, and many more. For full details of the resources
available see the DDP website at <url
- id="&url-ddp;"></p>
+ id="&url-ddp;">.</p>
<p>Documentation for individual packages is installed into
<file>/usr/share/doc/<var>package</var></file>, this may include
@@ -726,7 +762,7 @@
<sect1 id="lists">
<heading>Mailing lists</heading>
<p>The mailing lists of most interest to Debian users are the
- debian-user (English) and other debian-user-<var/language/ lists
+ debian-user list (English) and other debian-user-<var/language/ lists
(for other languages). For information on these lists and details of
how to subscribe see <url id="&url-debian-list-archives;">. Please
check the archives for answers to your question prior to posting and
@@ -758,6 +794,12 @@
information on reported bugs at our own Bug Tracking System (BTS)
browseable at <url id="&url-bts;" name="bugs.debian.org">, this is
consistent with Debian's open development.</p>
+<!-- FJP: I propose to replace the last sentence by:
+ Consistent with Debian's 'open development' philosophy and as a
+ service to our users, we provide all the information on reported bugs
+ at our own Bug Tracking System (BTS). The BTS is browseable at
+ <url id="&url-bts;" name="bugs.debian.org">.
+-->
<p>If you find a bug in the distribution or in packaged software
that is part of it, please report it so that it can be properly
@@ -766,15 +808,15 @@
can get in contact with submitters should they need more
information.</p>
- <p>You can submit a bug report either using the programs
- <package>reportbug</package> and <package>bug</package>
- (available in their apropriate packages) or manually using email.
+ <p>You can submit a bug report using the program
+ <package>reportbug</package> or manually using email.
You can read more about the Bug Tracking System and how to use it by
reading the reference cards (available at
<file>/usr/share/doc/debian</file> in any installed system) or
online at the <url id="&url-bts;" name="Bug Tracking
System">.</p>
-
+<!-- FJP: The 'bug' program and package are obsolete. -->
+
</sect>
<sect id="contributing">
@@ -878,6 +920,7 @@
None reported yet!
</example> </p>
</sect>
+
<sect id="removed"><heading>Removed packages</heading>
<sect1 id="nomaintainer">
<heading>Packages removed because of no maintainer</heading>
@@ -891,6 +934,7 @@
<p>The alternatives field lists any packages that might replace
the removed package.</p>
+<!-- FJP: Which 'alternatives field'? -->
<p><example>
aethera (152941)
@@ -1148,6 +1192,7 @@
zebra (208786)
</example></p>
</sect1>
+
<sect1 id="no-upstream">
<heading>Packages lacking upstream</heading>
<p>These are packages which have been removed because they lack an
@@ -1159,6 +1204,7 @@
<p>The alternatives field lists any packages that might replace
the removed package.</p>
+<!-- FJP: Which 'alternatives field'? -->
<p><example>
admwebuser (182238)
@@ -1300,6 +1346,7 @@
</example></p>
</sect1>
<sect1 id="removed-other">
+
<heading>Packages removed for other reasons</heading>
<p>The reason for the removal of the package is listed below the
name of the package. The number associated with the bug is
@@ -1307,9 +1354,11 @@
the package was removed. To use this number visit the <url
id="&url-bts;" name="Bug Tracking System"> and do a query based on
the bugnumber.</p>
+<!-- FJP: The 'reason for removal' seems to be missing in the list. -->
<p>The alternatives field lists any packages that might replace
the removed package.</p>
+<!-- FJP: Which 'alternatives field'? -->
<p><example>
Reply to: