debian-faq: Patch2 to improve wording or meaning, remove superfluous words, consistentency ...

On Tuesday 29 March 2016, at 19:20 +0200, Holger Wansing wrote:

Hi,

===================================================================
--- ftparchives.sgml (Revision 10939)
+++ ftparchives.sgml (Arbeitskopie)
@@ -61,14 +61,14 @@
<item>sarge was the sergeant of the Green Plastic Army Men,
<item>etch was the toy blackboard (Etch-a-Sketch),
<item>lenny was the toy binoculars,
- <item>squeeze was the name for the three-eyed aliens,
- <item>wheezy was the name of the rubber toy penguin with
+ <item>squeeze was the three-eyed aliens,

I think this should be either "squeeze was the name of the three-eyed
aliens" or "squeeze were the three-eyed aliens" , but I think the first
one sounds better.

Index: pkgtools.sgml
===================================================================
--- pkgtools.sgml (Revision 10939)
+++ pkgtools.sgml (Arbeitskopie)
@@ -64,7 +64,7 @@
<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.

The part "file size" sounds strange to me (not a English native
speaker). I would simply say "of approximately 460 KBytes", or "N files
each with a file size of approximately 460 KByte" (but it is maybe an
unnecessary complication) or "each with an approximate size of 460 KBytes".

Index: uptodate.sgml
===================================================================
--- uptodate.sgml (Revision 10939)
+++ uptodate.sgml (Arbeitskopie)
@@ -57,7 +57,7 @@
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
-list and downloads new packages without installing.
+list and downloads new packages, but without installing.

I think it is more common to use the plural "intervals" in the phrase
"at regular intervals". Also maybe adding "them" as in "but without installing them."?

Ciao,

beatrice

Holger Wansing

2016-03-30 18:40:02 UTC

Hi,

Post by Beatrice Torracca
Hi,

I think this should be either "squeeze was the name of the three-eyed
aliens" or "squeeze were the three-eyed aliens" , but I think the first
one sounds better.

Yes, also proposed by Justin.

Post by Beatrice Torracca

ok: N files each with a file size of approximately 460 KByte

Post by Beatrice Torracca

I think it is more common to use the plural "intervals" in the phrase
"at regular intervals". Also maybe adding "them" as in "but without installing them."?

Yes.

Thanks
Holger

Justin B Rye

2016-03-29 19:20:02 UTC

Post by Holger Wansing
I would appreciate review and comments.

[...]

Post by Holger Wansing
Index: faqinfo.sgml
===================================================================
--- faqinfo.sgml (Revision 10939)
+++ faqinfo.sgml (Arbeitskopie)
@@ -12,14 +12,14 @@
<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?

Post by Holger Wansing
<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">).

Post by Holger Wansing
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>sarge was the sergeant of the Green Plastic Army Men,
<item>etch 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?)

Post by Holger Wansing
<item>lenny was the toy binoculars,
- <item>squeeze was the name for the three-eyed aliens,
- <item>wheezy was the name of the rubber toy penguin with
+ <item>squeeze 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!)

Post by Holger Wansing
+ <item>wheezy was the rubber toy penguin with
a red bow tie,
- <item>jessie was the name of the yodelling cowgirl,
- <item>stretch was the name of the toy rubber octopus with suckers on her eight long arms.
+ <item>jessie was the yodelling cowgirl,

^
If we're standardising to en_US, isn't that usually "yodeling" (cf.
"traveling")?

[...]

Post by Holger Wansing
Index: pkg_basics.sgml
===================================================================
--- pkg_basics.sgml (Revision 10939)
+++ pkg_basics.sgml (Arbeitskopie)
@@ -180,7 +180,7 @@
script?
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.
@@ -365,8 +365,8 @@
<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.

Post by Holger Wansing
+ <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,

[...]

^
This needs a comma to indicate that "provides" is grammatically
parallel to "is". Alternatively you could replace "and" with "which".

Post by Holger Wansing
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...)

[...]

Post by Holger Wansing
@@ -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.
-For example, to split a big .deb file into N parts,
+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?

[...]

Post by Holger Wansing
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.
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!)

[...]

Post by Holger Wansing
@@ -202,7 +201,7 @@
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".

Post by Holger Wansing
-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

Holger Wansing

2016-03-30 18:30:02 UTC

Hi Justin,
[...]

Post by Holger Wansing
<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?

I don't see the globally strategy in this document, to place titles inside
of quotes.
So changing to such strategy would require most probably many changes...

[...]

Post by Holger Wansing
<item>sarge was the sergeant of the Green Plastic Army Men,
<item>etch 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?)

I personally have no preference here (german speaker).
What would you suggest?

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!)

More than that: what would you propose (since someone told me, Squeeze
could be seen as more than one person [three-eyed] ):

<item>squeeze was the name of the three-eyed alien
<item>squeeze was the name of the three-eyed aliens

I personally would use alien

^
If we're standardising to en_US, isn't that usually "yodeling" (cf.
"traveling")?

Changed to yodeling

(No, don't see dselect!)

I will note that for further discussion...

For the rest I followed your suggestions.

Thanks
Holger

Justin B Rye

2016-03-30 21:20:01 UTC

Post by Holger Wansing
+ <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?

I don't see the globally strategy in this document, to place titles inside
of quotes.
So changing to such strategy would require most probably many changes...

What I was really trying to say is that I don't think it *is* a title.
"The Linux FAQ" is more like a plain description; if this FAQ has a
title, it's "Linux FAQ", as in the URL of its current incarnation:
http://www.tldp.org/FAQ/Linux-FAQ/
And if TLDP wasn't willing to include articles in titles where
appropriate, it would be called LDP! So I'd suggest:

<item>the Linux FAQ, by <url name="Ian Jackson" id="http://www.chiark.greenend.org.uk/~ijackson/">,
or indeed:
<item>the original Linux FAQ, by <url name="Ian Jackson" id="http://www.chiark.greenend.org.uk/~ijackson/">,

Post by Holger Wansing
<item>sarge was the sergeant of the Green Plastic Army Men,
<item>etch 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?)

I personally have no preference here (german speaker).
What would you suggest?

People trying to describe what an Etch-a-Sketch is usually seem to
call it something like a "magic art pad". Maybe it doesn't matter as
long as we've got the actual brandname in there, but I would suggest:

<item>etch was the toy whiteboard (Etch-a-Sketch),

Post by Holger Wansing
+ <item>squeeze 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!)

More than that: what would you propose (since someone told me, Squeeze
<item>squeeze was the name of the three-eyed alien
<item>squeeze was the name of the three-eyed aliens
I personally would use alien

We only ever meet them in groups, but they're instances of the same
toy, so if any of them are named Squeeze they all are (just as both
the spaceman toys in TS2 are Buzz Lightyear). That's a weird enough
situation to make it worth talking in terms of the (one) name of the
(many) aliens:

<item>squeeze was the name of the three-eyed aliens,

(Of course they're *toy* three-eyed aliens, but we don't need to say
that every single time!)

--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package

Holger Wansing

2016-04-04 04:10:02 UTC

Hi,

Justin B Rye <***@gmail.com> wrote:
[...]

Post by Justin B Rye
<item>the Linux FAQ, by <url name="Ian Jackson" id="http://www.chiark.greenend.org.uk/~ijackson/">,

ok.

[...]

Post by Justin B Rye
(Do people think of etch-a-sketches as blackboards? For a start,
isn't it more of a whiteboard?)

I personally have no preference here (german speaker).
What would you suggest?

People trying to describe what an Etch-a-Sketch is usually seem to
call it something like a "magic art pad". Maybe it doesn't matter as
<item>etch was the toy whiteboard (Etch-a-Sketch),

ok.

[...]

Post by Holger Wansing
<item>squeeze was the name of the three-eyed alien
<item>squeeze was the name of the three-eyed aliens
I personally would use alien

We only ever meet them in groups, but they're instances of the same
toy, so if any of them are named Squeeze they all are (just as both
the spaceman toys in TS2 are Buzz Lightyear). That's a weird enough
situation to make it worth talking in terms of the (one) name of the
<item>squeeze was the name of the three-eyed aliens,

ok.

Thanks
Holger

Joost van Baal-Ilić

2016-03-29 19:50:01 UTC

Hi Holger,

On Tue, Mar 29, 2016 at 07:20:07PM +0200, Holger Wansing wrote:
[...]

Post by Holger Wansing
I would appreciate review and comments.

Apart from Beatrice and Justin's thoughtfull comments: here are my € 0,02.

[...]

Post by Holger Wansing
<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>

s/so I could include/so it could be included/

[...]

Post by Holger Wansing

@@ -423,7 +423,7 @@
using the standard Debian package management tools, you can set up your own
apt-able package archive. This is also useful if you'd like to share your
Debian packages while these are not distributed by the Debian project.
-Instructions on how to do this are given in the <url name="Debian Repository
+Instructions on how to do this are given in the (obsolete) <url name="Debian Repository
HOWTO"
id="http://www.debian.org/doc/manuals/repository-howto/repository-howto">.

Better not mention obsolete stuff at all.

[...]

Post by Holger Wansing
Index: pkgtools.sgml
===================================================================
--- pkgtools.sgml (Revision 10939)
+++ pkgtools.sgml (Arbeitskopie)
@@ -64,7 +64,7 @@
<sect1 id="apt-get">APT
-APT is the Advanced Package Tool is the advanced interface to the
+APT is the Advanced Package Tool, an advanced interface to the
Debian packaging system and provides the <prgn/apt-get/ program.
It features complete installation ordering, multiple source capability and
several other unique features, see the User's Guide in
@@ -91,10 +91,6 @@
<example>apt-get update</example>
(you should execute this regularly to update your package lists)
+### In the following, change the examples into a senseful ordering,
+### as it is also executed by user.
- <item>To upgrade all the packages on your system (without installing

[...]

# is not a comment mark in smgl, use

Post by Holger Wansing
@@ -103,8 +99,12 @@
<item>To remove the foo package and its configuration files from your
- <example>apt-get --purge remove foo</example>
+ <example>apt-get purge foo</example>

I'd use "apt", not "apt-get", as the standard tool for package management.

Thanks for your work!

Bye,

Joost

Holger Wansing

2016-03-30 18:40:02 UTC

Hi,

s/so I could include/so it could be included/

Yes.

[...]

Better not mention obsolete stuff at all.

I will mark this for further discussion.

Post by Holger Wansing
+### In the following, change the examples into a senseful ordering,
+### as it is also executed by user.
- <item>To upgrade all the packages on your system (without installing

[...]
# is not a comment mark in smgl, use

Ok. Although I inserted the lines just as a comment in the patch (to explain
changings). I don't wanted to keep that comments in the sgml file.

I'd use "apt", not "apt-get", as the standard tool for package management.

Since that is likely a lot of more work (and that changings are of that
sort, which I can unfuzzy in the translations easily), I will split that
apt-get -> apt changings into a separate patch.

Thanks
Holger

Holger Wansing

2016-04-04 04:20:01 UTC