Extend the documentation of apt-setup, especially the decision whether or

not to use a network mirror. Document selection of services.

1 files changed, 116 insertions, 5 deletions

diff --git a/en/using-d-i/modules/apt-setup.xml b/en/using-d-i/modules/apt-setup.xml
index 76d530223..3116f10de 100644
--- a/en/using-d-i/modules/apt-setup.xml
+++ b/en/using-d-i/modules/apt-setup.xml
@@ -32,11 +32,122 @@ recommended utility for package management.
 
 </para><para>
 
-<command>apt</command> must be configured so that it knows where to retrieve
-packages from. The installer largely takes care of this automatically based on
-what it knows about your installation medium. The results of this configuration
-are written to the file <filename>/etc/apt/sources.list</filename>, and you can
-examine and edit it to your liking after the install is complete.
+<command>apt</command> must be configured so that it knows from where to
+retrieve packages. The results of this configuration are written to the
+file <filename>/etc/apt/sources.list</filename>. You can examine and edit
+this file to your liking after the installation is complete.
+
+</para><para>
+
+If you are installing at default priority, 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
+mirror and, if you are installing the stable distribution, a mirror for the
+<quote>volatile</quote> update service.
+
+</para><para>
+
+If you are installing at a lower priority (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 volatile update services, and you can choose to
+add packages from the <quote>contrib</quote> and <quote>non-free</quote>
+sections of the archive.
+
+</para>
+
+    <sect4 id="apt-setup-mirror">
+    <title>Using a network mirror</title>
+
+<para>
+
+One question that will be asked in most cases is whether or not to use a
+network mirror as a source for packages. In most cases the default answer
+should be fine, but there are some exceptions.
+
+</para><para>
+
+If you are <emphasis>not</emphasis> installing from a full CD or DVD or
+using a full CD/DVD image, you really should use a network mirror as
+otherwise you will end up with only a very minimal system. However, if you
+have a limited Internet connection it is best <emphasis>not</emphasis>
+to select the <literal>desktop</literal> task in the next step of the
+installation.
+
+</para><para>
+
+If you are installing from a full CD or using a CD image (not DVD), using a
+network mirror is not required, but is still strongly recommended because a
+single CD contains only a fairly limited number of packages. The installer
+currently does not support using multiple CD or DVD images during the
+installation<footnote>
+
+Adding that option is planned.
+
+</footnote>. If you have a limited Internet connection it may still be best
+to <emphasis>not</emphasis> select a network mirror here, but to finish the
+installation using only what's available on the CD and install additional
+packages after the installation (i.e. after you have rebooted into the new
+system).
+
+</para><para>
+
+If you are installing from a DVD or using a DVD image, the need to use a
+network mirror is a lot smaller, but there is still a chance that some
+packages that are part of the tasks you select in the next step will not
+be included on the first DVD. This is especially true if you are installing
+in another language than English: a number of font and localization packages
+are known to be on the second DVD. So, if you have a reasonable Internet
+connection it is still advisable to use a network mirror.
+
+</para><para>
+
+<!-- This should probably be documented a bit more extensively in
+     post-install instead. -->
+To install additional packages after the installation you have two options:
+
+<orderedlist>
+<listitem><para>
+
+if you have additional CD/DVD images available (from same set as the
+installation CD/DVD you are using), you can add those to the
+<filename>sources.list</filename> using <command>apt-cdrom</command>;
+
+</para></listitem>
+<listitem><para>
+
+manually add a mirror to the <filename>sources.list</filename> using an
+editor.
+
+</para></listitem>
+</orderedlist>
+
+You can then use one of the package management front-ends to select and
+install additional packages<footnote>
+
+It is possible to add both additional CDs or DVDs <emphasis>and</emphasis>
+a network mirror in <filename>/etc/apt/sources.list</filename>. Also adding
+a network mirror has the advantage that it will make updates of packages in
+point releases of the distribution available for installation.
+
+</footnote>.
+
+</para><para>
+
+In summary: selecting a network mirror is generally a good idea, except
+if you do not have a good Internet connection. If the current version of
+a package is available on the CD/DVD, the installer will alway use that.
+The amount of data that will be downloaded if you do select a mirror thus
+depends on a) the tasks you select in the next step of the installation, b)
+which packages are needed for those tasks, and c) which of those packages
+are present on the CD/DVD.
+
+</para><para>
+
+Note that even if you choose not to use a network mirror, some packages
+may still be downloaded from the Internet if there is a security or
+volatile update available for them and those services have been configured.
 
 </para>
+</sect4>
    </sect3>