debian-faq: Patch4 to change apt-get / apt-cache into apt

[Holger Wansing]

Hello,

now the fourth patch, which documents the new apt command, as an
alternative for apt-get / apt-cache.

My approach is, to list both variants in examples, means the old
apt-get command, and the new apt command.

I added a sentence which gives a declaration about the new apt binary.

Additionally, I made apt/apt-get the recommended package tool over
aptitude. (Before it was the other way around.)


Comments welcome.


Holger

[Justin B Rye]

--- pkgtools.sgml (Revision 11106)
+++ pkgtools.sgml (Arbeitskopie)
@@ -72,6 +72,17 @@
<tt>/usr/share/doc/apt-doc/guide.html/index.html</tt> (you will have to install
the <tt>apt-doc</tt> package).
+<p>Please note that starting with Debian Jessie, the most popular
+<prgn/apt-get/ and <prgn/apt-cache/ commands got an equivalent via
+the new <prgn/apt/ binary. So some frequently used commands like
+<prgn/apt-get update/, <prgn/apt-get upgrade/, <prgn/apt-get install/,
+<prgn/apt-get remove/, <prgn/apt-cache search/, or <prgn/apt-cache show/
+now can also be called simply via <prgn/apt/, say <prgn/apt update/,
+<prgn/apt upgrade/, <prgn/apt install/, <prgn/apt remove/, <prgn/apt search/,
+or <prgn/apt show/ respective. To reflect this, we have listed both

^^^^^^^^^^

+variants (the <prgn/apt-get/ and the <prgn/apt/ command) in the
+examples below.
+

Where you've got the adjective "respective" there, the grammatical
version would have the adverb "respectively"; but the *natural* way
of saying this, here as almost always, would be to leave the word out
completely. You don't need to say that the two lists match up; after
all, why would anyone expect you to have scrambled them?

[...]

<item>To remove the foo package and its configuration files from your
<example>apt-get purge foo</example>
+ or <example>apt purge foo</example>
+ <item>To list all packages, for which newer package versions are

^
Surplus comma. English would only have one here if having newer
versions available was a defining characteristic of packages.

+ <example>apt list --upgradable</example>
+

[...]

@@ -44,12 +47,41 @@
<example>http://ftp.us.debian.org/debian stable main contrib non-free</example>
<p>You can replace ftp.us.debian.org (the mirror in the United States) with the
-name of a faster Debian mirror near you. See the mirror list at
+name of a faster Debian mirror near by you. See the mirror list at

This isn't an improvement.

[Holger Wansing]

Hi,

Post by Justin B Rye

--- pkgtools.sgml (Revision 11106)
+++ pkgtools.sgml (Arbeitskopie)
@@ -72,6 +72,17 @@
<tt>/usr/share/doc/apt-doc/guide.html/index.html</tt> (you will have to install
the <tt>apt-doc</tt> package).
+<p>Please note that starting with Debian Jessie, the most popular
+<prgn/apt-get/ and <prgn/apt-cache/ commands got an equivalent via
+the new <prgn/apt/ binary. So some frequently used commands like
+<prgn/apt-get update/, <prgn/apt-get upgrade/, <prgn/apt-get install/,
+<prgn/apt-get remove/, <prgn/apt-cache search/, or <prgn/apt-cache show/
+now can also be called simply via <prgn/apt/, say <prgn/apt update/,
+<prgn/apt upgrade/, <prgn/apt install/, <prgn/apt remove/, <prgn/apt search/,
+or <prgn/apt show/ respective. To reflect this, we have listed both

^^^^^^^^^^

+variants (the <prgn/apt-get/ and the <prgn/apt/ command) in the
+examples below.
+

Where you've got the adjective "respective" there, the grammatical
version would have the adverb "respectively"; but the *natural* way
of saying this, here as almost always, would be to leave the word out
completely. You don't need to say that the two lists match up; after
all, why would anyone expect you to have scrambled them?

ok

Post by Justin B Rye

<item>To remove the foo package and its configuration files from your
<example>apt-get purge foo</example>
+ or <example>apt purge foo</example>
+ <item>To list all packages, for which newer package versions are

^
Surplus comma. English would only have one here if having newer
versions available was a defining characteristic of packages.

ok.

Post by Justin B Rye

+ <example>apt list --upgradable</example>
+

[...]

@@ -44,12 +47,41 @@
<example>http://ftp.us.debian.org/debian stable main contrib non-free</example>
<p>You can replace ftp.us.debian.org (the mirror in the United States) with the
-name of a faster Debian mirror near you. See the mirror list at
+name of a faster Debian mirror near by you. See the mirror list at

This isn't an improvement.

ok.


Holger

[Joost van Baal-Ilić]

Hi Holger,

Post by Holger Wansing
now the fourth patch, which documents the new apt command, as an
alternative for apt-get / apt-cache.
My approach is, to list both variants in examples, means the old
apt-get command, and the new apt command.

I'd list just "apt", and drop "apt-get" from the examples.

Post by Holger Wansing
I added a sentence which gives a declaration about the new apt binary.

I'd add a sentence like: "The apt tool merges functionality of apt-get and
apt-cache; and by default has a fancier colored output format, making it more
pleasant for humans. For usage in scripts, apt-get is still preferable."

Thanks, Bye,

Joost

[Holger Wansing]

[ BTW: no need to CC me. ]


Hi,

Post by Joost van Baal-Ilić
Hi Holger,

Post by Holger Wansing
now the fourth patch, which documents the new apt command, as an
alternative for apt-get / apt-cache.
My approach is, to list both variants in examples, means the old
apt-get command, and the new apt command.

I'd list just "apt", and drop "apt-get" from the examples.

Yes, that would be the other approach.
But I am not sure, what is better. Replacing "apt-get" with "apt" would only
work in some examples, so some would say "apt install ..." and others
would say "apt-get source ...".
Or "apt show ..." versus "apt-cache showpkg ..."
Maybe that's more confusing than a simplification?

Post by Joost van Baal-Ilić

Post by Holger Wansing
I added a sentence which gives a declaration about the new apt binary.

I'd add a sentence like: "The apt tool merges functionality of apt-get and
apt-cache; and by default has a fancier colored output format, making it more
pleasant for humans. For usage in scripts, apt-get is still preferable."

apt tool only merges *some*functionality* of apt-get and apt-cache, not
everything.
So it should probably say "For usage in scripts or advanced use cases,
apt-get is still preferable or needed."


Holger

[Joost van Baal-Ilić]

Hi,

Post by Holger Wansing

Post by Joost van Baal-Ilić

Post by Holger Wansing
now the fourth patch, which documents the new apt command, as an
alternative for apt-get / apt-cache.
My approach is, to list both variants in examples, means the old
apt-get command, and the new apt command.

I'd list just "apt", and drop "apt-get" from the examples.

Yes, that would be the other approach.
But I am not sure, what is better. Replacing "apt-get" with "apt" would only
work in some examples, so some would say "apt install ..." and others
would say "apt-get source ...".
Or "apt show ..." versus "apt-cache showpkg ..."

I'd mention 'apt show' and I'd choose to no longer mention 'apt-cache showpkg'.

Post by Holger Wansing
Maybe that's more confusing than a simplification?

I feel it's simpler now: In most common cases, apt is what you need to handle
packages. For most cases, one no longer needs to figure out if one would need
apt-get or apt-cache or aptitude or ....

Post by Holger Wansing

Post by Joost van Baal-Ilić

Post by Holger Wansing
I added a sentence which gives a declaration about the new apt binary.

I'd add a sentence like: "The apt tool merges functionality of apt-get and
apt-cache; and by default has a fancier colored output format, making it more
pleasant for humans. For usage in scripts, apt-get is still preferable."

apt tool only merges *some*functionality* of apt-get and apt-cache, not
everything.
So it should probably say "For usage in scripts or advanced use cases,
apt-get is still preferable or needed."

Yes, that's better.

Bye,

Joost

[Holger Wansing]

Hi,

Post by Joost van Baal-Ilić
Hi,

Post by Holger Wansing

Post by Joost van Baal-Ilić

Post by Holger Wansing
now the fourth patch, which documents the new apt command, as an
alternative for apt-get / apt-cache.
My approach is, to list both variants in examples, means the old
apt-get command, and the new apt command.

I'd list just "apt", and drop "apt-get" from the examples.

Yes, that would be the other approach.
But I am not sure, what is better. Replacing "apt-get" with "apt" would only
work in some examples, so some would say "apt install ..." and others
would say "apt-get source ...".
Or "apt show ..." versus "apt-cache showpkg ..."

I'd mention 'apt show' and I'd choose to no longer mention 'apt-cache showpkg'.

Post by Holger Wansing
Maybe that's more confusing than a simplification?

I feel it's simpler now: In most common cases, apt is what you need to handle
packages. For most cases, one no longer needs to figure out if one would need
apt-get or apt-cache or aptitude or ....

Should we add a table which lists all the new apt commands and their old
apt-get / apt-cache variants in comparison?
Maybe that would make sense, since you are not always done with simply
replacing "apt-get" with "apt". There are cases, which are not that intuitive:
as an example, "apt-cache showpkg <name>" converts into "apt show -a <name>".


Holger

[Holger Wansing]

Hi,

Post by Holger Wansing
Should we add a table which lists all the new apt commands and their old
apt-get / apt-cache variants in comparison?
Maybe that would make sense, since you are not always done with simply
as an example, "apt-cache showpkg <name>" converts into "apt show -a <name>".

I have added a table with the changings in comparison.


Included in the attached patch.


Holger

[Holger Wansing]

Hi,

Post by Holger Wansing
Hi,

Post by Holger Wansing
Should we add a table which lists all the new apt commands and their old
apt-get / apt-cache variants in comparison?
Maybe that would make sense, since you are not always done with simply
as an example, "apt-cache showpkg <name>" converts into "apt show -a <name>".

I have added a table with the changings in comparison.
Included in the attached patch.

Patch applied.

Thanks

Holger