From cbffab246997fb5a06211dfb706b54e5ae5bb59f Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Sun, 7 Apr 2024 16:58:51 +0200
Subject: Adding upstream version 1.21.22.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 man/dselect.pod | 675 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 675 insertions(+)
 create mode 100644 man/dselect.pod

(limited to 'man/dselect.pod')

diff --git a/man/dselect.pod b/man/dselect.pod
new file mode 100644
index 0000000..507a741
--- /dev/null
+++ b/man/dselect.pod
@@ -0,0 +1,675 @@
+# dselect manual page - dselect(1)
+#
+# Copyright © 1995 Juho Vuori <javuori@cc.helsinki.fi>
+# Copyright © 2000 Josip Rodin
+# Copyright © 2001 Joost Kooij
+# Copyright © 2001 Wichert Akkerman <wakkerma@debian.org>
+# Copyright © 2010-2015 Guillem Jover <guillem@debian.org>
+#
+# This is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+=encoding utf8
+
+=head1 NAME
+
+dselect - Debian package management frontend
+
+=head1 SYNOPSIS
+
+B<dselect>
+[I<option>...] [I<command>...]
+
+=head1 DESCRIPTION
+
+B<dselect>
+is one of the primary user interfaces for managing packages on a Debian
+system. At the B<dselect> main menu, the system administrator can:
+
+=over
+
+=item *
+
+Update the list of available package versions,
+
+=item *
+
+View the status of installed and available packages,
+
+=item *
+
+Alter package selections and manage dependencies,
+
+=item *
+
+Install new packages or upgrade to newer versions.
+
+=back
+
+B<dselect>
+operates as a front-end to B<dpkg>(1), the low-level Debian package
+handling tool. It features a full-screen package selections manager
+with package depends and conflicts resolver. When run with administrator
+privileges, packages can be installed, upgraded and removed. Various
+access methods can be configured to retrieve available package version
+information and installable packages from package repositories.
+Depending on the used access method, these repositories can be public
+archive servers on the internet, local archive servers or CD-ROMs.
+The recommended access method is I<apt>, which is provided by the
+package B<apt>(8).
+
+Normally B<dselect> is invoked without parameters. An interactive
+menu is presented, offering the user a list of commands. If a command
+is given as argument, then that command is started immediately. Several
+command line parameters are still available to modify the running behaviour
+of B<dselect> or show additional information about the program.
+
+=head1 OPTIONS
+
+All options can be specified both on the command line and in the B<dselect>
+configuration file I<%PKGCONFDIR%/dselect.cfg> or the files on the
+configuration directory I<%PKGCONFDIR%/dselect.cfg.d/>. Each line in the
+configuration file is either an option (exactly the same as the
+command line option but without leading hyphens) or a comment (if it starts
+with a ‘B<#>’).
+
+=over
+
+=item B<--admindir> I<directory>
+
+Changes the directory where the dpkg ‘I<status>’,
+‘I<available>’ and similar files are located.
+Defaults to I<%ADMINDIR%> if B<DPKG_ADMINDIR> has not been set.
+
+=item B<--instdir> I<directory>
+
+Set the installation directory, which refers to the directory where
+packages get installed (since dpkg 1.21.2).
+Defaults to «I</>» if B<DPKG_ROOT> has not been set.
+
+=item B<--root> I<directory>
+
+Set the root directory to I<directory>, which sets the installation
+directory to «I<directory>» and the administrative
+directory to «I<directory>%ADMINDIR%» (since dpkg 1.21.0).
+
+=item B<-D>I<file>, B<--debug> I<file>
+
+Turn on debugging. Debugging information is sent to I<file>.
+
+=item B<--expert>
+
+Turns on expert mode, i.e. doesn't display possibly annoying help
+messages.
+
+=item B<--color> I<screenpart>:[I<foreground>],[I<background>][:I<attr>[I<+attr>]...]
+
+=item B<--colour> I<screenpart>:[I<foreground>],[I<background>][:I<attr>[I<+attr>]...]
+
+Configures screen colors. This works only if your display supports colors.
+This option may be used multiple times (and is best used in
+I<dselect.cfg>). Each use changes the color (and optionally, other
+attributes) of one part of the screen.
+The parts of the screen (from top to bottom) are:
+
+=over
+
+=item B<title>
+
+The screen title.
+
+=item B<listhead>
+
+The header line above the list of packages.
+
+=item B<list>
+
+The scrolling list of packages (and also some help text).
+
+=item B<listsel>
+
+The selected item in the list.
+
+=item B<pkgstate>
+
+In the list of packages, the text indicating the current state of each
+package.
+
+=item B<pkgstatesel>
+
+In the list of packages, the text indicating the current state of the
+currently selected package.
+
+=item B<infohead>
+
+The header line that displays the state of the currently selected package.
+
+=item B<infodesc>
+
+The package's short description.
+
+=item B<info>
+
+Used to display package info such as the package's description.
+
+=item B<infofoot>
+
+The last line of the screen when selecting packages.
+
+=item B<query>
+
+Used to display query lines
+
+=item B<helpscreen>
+
+Color of help screens.
+
+=back
+
+After the part of the screen comes a colon and the color specification. You
+can specify either the foreground color, the background color, or both,
+overriding the compiled-in colors. Use standard curses color names.
+
+Optionally, after the color specification is another colon, and an
+attribute specification. This is a list of one or more attributes,
+separated by plus (‘+’) characters.
+Available attributes include (not all of these will work on all terminals):
+B<normal>, B<standout>, B<underline>, B<reverse>, B<blink>,
+B<bright>, B<dim>, B<bold>
+
+=item B<-?>, B<--help>
+
+Print a brief help text and exit successfully.
+
+=item B<--version>
+
+Print version information and exit successfully.
+
+=back
+
+=head1 COMMANDS
+
+When
+B<dselect>
+is started it can perform the following commands, either directly if it
+was specified on the command line or by prompting the user with a menu
+of available commands if running interactively:
+
+=head2 access
+
+Choose and configure an access method to access package repositories.
+
+By default, B<dselect> provides several methods such
+as I<multi_cd>, I<mounted> or I<ftp>, but other
+packages may provide additional methods, for example the I<apt> access method
+provided by the B<apt>(8) package.
+
+The use of the I<apt> access method is strongly recommended.
+
+=head2 update
+
+Refresh the available packages database.
+
+Retrieves a list of available package versions from the package
+repository, configured for the current access method, and update
+the dpkg database. The package lists are commonly provided by the
+repository as files named I<Packages> or I<Packages.gz>.
+These files can be generated by repository maintainers, using the
+program B<dpkg-scanpackages>(1).
+
+Details of the update command depend on the access method's implementation.
+Normally the process is straightforward and requires no user interaction.
+
+=head2 select
+
+View or manage package selections and dependencies.
+
+This is the main function of B<dselect>. In the select screen, the
+user can review a list of all available and installed packages. When run
+with administrator privileges, it is also possible to interactively
+change packages selection state. B<dselect> tracks the implications
+of these changes to other depending or conflicting packages.
+
+When a conflict or failed depends is detected, a dependency resolution
+subscreen is prompted to the user. In this screen, a list of conflicting
+or depending packages is shown, and for each package listed, the reason
+for its listing is shown. The user may apply the suggestions proposed
+by B<dselect>, override them, or back out all the changes, including
+the ones that created the unresolved depends or conflicts.
+
+The use of the interactive package selections management screen is
+explained in more detail below.
+
+=head2 install
+
+Installs selected packages.
+
+The configured access method will fetch installable or upgradable packages
+from the relevant repositories and install these using B<dpkg>.
+Depending on the implementation of the access method, all packages can
+be prefetched before installation, or fetched when needed.
+Some access methods may also remove packages that were marked for removal.
+
+If an error occurred during install, it is usually advisable to run
+install again. In most cases, the problems will disappear or be solved.
+If problems persist or the installation performed was incorrect, please
+investigate into the causes and circumstances, and file a bug in the
+Debian bug tracking system. Instructions on how to do this can be found
+at L<https://bugs.debian.org/> or by reading the documentation
+for B<bug>(1) or B<reportbug>(1), if these are installed.
+
+Details of the install command depend on the access method's implementation.
+The user's attention and input may be required during installation,
+configuration or removal of packages. This depends on the maintainer
+scripts in the package. Some packages make use of the B<debconf>(1)
+library, allowing for more flexible or even automated installation
+setups.
+
+=head2 config
+
+Configures any previously installed, but not fully configured packages.
+
+=head2 remove
+
+Removes or purges installed packages, that are marked for removal.
+
+=head2 quit
+
+Quit B<dselect>.
+
+Exits the program with zero (successful) error code.
+
+=head1 PACKAGE SELECTIONS MANAGEMENT
+
+=head2 Introduction
+
+B<dselect>
+directly exposes
+the administrator to some of the complexities involved with managing
+large sets of packages with many interdependencies. For a user who is
+unfamiliar with the concepts and the ways of the Debian package management
+system, it can be quite overwhelming. Although B<dselect> is aimed
+at easing package management and administration, it is only instrumental
+in doing so and cannot be assumed to be a sufficient substitute for
+administrator skill and understanding. The user is required to
+be familiar with the concepts underlying the Debian packaging system.
+In case of doubt, consult the B<dpkg>(1) manpage and the distribution
+policy.
+
+Unless B<dselect> is run in expert
+or immediate mode, a help screen is first displayed when choosing this
+command from the menu. The user is I<strongly> advised to study all of
+the information presented in the online help screens, when one pops up.
+The online help screens can at any time be invoked with the ‘B<?>’ key.
+
+=head2 Screen layout
+
+The select screen is by default split in a top and a bottom half.
+The top half shows a list of packages. A cursor bar can select an
+individual package, or a group of packages, if applicable, by selecting
+the group header. The bottom half of the screen shows some details
+about the package currently selected in the top half of the screen.
+The type of detail that is displayed can be varied.
+
+Pressing the ‘B<I>’ key toggles a full-screen display of the packages
+list, an enlarged view of the package details, or the equally split screen.
+
+=head2 Package details view
+
+The package details view by default shows the extended package description
+for the package that is currently selected in the packages status list.
+The type of detail can be toggled by pressing the ‘B<i>’ key.
+This alternates between:
+
+=over
+
+=item *
+
+the extended description
+
+=item *
+
+the control information for the installed version
+
+=item *
+
+the control information for the available version
+
+=back
+
+In a dependency resolution screen, there is also the possibility of
+viewing the specific unresolved depends or conflicts related to the
+package and causing it to be listed.
+
+=head2 Packages status list
+
+The main select screen displays a list of all packages known to the Debian
+package management system. This includes packages installed on the system
+and packages known from the available packages database.
+
+For every package, the list shows the package's status, priority, section,
+installed and available architecture, installed and available versions,
+the package name and its short description, all in one line.
+By pressing the ‘B<A>’ key, the display of the installed and
+available architecture can be toggled between on an off.
+By pressing the ‘B<V>’ key, the display of the installed and
+available version can be toggled between on an off.
+By pressing the ‘B<v>’ key, the package status display is toggled
+between verbose and shorthand.
+Shorthand display is the default.
+
+The shorthand status indication consists
+of four parts: an error flag, which should normally be clear, the
+current status, the last selection state and the current selection state.
+The first two relate to the actual state of the package, the second pair
+are about the selections set by the user.
+
+These are the meanings of the shorthand package status indicator codes:
+
+=over
+
+Error flag:
+
+=over
+
+=item I<empty>   no error
+
+=item B<R>       serious error, needs reinstallation;
+
+=back
+
+Installed state:
+
+=over
+
+=item I<empty>   not installed;
+
+=item B<*>       fully installed and configured;
+
+=item B<->       not installed but some config files may remain;
+
+=item B<U>       unpacked but not yet configured;
+
+=item B<C>       half-configured (an error happened);
+
+=item B<I>       half-installed (an error happened).
+
+=back
+
+Current and requested selections:
+
+=over
+
+=item B<*>       marked for installation or upgrade;
+
+=item B<->       marked for removal, configuration files remain;
+
+=item B<=>       on hold: package will not be processed at all;
+
+=item B<_>       marked for purge, also remove configuration;
+
+=item B<n>       package is new and has yet to be marked.
+
+=back
+
+=back
+
+=head2 Cursor and screen movement
+
+The package selection list and the dependency conflict
+resolution screens can be navigated using motion
+commands mapped to the following keys:
+
+=over
+
+=over
+
+=item B<p, Up, k>           move cursor bar up
+
+=item B<n, Down, j>         move cursor bar down
+
+=item B<P, Pgup, Backspace> scroll list 1 page up
+
+=item B<N, Pgdn, Space>     scroll list 1 page down
+
+=item B<^p>                 scroll list 1 line up
+
+=item B<^n>                 scroll list 1 line down
+
+=item B<t, Home>            jump to top of list
+
+=item B<e, End>             jump to end of list
+
+=item B<u>                  scroll info 1 page up
+
+=item B<d>                  scroll info 1 page down
+
+=item B<^u>                 scroll info 1 line up
+
+=item B<^d>                 scroll info 1 line down
+
+=item B<B, Left-arrow>      pan display 1/3 screen left
+
+=item B<F, Right-arrow>     pan display 1/3 screen right
+
+=item B<^b>                 pan display 1 character left
+
+=item B<^f>                 pan display 1 character right
+
+=back
+
+=back
+
+=head2 Searching and sorting
+
+The list of packages can be searched by package name. This
+is done by pressing ‘B</>’, and typing a simple search
+string. The string is interpreted as a
+B<regex>(7)
+regular expression.
+If you add ‘B</d>’ to the search expression, dselect will also
+search in descriptions.
+If you add ‘B</i>’ the search will be case insensitive.
+You may combine these two suffixes like this: ‘B</id>’.
+Repeated searching is accomplished by repeatedly pressing the
+‘B<n>’ or ‘B<\>’ keys, until the wanted package is found.
+If the search reaches the bottom of the list, it wraps to the top
+and continues searching from there.
+
+The list sort order can be varied by pressing
+the ‘B<o>’ and ‘B<O>’ keys repeatedly.
+The following nine sort orderings can be selected:
+
+=over
+
+=over
+
+=item B<alphabet>
+
+=item B<priority+section>
+
+=item B<section+priority>
+
+=item B<available>
+
+=item B<available+priority>
+
+=item B<available+section>
+
+=item B<status>
+
+=item B<status+priority>
+
+=item B<status+section>
+
+=back
+
+=back
+
+Where not listed above explicitly, alphabetic order is used as
+the final subordering sort key.
+
+=head2 Altering selections
+
+The requested selection state of individual packages may be
+altered with the following commands:
+
+=over
+
+=over
+
+=item B<+, Insert>    install or upgrade
+
+=item B<=, H>         hold in present state and version
+
+=item B<:, G>         unhold: upgrade or leave uninstalled
+
+=item B<-, Delete>    remove, but leave configuration
+
+=item B<_>            remove & purge configuration
+
+=back
+
+=back
+
+When the change request results in one or more unsatisfied depends
+or conflicts, B<dselect> prompts the user with a dependency resolution
+screen. This will be further explained below.
+
+It is also possible to apply these commands to groups of package
+selections, by pointing the cursor bar onto a group header. The
+exact grouping of packages is dependent on the current list ordering
+settings.
+
+Proper care should be taken when altering large groups of selections,
+because this can instantaneously create large numbers of unresolved
+depends or conflicts, all of which will be listed in one dependency
+resolution screen, making them very hard to handle. In practice,
+only hold and unhold operations are useful when applied to groups.
+
+=head2 Resolving depends and conflicts
+
+When the change request results in one or more unsatisfied depends
+or conflicts, B<dselect> prompts the user with a dependency resolution
+screen. First however, an informative help screen is displayed.
+
+The top half of this screen lists all the packages that will have
+unresolved depends or conflicts, as a result of the requested change,
+and all the packages whose installation can resolve any of these
+depends or whose removal can resolve any of the conflicts.
+The bottom half defaults to show the depends or conflicts that
+cause the currently selected package to be listed.
+
+When the sublist of packages is displayed initially, B<dselect>
+may have already set the requested selection status of some of the
+listed packages, in order to resolve the depends or conflicts that
+caused the dependency resolution screen to be displayed. Usually,
+it is best to follow up the suggestions made by B<dselect>.
+
+The listed packages' selection state may be reverted to the original
+settings, as they were before the unresolved depends or conflicts
+were created, by pressing the ‘B<R>’ key.
+By pressing the ‘B<D>’ key, the automatic suggestions are reset,
+but the change that caused the dependency resolution screen to be prompted
+is kept as requested.
+Finally, by pressing ‘B<U>’, the selections are again set to the
+automatic suggestion values.
+
+=head2 Establishing the requested selections
+
+By pressing B<enter>, the currently displayed set of selections
+is accepted. If B<dselect> detects no unresolved depends as a result
+of the requested selections, the new selections will be set.
+However, if there are any unresolved depends, B<dselect> will again
+prompt the user with a dependency resolution screen.
+
+To alter a set of selections that creates unresolved depends or
+conflicts and forcing B<dselect> to accept it, press the ‘B<Q>’
+key. This sets the selections as specified by the user,
+unconditionally. Generally, don't do this unless you've read
+the fine print.
+
+The opposite effect, to back out any selections change requests and
+go back to the previous list of selections, is attained by pressing
+the ‘B<X>’ or B<escape> keys. By repeatedly pressing these
+keys, any possibly detrimental changes to the requested package
+selections can be backed out completely to the last established
+settings.
+
+If you mistakenly establish some settings and wish to revert all the
+selections to what is currently installed on the system, press the
+‘B<C>’ key.
+This is somewhat similar to using the unhold command on all packages,
+but provides a more obvious panic button in cases where the user
+pressed B<enter> by accident.
+
+=head1 EXIT STATUS
+
+=over
+
+=item B<0>
+
+The requested command was successfully performed.
+
+=item B<2>
+
+Fatal or unrecoverable error due to invalid command-line usage, or
+interactions with the system, such as accesses to the database,
+memory allocations, etc.
+
+=back
+
+=head1 ENVIRONMENT
+
+=over
+
+=item B<DPKG_ROOT>
+
+If set and the B<--instdir> or B<--root> options have not been specified,
+it will be used as the filesystem root directory (since dpkg 1.21.0).
+
+=item B<DPKG_ADMINDIR>
+
+If set and the B<--admindir> or B<--root> option have not been specified,
+it will be used as the B<dpkg> database directory (since dpkg 1.21.0).
+
+=item B<HOME>
+
+If set, B<dselect> will use it as the directory from which to read the
+user specific configuration file.
+
+=back
+
+=head1 BUGS
+
+The
+B<dselect>
+package selection interface is confusing to some new users.
+Reportedly, it even makes seasoned kernel developers cry.
+
+The documentation is lacking.
+
+There is no help option in the main menu.
+
+The visible list of available packages cannot be reduced.
+
+The built in access methods can no longer stand up to current quality
+standards. Use the access method provided by B<apt>(8), it is not only not
+broken, it is also much more flexible than the built in access methods.
+
+=head1 SEE ALSO
+
+B<dpkg>(1),
+B<apt>(8),
+B<sources.list>(5),
+B<deb>(5).
-- 
cgit v1.2.3