proposed changes to debian-faq

Post by Beatrice Torracca
I updated the Italian translation of the Debian FAQ. In doing so I
notice a couple of minor things that I think can be changed (nothing
substantial!).
Since Holger is doing such an extensive great job in
reorganizing/updating the FAQ I thought this might be a good moment to
re-read the FAQs as a "low-level" reviewer. The changes I propose are
mostly minor typos and such.

And almost all of them look to me like definite improvements in the

Post by Beatrice Torracca
@@ -238,8 +238,8 @@
<sect1 id="synaptic">synaptic
<prgn/synaptic/ is a graphical package manager. It enables you to install,
-upgrade and remove software packages in a user friendly way. Next to all
-features offered by aptitude, it also has a feature for editing the list of
+upgrade and remove software packages in a user friendly way. Next to
+all the features offered by aptitude, it also has a feature for editing the list of
used repositories, and supports browsing all available documentation related to
a package. See the <url id="http://www.nongnu.org/synaptic/" name="Synaptic
Website"> for more information.

What is "next to" trying to say here? Something like "alongside",
"along with"? But more importantly, Synaptic doesn't in fact have
*all* the features offered by aptitude (like for instance the debtags
browser view). Could we change it to something like:

upgrade and remove software packages in a user friendly way. Along with
most of the features offered by aptitude, it also has a feature for editing the list of

[...]

Post by Beatrice Torracca
@@ -329,7 +329,7 @@
<example>dpkg --status packagename</example>
-<sect id="listfiles">How to display the files of a package installed?
+<sect id="listfiles">How to display the files of an installed package?

This might just be intended as a sentence fragment talking about
how to do something, in which case it just needs to drop the question
mark, but comparing it with other section titles I suspect it's an
ungrammatical question and needs to turn into something along the
lines of "How do I display the files of an installed package?"

Post by Beatrice Torracca
@@ -372,13 +372,13 @@
If you install the <package>apt-file</package>, similar to the above, it
searches files which contain the substring or regular expression
<tt>foo</tt> in their full path names. The
- advantage over the sample above is that there is no need to retrieve the
+ advantage over the exemple above is that there is no need to retrieve the

Oops, spelling: example

Post by Beatrice Torracca
@@ -387,7 +387,7 @@
multimedia applications and
dictionaries in Debian and has been introduced since some users might
want to access the raw data without installing the program or because
-the program can be run without the data itself, making it optional.
+the program can be run without the data itself, making them optional.

No; "data" is "it", not "them", at least for English-speakers born
after about 1950. If you want to avoid the issue, you can say "making
the package optional".

Post by Beatrice Torracca
Index: uptodate.sgml
===================================================================
--- uptodate.sgml (revisione 11195)
+++ uptodate.sgml (copia locale)
@@ -1,8 +1,8 @@
-
+vn

<chapt id="uptodate">Keeping your Debian system up-to-date

Is that deliberate?

Post by Beatrice Torracca
-A Debian goal is to provide a consistent upgrade path and a secure
+One of Debian goals is to provide a consistent upgrade path and a secure

No: One of Debian's goals

Post by Beatrice Torracca
+
+Or you can use the redirector httpredir.debian.org which aims to
+ solve the problem of choosing a Debian mirror. It uses the geographic
+ location of the user and other information to choose the best mirror
+ that can serve the files. To take advantage of it use a source like
+
+<example>http://httpredir.debian.org/debian stable main contrib non-free</example>
+

Looks good to me.

[...]

Post by Beatrice Torracca
<sect id="keepingalog">How can I keep a log of the packages I added to the
- system? I'd like to know when which package upgrades and removals have
- occured!
+ system? I'd like to know when upgrades and removals have
+ occured and on which packages!

^
Spelling:
occurred

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

Beatrice Torracca

2016-05-29 18:00:01 UTC

On Sunday 29 May 2016, at 17:48 +0100, Justin B Rye wrote:

Hi!

Post by Justin B Rye
And almost all of them look to me like definite improvements in the

I should have added that I am not a native English speaker, although I
think it is quite obvious :)

Thanks for the corrections!

What is "next to" trying to say here? Something like "alongside",
"along with"? But more importantly, Synaptic doesn't in fact have
*all* the features offered by aptitude (like for instance the debtags
upgrade and remove software packages in a user friendly way. Along with
most of the features offered by aptitude, it also has a feature for editing the list of

The meaning (I imagine) was the one you guessed. Your suggestion is
definitely better than mine. I am sure Holger will take it into account.

By the way, I could do the commit but I did not want to disrupt the
workflow of Holger who is reorganizing the FAQ. (But I am willing to do
it if instead it's time-saving for him).

Is that deliberate?

no. my bad, sorry.

beatrice

Brian Potkin

2016-05-29 19:40:01 UTC

No; "data" is "it", not "them", at least for English-speakers born
after about 1950. If you want to avoid the issue, you can say "making
the package optional".

Avoidance is probabably the best and cleanest option.

I'd like to say I was born after 1950 and see "data" as singular, but I
wasn't. :) I'm still inclined to say "the bacteria are...", "the die
is..." and "the media are...". "datum" and "data" are not the same. What
happened after 1950? Logic dissolved into thin air?

Completelely irrelevant to the matter at hand but we now have "trade
union" (a union of trade) instead of "trades union" (a union of trades).
Recently I've seen "Charity Commission" in print. "Charities Commission"
has a distinctly different meaning. How long before we get "Mother
Union" instead of "Mothers' Union"?

Modern English has a problem with plurals. "Education, education,
education" seems not to have addressed it.

Sorry for the wee rant. Please carry on with the excellent work.

Regards,

Brian.

Justin B Rye

2016-05-29 20:30:03 UTC

Post by Brian Potkin

No; "data" is "it", not "them", at least for English-speakers born
after about 1950. If you want to avoid the issue, you can say "making
the package optional".

In fact looking at it again I'm not sure I understood it correctly in
the first place. What is it that's optional - the data, the package,
or the dictionaries etc.?

Post by Brian Potkin
Avoidance is probabably the best and cleanest option.
I'd like to say I was born after 1950 and see "data" as singular, but I
wasn't. :) I'm still inclined to say "the bacteria are...", "the die
is..." and "the media are...". "datum" and "data" are not the same. What
happened after 1950? Logic dissolved into thin air?

The language changed, as it already had for "agenda", "stamina", and
"erotica", largely because it turned out that people only ever needed
to talk about data in bulk rather than a set of individual items. In
the case of "media", it's only in the sense meaning "entertainment
industry" that the word has come to be sometimes used as a singular -
nobody talks about "a removable media".

Post by Brian Potkin
Completelely irrelevant to the matter at hand but we now have "trade
union" (a union of trade) instead of "trades union" (a union of trades).
Recently I've seen "Charity Commission" in print. "Charities Commission"
has a distinctly different meaning. How long before we get "Mother
Union" instead of "Mothers' Union"?

Noun stacks like this are odd; we often file off the endings in
sequences like "the window manager section" (the section for managerS
of windowS), but there are odd exceptions like "an events managers
conference", and I've never been able to see why.

Post by Brian Potkin
Modern English has a problem with plurals. "Education, education,
education" seems not to have addressed it.

Education has nothing to do with it; the way our ancestors spoke isn't
more correct simply because it's older.

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

Holger Wansing

2016-05-29 21:10:01 UTC

Hi,

No; "data" is "it", not "them", at least for English-speakers born
after about 1950. If you want to avoid the issue, you can say "making
the package optional".

In fact looking at it again I'm not sure I understood it correctly in
the first place. What is it that's optional - the data, the package,
or the dictionaries etc.?

Looking at the whole chapter, I think that the foo-data package is the one
which is meant to be optional (meant on the base of the package dependencies).

So I have changed that into

"the program can be run without the data itself, making `foo-data' optional."

That brought me to this part:

"If you use <prgn>aptitude</prgn> (see <ref
id="aptitude">) as your package management tool it will, however,
track automatically installed packages and remove them when no
packages remain that need them in your system."

This is no longer true strictly spoken, since apt now also provides this
feature (see 'apt-get autoremove').
So I have changed this into:

However, if you use <prgn>apt-get</prgn>
(see <ref id="apt-get">) or <prgn>aptitude</prgn> (see <ref id="aptitude">)
as your package management tool, they will
track automatically installed packages and give the possibility to
remove them, when no packages needing them remain in your system.

Holger

--
============================================================
Created with Sylpheed 3.5.0 under
D E B I A N L I N U X 8 . 0 " J E S S I E " .

Registered Linux User #311290 - https://linuxcounter.net/
============================================================

Justin B Rye

2016-05-29 21:20:01 UTC

Post by Holger Wansing
So I have changed that into
"the program can be run without the data itself, making `foo-data' optional."
"If you use <prgn>aptitude</prgn> (see <ref
id="aptitude">) as your package management tool it will, however,
track automatically installed packages and remove them when no
packages remain that need them in your system."
This is no longer true strictly spoken, since apt now also provides this
feature (see 'apt-get autoremove').
However, if you use <prgn>apt-get</prgn>
(see <ref id="apt-get">) or <prgn>aptitude</prgn> (see <ref id="aptitude">)
as your package management tool, they will
track automatically installed packages and give the possibility to
remove them, when no packages needing them remain in your system.

That all looks good.

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

Holger Wansing

2016-05-30 14:40:01 UTC

Hi,

That all looks good.

Ok, thanks.

I have cooked a patch summarizing all the suggestions here together,
just for reference.

Holger

Holger Wansing

2016-06-13 20:20:01 UTC

Hi,

Post by Holger Wansing
Hi,

That all looks good.

Ok, thanks.
I have cooked a patch summarizing all the suggestions here together,
just for reference.

Just committed.

Thanks

victory

2016-05-31 18:40:02 UTC

choosing:123-124:
<item>Stable is rock solid. It does not break and has full security
support. But it not might have support for the latest hardware.

might not

--
victory
no need to CC me :-)

Holger Wansing

2016-05-29 19:00:02 UTC

Hi Beatrice,

I very much appreciate your work on debian-faq!

Justin: thanks for your comments against this patch!

Great. You found a lot of typos / potential for improvement.

Post by Beatrice Torracca
The only change related to actual contents is about the use of
httpredir.
I attach a suggested patch for 4 of the sgml files in the source tree.
Holger can decide what to change or not change of course.

I would not vote myself as the main decision-maker though :-)
Always appreciating review / comments / acknowledgement / objections by
the team. Especially since I am also not a native English speaker.
And no DD (but my application is running :-) ).

Post by Beatrice Torracca
I plan to read the rest of the files in the repo too, unless someone
objects to my suggestions.

Yes! Please do!

Post by Beatrice Torracca
Starting with Debian Jessie, some frequently used
-<prgn/apt-get/ and <prgn/apt-cache/ commands got an equivalent via
+<prgn/apt-get/ and <prgn/apt-cache/ commands have an equivalent via

I don't see the improvement here, so omitting this.

Post by Beatrice Torracca
the new <prgn/apt/ binary. This means some popular commands like
<prgn/apt-get update/, <prgn/apt-get install/, <prgn/apt-get remove/,
<prgn/apt-cache search/, or <prgn/apt-cache show/ now can also be called

[...]

Post by Beatrice Torracca
@@ -321,8 +321,8 @@
status symbol (explained in the header), the package name, the version
which is installed, and a brief description.
-To learn the status of packages whose names match the string any
+To learn the status of packages whose names match any

Maybe we should change "learn" into something like "query" here?
Justin?

Post by Beatrice Torracca
<example>dpkg --list 'foo*'</example>
To get a more verbose report for a particular package, execute the

[...]

Post by Beatrice Torracca
@@ -1,8 +1,8 @@
-
+vn

<chapt id="uptodate">Keeping your Debian system up-to-date
-A Debian goal is to provide a consistent upgrade path and a secure
+One of Debian goals is to provide a consistent upgrade path and a secure

Maybe better "One of Debian's goals ... " ?

Post by Beatrice Torracca
upgrade process. We always do our best to make upgrading to new releases
a smooth procedure. In case there's some important note to
add to the upgrade process, the packages will alert the user, and often

[...]

Post by Beatrice Torracca
@@ -47,10 +47,19 @@
name of a faster Debian mirror near you. See the mirror list at
<url id="http://www.debian.org/mirror/list"> for more information.
+
+Or you can use the redirector httpredir.debian.org which aims to

Or you can use the redirector service httpredir.debian.org ?
(add "service" )

Post by Beatrice Torracca
+ solve the problem of choosing a Debian mirror. It uses the geographic
+ location of the user and other information to choose the best mirror
+ that can serve the files. To take advantage of it use a source like
+
+<example>http://httpredir.debian.org/debian stable main contrib non-free</example>

Maybe we should not include "non-free" in such examples?
Users may copy them directly to their sources.list and have non-free
without knowing of the exact details regarding non-free.

There is another code example in this chapter, which also includes
non-free. I would remove it there too.

Post by Beatrice Torracca
+
More details on this can be found in the <manref name="sources.list"
section="5"> manual page.
-To update your system in command line, run
+To update your system from the command line, run
<example>aptitude update</example>
followed by
<example>aptitude full-upgrade</example>

All the rest of the patch is perfectly fine with me
(apart from the issues brought up by Justin, of course).
If noone objects, I will commit it in a week or two.

Best regards
Holger

Justin B Rye

2016-05-29 19:40:01 UTC

Post by Beatrice Torracca
Since Holger is doing such an extensive great job in
reorganizing/updating the FAQ I thought this might be a good moment to
re-read the FAQs as a "low-level" reviewer. The changes I propose are
mostly minor typos and such.

Great. You found a lot of typos / potential for improvement.

[...]

I don't see the improvement here, so omitting this.

It's a non-native-speakerism. The current FAQ says that the commands
"got" (="did acquire") an equivalent. What it's trying to say is
that the commands "have" (="do possess") an equivalent.

[...]

Maybe we should change "learn" into something like "query" here?
Justin?

"Query" would work, but "learn" has the advantage of being simpler
than most of the alternatives, which is helpful here.

[...]

Post by Beatrice Torracca
+
+Or you can use the redirector httpredir.debian.org which aims to

Or you can use the redirector service httpredir.debian.org ?
(add "service" )

(Those both sound okay, and I don't know which is more accurate.)

Maybe we should not include "non-free" in such examples?
Users may copy them directly to their sources.list and have non-free
without knowing of the exact details regarding non-free.
There is another code example in this chapter, which also includes
non-free. I would remove it there too.

(I had a similar thought but was too lazy to check other examples.)

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

Holger Wansing

2016-05-29 19:50:02 UTC

Hi,

I don't see the improvement here, so omitting this.

It's a non-native-speakerism. The current FAQ says that the commands
"got" (="did acquire") an equivalent. What it's trying to say is
that the commands "have" (="do possess") an equivalent.

Yes, that was exactly what I wanted to say when I wrote that sentence:
that there is a new binary named apt, introduced with Jessie, which has said
advantages.
And that's why I like the "got" :-)

Post by Justin B Rye
[...]

Maybe we should change "learn" into something like "query" here?
Justin?

"Query" would work, but "learn" has the advantage of being simpler
than most of the alternatives, which is helpful here.

Ok, so we stay with learn.

Post by Justin B Rye
[...]

Post by Beatrice Torracca
+
+Or you can use the redirector httpredir.debian.org which aims to

Or you can use the redirector service httpredir.debian.org ?
(add "service" )

(Those both sound okay, and I don't know which is more accurate.)

I have heard of the httpredir thing as a "service" many times, that's why I
proposed it.

Maybe we should not include "non-free" in such examples?
Users may copy them directly to their sources.list and have non-free
without knowing of the exact details regarding non-free.
There is another code example in this chapter, which also includes
non-free. I would remove it there too.

(I had a similar thought but was too lazy to check other examples.)

Ok.

Cheers
Holger

Justin B Rye

2016-05-29 20:30:02 UTC

I don't see the improvement here, so omitting this.

It's a non-native-speakerism. The current FAQ says that the commands
"got" (="did acquire") an equivalent. What it's trying to say is
that the commands "have" (="do possess") an equivalent.

that there is a new binary named apt, introduced with Jessie, which has said
advantages.
And that's why I like the "got" :-)

It doesn't work with simple past "got", though; we're not talking
about something that's over and done with, we're talking about the
present-day effects of this new binary being added, so it's
present-perfect - they "have gotten" or more likely "have gained" an
equivalent. And since we've already explicitly said when the change
happened, we wouldn't lose any information if we just said "have".

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

Holger Wansing

2016-05-29 20:40:02 UTC

Hi,