Additional manual issues re 22.04 LTS

[nerdfever]

Sorry to open so many issues. I'm willing to do some editing on the manual (w/change marks) if I can get source editable in MS Word or LibreOffice.

Also I apologize for being so nitpicky, but this is the FIRST document about Kubuntu new users are supposed to read. It needs to be clear and accurate. Learning a new OS is complicated and challenging enough without rough documentation.

The below are all against https://github.com/kubuntu-team/kubuntu-manual/releases/tag/v22.04.1 as of the date of this issue.

4.2 (Repositories):

Typo in last paragraph "check the click on".

4.2.1 (PPAs):

References "Launchpad' but never explains what "Launchpad" is. It appears to be a website at https://launchpad.net/. This should be explained.

The end of this paragraph says:

For more information about PPAs, click on the Repositories section of this manual.

That section s 4.2, this is section 4.2.1, so technically this text is already in the "Repositories" section. As well, it's not a link, so the reader can't "click on" it.

Also, that section (4.2) IMMEDIATELY PRECEDES this section.

Also, that section does not in fact contain additional info about PPAs.

4.2.2 (says "Kubuntu Backports" but actually multiple subjects)

The "Managing Personal Package Archives", "Add a PPA", and "Remove a PPA" sections don't have their own section numbers, they're all under 4.2.2 ("Backports"), yet don't seem to be about backports. They should have their own section numbers.

"Managing Personal Package Archives"

This section appears to be mostly a duplicate of the paragraph above in 4.2.1 about "PPAs".

"Add a PPA"

Instructions are given re how to add a PPA to Discover. This is confusing because the instructions actually have nothing to do with Discover but are all about apt.

This section says:

Open the Launchpad PPA overview page in your browser

But does not give a URL for this page (nor a link). After googling, I think it's referring to https://launchpad.net/~kubuntu-ppa/+archive/ubuntu/backports (but I'm not sure).

Assuming that's the correct link, the page contradicts the manual. That page doesn't given any instructions about Discover at all - only using apt. The page says:

Adding this PPA to your system
You can update your system with unsupported packages from this untrusted PPA by adding ppa:kubuntu-ppa/backports to your system's Software Sources. (Read about installing)

sudo add-apt-repository ppa:kubuntu-ppa/backports
sudo apt update

Next, still in the Add a PPA section, the manual directions say:

You can use the Discover to add a PPA:

1. Open the Launchpad PPA overview page in your browser for example look at the Kubuntu Backports PPA
2. Look for the ‘Adding this PPA to your system’ section
3. Open Konsole then copy (Ctrl+C once the command is highlighted)
4. Now paste (Ctrl+Shift+V in terminals like Konsole) and press the Enter key

Despite the first line, these instructions are completely about using Konsole and apt, and don't have anything to do with Discover (other than the result of doing this indirectly makes the new PPA appear in Discover).

"You can use Discover" to do this is incorrect (unless there's some way to add a PPA other than the one described here).

Step 3 quoted above refers to "the command" yet in the example page given there are 2 commands (not 1) to be copied and pasted - should be reworded to "command(s)".

sudo add-apt-repository ppa:kubuntu-ppa/backports
sudo apt update

The entire PPA discussion in the manual confuses apt and Discover - it says Discover when it means apt.

Page 37 - figure doesn't match distro

============

Personal comments:

The whole subject of discovery and installation of software is complex and very confusing to new Linux users. There's Discover and apt, repositories, packages, and .DEB files. And snaps and flatpaks.

And all these differ from distro to distro and between DEs. And are very different from Windows.

If we want to see people using Linux desktops, all this needs to be explained clearly, carefully, and accurately. I'm sure the Linux community loses lots of potential users because of this.

I think it needs to be kept in mind that new users are not going to read this manual in isolation - they're going to google unfamiliar things and read about other distros and DEs and about obsolete things that are still on the Web. So in order to make sense of all that, we need to explain some general background about Linux and how it works.

In particular, I think new users need to be made familiar with the NAMES of the pieces of the Linux system and WHAT THOSE NAMES MEAN, since they're going to see them a lot online. This is lacking now (not just in this manual - in general the Linux community throws around lots of terminology without much explanation of what it all means. This is understandable, but it needs to be explained for new users).

I'm a newbie myself, but here are some of my own notes - maybe they can be a basis for some clearer discussion for new users (of course these may not be entirely accurate, as I'm a newbie myself):

TERMINOLOGY RE SOFTWARE INSTALLERS

KDE - an org (non-profit)
Canonical - an org (for-profit)

KDE Neon - a Linux distrubiton using KDE Plasma, from KDE
Kubuntu - a Linux distrubiton using KDE Plasma, from Canonical

Plasma - KDE's Desktop Enviornment (vs. Gnome, etc.)
QT - a graphical toolkit used for building apps and DEs (used in Plasma and LXQt)
GTK - a graphical toolkit used for building apps and DEs (used in Gnome, Unity, and others)

dpkg - Very low level. Can mess with kernel stuff. Try to avoid unless seriously messed up.
apt - wrapper around dpkg. Debian's command-line installer, a front-end to dpkg
Discover - GUI wrapper around apt. "an app store" for KDE (part of Plasma). Handles snaps and flatpaks.

Not used or needed in Kubuntu, but for other distros:
Synaptic - GUI package manger, a GTK-based frontent to apt - equiv. of Muon
Muon - GUI package manager, Plasma-based front-end to apt. Shows every tiny package for multiplet binaries, gui apps, system libraries, dependencies. No snaps or flatpaks. It does not handle things like snaps Flatpaks or theming bits. apt can do everything this can do. No need to use it in Kubuntu

KPackage - was KDE's package manager frontend (sez Wikipedia) - Obsolete.

Conclusion -to find software look in the following places, in this order: (1) Discover - native program (2) Discover - snap (3) Discover - flatpak (4) .DEB file from developer (not sure how to install that...) (5) Wine (if a Windows program) (6) a Windows VM (if a windows program won't work in Wine).

Also probably worth mentioning in a Troubleshooting section:

IF YOUR SYSTEM GETS BORKED

Alt+Ctrl+F3 - gets you to a command-line terminal. Login there.

Then:
sudo apt install kubuntu-desktop

MORE TERMINOLOGY

Linux distributions come from organizations - Kubuntu (and other Ubuntu flavors) comes from Canonical.

Every GUI Linux distribution has a Desktop Environment (DE). There are many DEs - popular ones include Gnome and Plasma. Each DE has many derivative versions - for example the Cinnamon and MATE DEs are derived from Gnome.

Kubuntu's DE is called "Plasma". It's from an organization called "KDE" (and "KDE" is often used as an alternative name for it). KDE is independent of Canonical. The Plasma DE is also used in other Linux distributions (for example KDE Neon).

DEs and GUI applications are built on top of GUI toolkits. Again, there are many GUI toolkits. The most popular GUI toolkits are QT and GTK. LXQt (a DE) and Plasma are built on QT. Gnome, its derivatives, and many other DEs are built on GTK.

Apps built with any reasonably popular GUI toolkit can run on all GUI Linux distros. Apps built with the same GUI toolkit as the distro will look prettier, but even if built with a different GUI toolkit, they'll still work. This is why you may hear about many similar Linux applications for the same purpose. For example the HexChat IRC client is based on GTK while Konversation (supplied in Kubuntu) is based on QT. They have similar functionality, and either can be used on any GUI Linux. The difference is mostly how pretty they look on which distributions. A Linux distribution usually supplies a set of applications that look good on that distro, because they're built with the same GUI toolkit. But you can install others if you prefer.

[ahoneybun]

I think I addressed a good chuck of this in the latest commit to the kubuntu-22.04 branch but let me know if there is anything wrong or if it looks good. I am going to release the 22.04.2 version of the manual on Friday if I don't hear anything by then.