Re: debian-faq: Patch2 to improve wording or meaning, remove superfluous words, consistentency ...
Holger Wansing wrote:
> I would appreciate review and comments.
[...]
> Index: faqinfo.sgml
> ===================================================================
> --- faqinfo.sgml (Revision 10939)
> +++ faqinfo.sgml (Arbeitskopie)
> @@ -12,14 +12,14 @@
>
> <p>Parts of the information came from:
> <list>
> - <item>The Debian-1.1 release announcement, by <url name="Bruce Perens" id="http://www.perens.com/";>.
> - <item>The Linux FAQ, by <url name="Ian Jackson" id="http://www.chiark.greenend.org.uk/~ijackson/";>.
> + <item>The Debian-1.1 release announcement, by <url name="Bruce Perens" id="http://www.perens.com/";>,
> + <item>The Linux FAQ, by <url name="Ian Jackson" id="http://www.chiark.greenend.org.uk/~ijackson/";>,
^
I'm not sure about the item-initial capitalisation here - if we're
treating "The Linux FAQ" as a title, shouldn't it be in quotes or
something?
> <item><url name="Debian Mailing Lists Archives" id="http://lists.debian.org/";>,
> <item>the dpkg programmers' manual and the Debian Policy manual
> - (see <ref id="debiandocs">)
> + (see <ref id="debiandocs">),
> <item>many developers, volunteers, and beta testers, and
> - <item>the flaky memories of its authors. :-)
> - <item>Kamaraju Kusumanchi's <url name="Choosing a Debian distribution FAQ" id="http://people.cornell.edu/pages/kk288/debian_choosing_distribution.html";>, who graciously made it GPL so I could include it as a new chapter (see <ref id="choosing">)
> + <item>the flaky memories of its authors :-)
> + <item>and Kamaraju Kusumanchi's <url name="Choosing a Debian distribution FAQ" id="http://people.cornell.edu/pages/kk288/debian_choosing_distribution.html";>, who graciously made it GPL so I could include it as a new chapter (see <ref id="choosing">).
> </list>
Grammar problems and a dead link. It needs to be something like
<item>and "Choosing a Debian distribution FAQ", which Kamaraju
Kusumanchi graciously released under the GPL so I could include
it as a new chapter (see <ref id="choosing">).
> <p>The authors would like to thank all those who helped make this
> Index: ftparchives.sgml
> ===================================================================
> --- ftparchives.sgml (Revision 10939)
> +++ ftparchives.sgml (Arbeitskopie)
> @@ -61,14 +61,14 @@
> <item><em>sarge</em> was the sergeant of the Green Plastic Army Men,
> <item><em>etch</em> was the toy blackboard (Etch-a-Sketch),
(Do people think of etch-a-sketches as blackboards? For a start,
isn't it more of a whiteboard?)
> <item><em>lenny</em> was the toy binoculars,
> - <item><em>squeeze</em> was the name for the three-eyed aliens,
> - <item><em>wheezy</em> was the name of the rubber toy penguin with
> + <item><em>squeeze</em> was the three-eyed aliens,
You could I suppose say that "Squeeze" *referred to* the aliens, but I
think the simplest approach is to keep "the name for/of" in this one
case.
(Actually I'm not sure the name "Squeeze" was ever mentioned in the
original movie, though it might be in the merchandising or the
screenplay or something. And technically the names used in Toy Story
all obeyed the standard capitalisation rules of English orthography!)
> + <item><em>wheezy</em> was the rubber toy penguin with
> a red bow tie,
> - <item><em>jessie</em> was the name of the yodelling cowgirl,
> - <item><em>stretch</em> was the name of the toy rubber octopus with suckers on her eight long arms.
> + <item><em>jessie</em> was the yodelling cowgirl,
^
If we're standardising to en_US, isn't that usually "yodeling" (cf.
"traveling")?
[...]
> Index: pkg_basics.sgml
> ===================================================================
> --- pkg_basics.sgml (Revision 10939)
> +++ pkg_basics.sgml (Arbeitskopie)
> @@ -180,7 +180,7 @@
> script?
>
> <p>These files are executable scripts which are automatically run before
> -or after a package is installed. Along with a file named <tt>control</tt>,
> +or after a package is installed or removed. Along with a file named <tt>control</tt>,
> all of these files are part of the "control" section of a Debian archive file.
>
> <p>The individual files are:
> @@ -365,8 +365,8 @@
>
> <p>Their meanings are:
> <list>
> - <item>unknown - the user has never indicated whether he wants the package
> - <item>install - the user wants the package installed or upgraded
> + <item>unknown - the user has never indicated whether he wants the package.
^^
Women are allowed to use Debian. This one's a bit tricky, but I
suppose you could say:
<item>unknown - the user has never indicated whether the package is wanted.
I suspect there are plenty of similar cases in the rest of the document.
> + <item>install - the user wants the package installed or upgraded.
> <item>remove - the user wants the package removed, but does not want to
> remove any existing configuration files.
> <item>purge - the user wants the package to be removed completely,
[...]
> Index: pkgtools.sgml
> ===================================================================
> --- pkgtools.sgml (Revision 10939)
> +++ pkgtools.sgml (Arbeitskopie)
> @@ -64,7 +64,7 @@
>
> <sect1 id="apt-get">APT
>
> -<p>APT is the <em>Advanced Package Tool</em> is the advanced interface to the
> +<p>APT is the <em>Advanced Package Tool</em>, an advanced interface to the
> Debian packaging system and provides the <prgn/apt-get/ program.
^
This needs a comma to indicate that "provides" is grammatically
parallel to "is". Alternatively you could replace "and" with "which".
> It features complete installation ordering, multiple source capability and
> several other unique features, see the User's Guide in
This stuff about "complete installation ordering" used to be in the
apt package description too, but got removed (see BTS #458029 - I for
one never understood what it was supposed to mean...)
[...]
> @@ -409,10 +409,10 @@
> a system containing the <package/dpkg/ package), since it calls the program
> <tt>dpkg-deb</tt> to parse the debian package file into its component records.
>
> -<p>For example, to split a big .deb file into N parts,
> +<p>For example, to split a big .deb file into N parts and join them together on an another machine,
> <list>
> <item>Execute the command <tt>dpkg-split --split foo.deb</tt>.
> - This will produce N files each of approximately 460 KBytes long in the
> + This will produce N files each of approximately 460 KBytes file size in the
> current directory.
> <item>Copy those N files to floppy disks.
> <item>Copy the contents of the floppy disks onto the hard disk of your
Are those kilobytes or kibibytes? But never mind that; the whole
topic is cobwebby. Who uses storage media so cramped that a normal
.deb file needs to be chopped up to fit on one?
[...]
> Index: uptodate.sgml
> ===================================================================
> --- uptodate.sgml (Revision 10939)
> +++ uptodate.sgml (Arbeitskopie)
> @@ -57,7 +57,7 @@
> Answer any questions that might come up, and your system will be upgraded.
>
> <p>Note that <prgn/aptitude/ is not the recommended tool for
> -doing upgrades from one &debian; release to another. For upgrades between
> +doing upgrades from one &debian; release to another. Use <prgn/apt-get/ instead. For upgrades between
> releases you should read the <url
> id="http://www.debian.org/releases/stable/releasenotes"; name="Release
> Notes">. This document describes in detail the recommended steps for upgrades
>
> @@ -92,9 +92,8 @@
> be used. The configuration file is <file>/etc/apt/sources.list</file>.
> See also <ref id="dselect">.
(No, don't see dselect!)
[...]
> @@ -202,7 +201,7 @@
>
> <p>Yes. You can use <prgn>cron-apt</prgn>, this tool updates the system at
> regular interval by using a cron job. By default it just updates the package
^ ^^
Yes, this needs to be "at regular intervals". And it should probably
just be "using a cron job" insteado of "by using a cron job". And
there should be a semicolon before "this tool" instead of a comma
splice. And "without installing" below should be "without installing
them".
> -list and downloads new packages without installing.
> +list and downloads new packages, but without installing.
(Again, this whole section may be somewhat stale, since you can get
the same functionality without installing any extra packages just by
activating some variables like "APT::Periodic::Update-Package-Lists"
in your APT configuration.)
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: