Bug#796662: installation-guide: rethinking priorities
Source: installation-guide
Version: 20150528
Severity: minor
Tags: d-i patch
Again following up #794936, here's my third and final bugreport for a
big clear individual issue before I start on a general proofreading
sweep.
The jargon of "low priority installs" is just plain demented.
Lowering the priority of an install would mean declaring it less
urgent, but asking for "expert mode" doesn't do that; it doesn't even
cause prompts to have a lower debconf priority (so that they're less
likely to be shown). What it does is lower the cutoff on the
filtering-by-priority applied to debconf prompts!
Unfortunately I can't find a good single English word that conveys
this - we might perhaps say that expert mode is a "low handholdiness"
or "low automation" or "low simplification" install, but really what's
needed is for debconf to be fixed so that it works entirely the other
way around, with "debconf/prompting=high" meaning an expert-mode
install. Alas, that's never going to happen - for a start it would
break everybody's preseeding setups.
Instead what I've gone for in my patch is the longwinded option, using
various circumlocutions based on the idea that expert mode means
having the "prompting cutoff" set to "low". This may be hard to
follow, but that's still an improvement on having a natural and
straightforward interpretation that's completely wrong. Constructive
alternatives gladly accepted.
In this case since I'm editing multiple files I've made this a minimal
patch, ignoring the grammar errors in neighbouring lines.
Annotated walkthrough:
> Index: appendix/pppoe.xml
> ===================================================================
> --- appendix/pppoe.xml (revision 70037)
> +++ appendix/pppoe.xml (working copy)
> @@ -56,8 +56,9 @@
> <para>
>
> The <classname>ppp-udeb</classname> component is loaded as one of
> -the additional components in this step. If you want to install at
> -medium or low priority (expert mode), you can also manually select
> +the additional components in this step. If you want to install with
> +the prompting cutoff set to <quote>medium</quote> or
> +<quote>low</quote> (expert mode), you can also manually select
> the <classname>ppp-udeb</classname> instead of entering the
> <quote>modules</quote> parameter at the boot prompt.
A straightforward case. As well as complicating the terminology I'm
consistently putting quotes around the names of the levels.
(Meanwhile, appendix/chroot-install.xml talks about priorities but
means something completely different by them: *package* priorities.
We really shouldn't be using the same word in two different important
technical senses at the same time!)
> Index: appendix/preseed.xml
> ===================================================================
> --- appendix/preseed.xml (revision 70037)
> +++ appendix/preseed.xml (working copy)
> @@ -127,7 +127,8 @@
>
> Obviously, any questions that have been processed before the
> preconfiguration file is loaded cannot be preseeded (this will include
> -questions that are only displayed at medium or low priority, like the
> +questions that are only displayed when the prompting cutoff is set to
> +<quote>medium</quote> or <quote>low</quote>, like the
> first hardware detection run). A not so convenient way to avoid these
> questions from being asked is to preseed them through the boot parameters,
> as described in <xref linkend="preseed-bootparms"/>.
Another simple case.
> @@ -139,7 +140,8 @@
> mode. This delays questions that would normally be asked too early for
> preseeding (i.e. language, country and keyboard selection) until after
> the network comes up, thus allowing them to be preseeded. It also runs
> -the installation at critical priority, which avoids many unimportant
> +the installation with the prompting cutoff set to
> +<quote>critical</quote>, which avoids many unimportant
> questions. See <xref linkend="preseed-auto"/> for details.
>
> </para></important>
An installation "at critical priority" would be one I'm prepared to
put a lot of effort into, not one that requires no input from me.
> @@ -512,7 +514,7 @@
> <literal>true</literal> delays the
> locale and keyboard questions until after there has been a chance to
> preseed them, while <literal>priority</literal> is an alias for
> -<literal>debconf/priority</literal> and setting it to
> +<literal>debconf/priority</literal> and setting the cutoff to
> <literal>critical</literal> stops any questions with a lower priority
> from being asked.
We can't fix this properly, but we can make it clearer.
(Meanwhile, boot-installer/parameters.xml has definitions of the boot
parameter "debconf/priority", but unless we can think of a way of
renaming that it'll have to stay as it is.)
(Then boot-installer/powerpc.xml talks about priorities but means that
in the ordinary English sense of the word.)
> Index: using-d-i/modules/apt-setup.xml
> ===================================================================
> --- using-d-i/modules/apt-setup.xml (revision 70037)
> +++ using-d-i/modules/apt-setup.xml (working copy)
> @@ -36,7 +36,7 @@
>
> </para><para>
>
> -If you are installing at default priority, the installer will largely
> +If you are installing with a default prompting cutoff, the installer will largely
> take care of the configuration automatically, based on the installation
> method you are using and possibly using choices made earlier in the
> installation. In most cases the installer will automatically add a security
If I am installing "at default priority", that means it's a routine
task. In this case that natural misinterpretation works well enough
that readers won't realise it's wrong, making them even more confused
when it falls apart later in the same file:
> @@ -45,7 +45,7 @@
>
> </para><para>
>
> -If you are installing at a lower priority (e.g. in expert mode), you will
> +If you are installing with a lower prompting cutoff (e.g. in expert mode), you will
> be able to make more decisions yourself. You can choose whether or not to
> use the security and/or stable-updates services, and you can choose to
> add packages from the <quote>contrib</quote> and <quote>non-free</quote>
(Does it actually mean "e.g." there or should it be "i.e."? Is there
anything to "expert mode" beyond the "debconf/priority=low" setting?)
> Index: using-d-i/modules/base-installer.xml
> ===================================================================
> --- using-d-i/modules/base-installer.xml (revision 70037)
> +++ using-d-i/modules/base-installer.xml (working copy)
> @@ -18,9 +18,9 @@
>
> </para><para>
>
> -As part of the installation, a &arch-kernel; kernel will be installed. At the default
> -priority, the installer will choose one for you that best matches your
> -hardware. In lower priority modes, you will be able to choose from a list
> +As part of the installation, a &arch-kernel; kernel will be installed. With the
> +default prompting cutoff, the installer will choose one for you that best matches your
> +hardware. With a lower cutoff, you will be able to choose from a list
> of available kernels.
>
> </para><para>
This one makes me wish I could think of a replacement for the word
"cutoff" that more clearly implied the fact that the filter is a
minimum rather than a maximum level, but I can't find one.
> Index: using-d-i/modules/localechooser.xml
> ===================================================================
> --- using-d-i/modules/localechooser.xml (revision 70037)
> +++ using-d-i/modules/localechooser.xml (working copy)
> @@ -77,7 +77,8 @@
> locale for the installed system<footnote>
>
> <para>
> -At medium and low priority you can always select your preferred locale from
> +With the prompting cutoff set to <quote>medium</quote> or
> +<quote>low</quote>, you can always select your preferred locale from
> those available for the selected language (if there's more than one).
> </para>
A straightforward one.
> @@ -91,7 +92,7 @@
>
> </para><para>
>
> -If you are installing at low priority, you will have the option
> +If you are installing with the filtering cutoff set to <quote>low</low>, you will have the option
> of selecting additional locales, including so-called <quote>legacy</quote>
> locales<footnote>
And another.
> Index: using-d-i/modules/network-console.xml
> ===================================================================
> --- using-d-i/modules/network-console.xml (revision 70037)
> +++ using-d-i/modules/network-console.xml (working copy)
> @@ -19,7 +19,8 @@
> This component is not loaded into the main installation menu by default,
> so you have to explicitly ask for it.
>
> -If you are installing from CD, you need to boot with medium priority or
> +If you are installing from CD, you need to boot the installer with the
> +prompting cutoff set to <quote>medium</quote> or
> otherwise invoke the main installation menu and choose <guimenuitem>Load
> installer components from CD</guimenuitem> and from the list of
> additional components select <guimenuitem>network-console: Continue
(*I* don't need to boot!)
> Index: using-d-i/modules/partman.xml
> ===================================================================
> --- using-d-i/modules/partman.xml (revision 70037)
> +++ using-d-i/modules/partman.xml (working copy)
> @@ -47,8 +47,9 @@
> Defaults may vary as well. The type of partition table used by default
> can for example be different for large capacity hard disks than for
> smaller hard disks.
> -Some options can only be changed when installing at medium or low debconf
> -priority; at higher priorities sensible defaults will be used.
> +Some options can only be changed when installing with the prompting
> +cutoff set to <quote>medium</quote> or <quote>low</quote>; with higher
> +cutoffs sensible defaults will be used.
>
> </para><para arch="linux-any">
This has the bonus flaw of explicitly referring to the setting as the
*debconf* priority, which makes it even harder to distinguish clearly
between the debconf-priority values on the individual questions and
DI's prompt-filtering-by-debconf-priority setting.
(Besides, it's usually a mistake to refer to debconf when you don't
have to - it's meant to work invisibly behind the scenes, without
users ever needing to have their attention drawn to its presence.)
>
> @@ -143,7 +144,8 @@
> <emphasis>reiserfs</emphasis> (optional; not available on all architectures)
> </para><para>
> Support for the Reiser file system is no longer available by default.
> - When the installer is running at medium or low debconf priority it can
> + When the installer is running with the prompting cutoff set to
> + <quote>medium</quote> or <quote>low</quote> it can
> be enabled by selecting the <classname>partman-reiserfs</classname>
> component. Only version 3 of the file system is supported.
> </para></listitem>
This was again focussing the spotlight on the stagehand.
(Meanwhile, using-d-i/modules/pkgsel.xml talks about priorities but
again means the other kind.)
> Index: using-d-i/modules/tzsetup.xml
> ===================================================================
> --- using-d-i/modules/tzsetup.xml (revision 70037)
> +++ using-d-i/modules/tzsetup.xml (working copy)
> @@ -14,7 +14,8 @@
>
> </para><para>
>
> -In expert mode or when installing at medium priority, you will have the
> +When installing with the prompting cutoff set to <quote>medium</quote>
> +or <quote>low</quote> (e.g. in expert mode), you will have the
> additional option to select <quote>Coordinated Universal Time</quote> (UTC)
> as time zone.
This was a strange way of putting it, as if expert mode and "priority"
were two completely independent options.
> Index: using-d-i/modules/user-setup.xml
> ===================================================================
> --- using-d-i/modules/user-setup.xml (revision 70037)
> +++ using-d-i/modules/user-setup.xml (working copy)
> @@ -4,7 +4,7 @@
> <sect3 id="user-setup-root">
> <title>Set the Root Password</title>
>
> -<!-- TODO: Document sudo setup (no root password); medium/low prio only -->
> +<!-- TODO: Document sudo setup (no root password); debconf/priority=(medium|low) only -->
>
> <para>
Just futureproofing a comment.
> Index: using-d-i/using-d-i.xml
> ===================================================================
> --- using-d-i/using-d-i.xml (revision 70037)
> +++ using-d-i/using-d-i.xml (working copy)
> @@ -10,8 +10,9 @@
> The &debian; Installer consists of a number of special-purpose
> components to perform each installation task. Each component performs
> its task, asking the user questions as necessary to do its job.
> -The questions themselves are given priorities, and the priority
> -of questions to be asked is set when the installer is started.
> +The questions themselves are given priorities, and when the installer
> +is started it sets a cutoff level to determine which questions will be
> +asked.
>
> </para><para>
Finally we get to the file where it actually explains things, but it
does so rather clumsily. First we're told that all the questions are
assigned individual priorities, though we aren't told when this
happens; then we're told that the priority of some subset of questions
(the ones that are to be asked) is assigned at a particular time. Or
no, wait, that's not it. It means that when the installer is started,
it picks a priority level, and only asks the questions with a matching
priority. So for instance if it picks "low", it won't ask the
high-priority questions. No, still not right...
Instead make it clear that the second step is creating a threshold.
This isn't a complete explanation, but the rest comes later.
> @@ -46,7 +47,8 @@
> where each step is controlled by the user rather than the installer
> performing each step automatically in sequence. To use the installer
> in a manual, menu-driven way, add the boot argument
> -<userinput>priority=medium</userinput>.
> +<userinput>priority=medium</userinput>. This resets the prompting cutoff so
> +that questions of priority <quote>medium</quote> (or higher) will be shown.
>
> </para><para>
Add the actual explanation that was being skipped here.
> @@ -182,11 +184,10 @@
>
> Shows the list of components to the user during installer operation,
> and starts a component when it is selected. Main-menu's
> -questions are set to priority medium, so if your priority is set to
> -high or critical (high is the default), you will not see the menu. On
> -the other hand, if there is an error which requires your intervention,
> -the question priority may be downgraded temporarily to allow you
> -to resolve the problem, and in that case the menu may appear.
> +questions are set to priority <quote>medium</quote>, so if the
> +installer's prompting cutoff is set to <quote>high</quote> or
> +<quote>critical</quote> (<quote>high</quote> is the
> +default), you will not see the menu unless something goes wrong.
>
> </para><para>
I've cut a chunk out here since it seems to be badly confused. It
claims "the question priority may be downgraded", which is backwards.
It might mean to say that a question's priority level is temporarily
*raised* or that the prompting cutoff level is temporarily *lowered*;
I would guess it's the latter, but it's hard to be sure.
My preferred solution to this mess is to throw away the unnecessary
implementation details. The only thing that matters here is that I
won't see the menu unless something goes wrong - in which case, by
implication, I will see the menu.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Index: appendix/pppoe.xml
===================================================================
--- appendix/pppoe.xml (revision 70037)
+++ appendix/pppoe.xml (working copy)
@@ -56,8 +56,9 @@
<para>
The <classname>ppp-udeb</classname> component is loaded as one of
-the additional components in this step. If you want to install at
-medium or low priority (expert mode), you can also manually select
+the additional components in this step. If you want to install with
+the prompting cutoff set to <quote>medium</quote> or
+<quote>low</quote> (expert mode), you can also manually select
the <classname>ppp-udeb</classname> instead of entering the
<quote>modules</quote> parameter at the boot prompt.
Index: appendix/preseed.xml
===================================================================
--- appendix/preseed.xml (revision 70037)
+++ appendix/preseed.xml (working copy)
@@ -127,7 +127,8 @@
Obviously, any questions that have been processed before the
preconfiguration file is loaded cannot be preseeded (this will include
-questions that are only displayed at medium or low priority, like the
+questions that are only displayed when the prompting cutoff is set to
+<quote>medium</quote> or <quote>low</quote>, like the
first hardware detection run). A not so convenient way to avoid these
questions from being asked is to preseed them through the boot parameters,
as described in <xref linkend="preseed-bootparms"/>.
@@ -139,7 +140,8 @@
mode. This delays questions that would normally be asked too early for
preseeding (i.e. language, country and keyboard selection) until after
the network comes up, thus allowing them to be preseeded. It also runs
-the installation at critical priority, which avoids many unimportant
+the installation with the prompting cutoff set to
+<quote>critical</quote>, which avoids many unimportant
questions. See <xref linkend="preseed-auto"/> for details.
</para></important>
@@ -512,7 +514,7 @@
<literal>true</literal> delays the
locale and keyboard questions until after there has been a chance to
preseed them, while <literal>priority</literal> is an alias for
-<literal>debconf/priority</literal> and setting it to
+<literal>debconf/priority</literal> and setting the cutoff to
<literal>critical</literal> stops any questions with a lower priority
from being asked.
Index: using-d-i/modules/apt-setup.xml
===================================================================
--- using-d-i/modules/apt-setup.xml (revision 70037)
+++ using-d-i/modules/apt-setup.xml (working copy)
@@ -36,7 +36,7 @@
</para><para>
-If you are installing at default priority, the installer will largely
+If you are installing with a default prompting cutoff, the installer will largely
take care of the configuration automatically, based on the installation
method you are using and possibly using choices made earlier in the
installation. In most cases the installer will automatically add a security
@@ -45,7 +45,7 @@
</para><para>
-If you are installing at a lower priority (e.g. in expert mode), you will
+If you are installing with a lower prompting cutoff (e.g. in expert mode), you will
be able to make more decisions yourself. You can choose whether or not to
use the security and/or stable-updates services, and you can choose to
add packages from the <quote>contrib</quote> and <quote>non-free</quote>
Index: using-d-i/modules/base-installer.xml
===================================================================
--- using-d-i/modules/base-installer.xml (revision 70037)
+++ using-d-i/modules/base-installer.xml (working copy)
@@ -18,9 +18,9 @@
</para><para>
-As part of the installation, a &arch-kernel; kernel will be installed. At the default
-priority, the installer will choose one for you that best matches your
-hardware. In lower priority modes, you will be able to choose from a list
+As part of the installation, a &arch-kernel; kernel will be installed. With the
+default prompting cutoff, the installer will choose one for you that best matches your
+hardware. With a lower cutoff, you will be able to choose from a list
of available kernels.
</para><para>
Index: using-d-i/modules/localechooser.xml
===================================================================
--- using-d-i/modules/localechooser.xml (revision 70037)
+++ using-d-i/modules/localechooser.xml (working copy)
@@ -77,7 +77,8 @@
locale for the installed system<footnote>
<para>
-At medium and low priority you can always select your preferred locale from
+With the prompting cutoff set to <quote>medium</quote> or
+<quote>low</quote>, you can always select your preferred locale from
those available for the selected language (if there's more than one).
</para>
@@ -91,7 +92,7 @@
</para><para>
-If you are installing at low priority, you will have the option
+If you are installing with the filtering cutoff set to <quote>low</low>, you will have the option
of selecting additional locales, including so-called <quote>legacy</quote>
locales<footnote>
Index: using-d-i/modules/network-console.xml
===================================================================
--- using-d-i/modules/network-console.xml (revision 70037)
+++ using-d-i/modules/network-console.xml (working copy)
@@ -19,7 +19,8 @@
This component is not loaded into the main installation menu by default,
so you have to explicitly ask for it.
-If you are installing from CD, you need to boot with medium priority or
+If you are installing from CD, you need to boot the installer with the
+prompting cutoff set to <quote>medium</quote> or
otherwise invoke the main installation menu and choose <guimenuitem>Load
installer components from CD</guimenuitem> and from the list of
additional components select <guimenuitem>network-console: Continue
Index: using-d-i/modules/partman.xml
===================================================================
--- using-d-i/modules/partman.xml (revision 70037)
+++ using-d-i/modules/partman.xml (working copy)
@@ -47,8 +47,9 @@
Defaults may vary as well. The type of partition table used by default
can for example be different for large capacity hard disks than for
smaller hard disks.
-Some options can only be changed when installing at medium or low debconf
-priority; at higher priorities sensible defaults will be used.
+Some options can only be changed when installing with the prompting
+cutoff set to <quote>medium</quote> or <quote>low</quote>; with higher
+cutoffs sensible defaults will be used.
</para><para arch="linux-any">
@@ -143,7 +144,8 @@
<emphasis>reiserfs</emphasis> (optional; not available on all architectures)
</para><para>
Support for the Reiser file system is no longer available by default.
- When the installer is running at medium or low debconf priority it can
+ When the installer is running with the prompting cutoff set to
+ <quote>medium</quote> or <quote>low</quote> it can
be enabled by selecting the <classname>partman-reiserfs</classname>
component. Only version 3 of the file system is supported.
</para></listitem>
Index: using-d-i/modules/tzsetup.xml
===================================================================
--- using-d-i/modules/tzsetup.xml (revision 70037)
+++ using-d-i/modules/tzsetup.xml (working copy)
@@ -14,7 +14,8 @@
</para><para>
-In expert mode or when installing at medium priority, you will have the
+When installing with the prompting cutoff set to <quote>medium</quote>
+or <quote>low</quote> (e.g. in expert mode), you will have the
additional option to select <quote>Coordinated Universal Time</quote> (UTC)
as time zone.
Index: using-d-i/modules/user-setup.xml
===================================================================
--- using-d-i/modules/user-setup.xml (revision 70037)
+++ using-d-i/modules/user-setup.xml (working copy)
@@ -4,7 +4,7 @@
<sect3 id="user-setup-root">
<title>Set the Root Password</title>
-<!-- TODO: Document sudo setup (no root password); medium/low prio only -->
+<!-- TODO: Document sudo setup (no root password); debconf/priority=(medium|low) only -->
<para>
Index: using-d-i/using-d-i.xml
===================================================================
--- using-d-i/using-d-i.xml (revision 70037)
+++ using-d-i/using-d-i.xml (working copy)
@@ -10,8 +10,9 @@
The &debian; Installer consists of a number of special-purpose
components to perform each installation task. Each component performs
its task, asking the user questions as necessary to do its job.
-The questions themselves are given priorities, and the priority
-of questions to be asked is set when the installer is started.
+The questions themselves are given priorities, and when the installer
+is started it sets a cutoff level to determine which questions will be
+asked.
</para><para>
@@ -46,7 +47,8 @@
where each step is controlled by the user rather than the installer
performing each step automatically in sequence. To use the installer
in a manual, menu-driven way, add the boot argument
-<userinput>priority=medium</userinput>.
+<userinput>priority=medium</userinput>. This resets the prompting cutoff so
+that questions of priority <quote>medium</quote> (or higher) will be shown.
</para><para>
@@ -182,11 +184,10 @@
Shows the list of components to the user during installer operation,
and starts a component when it is selected. Main-menu's
-questions are set to priority medium, so if your priority is set to
-high or critical (high is the default), you will not see the menu. On
-the other hand, if there is an error which requires your intervention,
-the question priority may be downgraded temporarily to allow you
-to resolve the problem, and in that case the menu may appear.
+questions are set to priority <quote>medium</quote>, so if the
+installer's prompting cutoff is set to <quote>high</quote> or
+<quote>critical</quote> (<quote>high</quote> is the
+default), you will not see the menu unless something goes wrong.
</para><para>
Reply to: