- Move documentation on preseeding to separate appendix for etch

- Use new, more flexible perl script to extract example preseed file from new appendix

4 files changed, 353 insertions, 520 deletions

diff --git a/en/appendix/example-preseed-etch.xml b/en/appendix/example-preseed-etch.xml
deleted file mode 100644
index bbd13427d..000000000
--- a/en/appendix/example-preseed-etch.xml
+++ /dev/null
@@ -1,374 +0,0 @@
-<!-- retain these comments for translator revision tracking -->
-<!-- $Id$ -->
-
-<informalexample condition="etch"><screen>
-#### Startup.
-
-# To use a preseed file, you'll first need to boot the installer,
-# and tell it what preseed file to use. This is done by passing the
-# kernel a boot parameter, either manually at boot or by editing the
-# syslinux.cfg (or similar) file and adding the parameter to the end
-# of the append line(s) for the kernel.
-#
-# If you're netbooting, use this:
-#   preseed/url=http://host/path/to/preseed
-# If you're remastering a CD, you could use this:
-#   preseed/file=/cdrom/preseed
-# If you're installing from USB media, use this, and put the preseed file
-# in the toplevel directory of the USB stick.
-#   preseed/file=/hd-media/preseed
-#
-# If you feel comfortable modifying the installer's initrd image,
-# you can also place a preseed file in the root directory of the initrd's
-# filesystem, named "preseed.cfg" -- the installer will always use this
-# file if it is present. Otherwise, be sure to copy this file to the location
-# you specify.
-#
-# To make sure the installer gets the right preseed file, you can specify
-# a checksum for the file. Currently this needs to be a md5sum, and if
-# specified it must match the file or the installer will refuse to use the
-# file.
-#   preseed/url/checksum=5da499872becccfeda2c4872f9171c3d
-#   preseed/file/checksum=5da499872becccfeda2c4872f9171c3d
-#
-# Some parts of the installation process cannot be automated using
-# some forms of preseeding, because the questions are asked before
-# the preseed file is loaded. For example, if the preseed file is
-# downloaded over the network, the network setup must be done first.
-# One reason to use initrd preseeding is that it allows preseeding
-# of even these early steps of the installation process.
-#
-# If a preseed file cannot be used to preseed some steps, the install can
-# still be fully automated, since you can pass preseed values to the kernel
-# on the command line. Just pass path/to/var=value for any of the preseed
-# variables listed below.
-#
-# While you're at it, you may want to throw a debconf/priority=critical in
-# there, to avoid most questions even if the preseeding below misses some.
-# And you might set the timeout to 1 in syslinux.cfg to avoid needing to hit
-# enter to boot the installer.
-#
-# Note that the 2.4 kernel accepts a maximum of 8 command line options and
-# 8 environment options (including any options added by default for the
-# installer). If these numbers are exceeded, 2.4 kernels will drop any
-# excess options and 2.6 kernels will panic. With kernel 2.6.9 or newer,
-# you can use 32 command line options and 32 environment options.
-#
-# Some of the default options, like 'vga=normal' may be safely removed
-# for most installations, which may allow you to add more options for
-# preseeding.
-
-# To select your language and country, use this setting, but remember
-# that this will only work for initrd based preseeding, for other forms of
-# preseeding you must convert it into a kernel parameter,
-# such as debian-installer/locale=en_US
-d-i debian-installer/locale string en_US
-
-# To select your keyboard, use this setting. Again it will need to be
-# passed as a kernel parameter for most preseed setups.
-d-i console-keymaps-at/keymap select us
-
-#### Network configuration.
-
-# Of course, this won't work if you're loading your preseed file from the
-# network! But it's great if you're booting from CD or USB stick. You can
-# also pass network config parameters in on the kernel params if you are
-# loading preseed files from the network.
-
-# netcfg will choose an interface that has link if possible. This makes it
-# skip displaying a list if there is more than one interface.
-d-i netcfg/choose_interface select auto
-
-# If you have a slow dhcp server and the installer times out waiting for
-# it, this might be useful.
-#d-i netcfg/dhcp_timeout string 60
-
-# If you prefer to configure the network manually, here's how:
-#d-i netcfg/disable_dhcp boolean true
-#d-i netcfg/get_nameservers string 192.168.1.1
-#d-i netcfg/get_ipaddress string 192.168.1.42
-#d-i netcfg/get_netmask string 255.255.255.0
-#d-i netcfg/get_gateway string 192.168.1.1
-#d-i netcfg/confirm_static boolean true
-
-# Note that any hostname and domain names assigned from dhcp take
-# precedence over values set here. However, setting the values still
-# prevents the questions from being shown even if values come from dhcp.
-d-i netcfg/get_hostname string unassigned-hostname
-d-i netcfg/get_domain string unassigned-domain
-
-# Disable that annoying WEP key dialog.
-d-i netcfg/wireless_wep string
-# The wacky dhcp hostname that some ISPs use as a password of sorts.
-#d-i netcfg/dhcp_hostname string radish
-
-#### Mirror settings.
-
-d-i mirror/country string enter information manually
-d-i mirror/http/hostname string http.us.debian.org
-d-i mirror/http/directory string /debian
-d-i mirror/http/proxy string
-
-# What suite of Debian to install.
-#d-i mirror/suite string testing
-# What suite of Debian to use for loading installer components.
-# (Defaults to same as mirror/suite.)
-#d-i mirror/udeb/suite string testing
-
-#### Partitioning.
-
-# If the system has free space you can choose to only partition that space.
-#d-i partman-auto/init_automatically_partition \
-#      select Use the largest continuous free space
-
-# Alternatively, you can specify a disk to partition. The device name can
-# be given in either devfs or traditional non-devfs format.
-# For example, to use the first disk devfs knows of:
-d-i partman-auto/disk string /dev/discs/disc0/disc
-
-# You can choose from any of the predefined partitioning recipes:
-d-i partman-auto/choose_recipe \
-       select All files in one partition (recommended for new users)
-#d-i partman-auto/choose_recipe \
-#       select Separate /home partition
-#d-i partman-auto/choose_recipe \
-#       select Separate /home, /usr, /var, and /tmp partitions
-
-# Or provide a recipe of your own...
-# The recipe format is documented in the file devel/partman-auto-recipe.txt.
-# If you have a way to get a recipe file into the d-i environment, you can
-# just point at it.
-#d-i partman-auto/expert_recipe_file string /hd-media/recipe
-
-# If not, you can put an entire recipe the preseed file in one (logical)
-# line. This example creates a small /boot partition, suitable swap, and
-# uses the rest of the space for the root partition:
-#d-i partman-auto/expert_recipe string                         \
-#      boot-root ::                                            \
-#              40 50 100 ext3                                  \
-#                      $primary{ } $bootable{ }                \
-#                      method{ format } format{ }              \
-#                      use_filesystem{ } filesystem{ ext3 }    \
-#                      mountpoint{ /boot }                     \
-#              .                                               \
-#              500 10000 1000000000 ext3                       \
-#                      method{ format } format{ }              \
-#                      use_filesystem{ } filesystem{ ext3 }    \
-#                      mountpoint{ / }                         \
-#              .                                               \
-#              64 512 300% linux-swap                          \
-#                      method{ swap } format{ }                \
-#              .
-
-# This makes partman automatically partition without confirmation.
-d-i partman/confirm_write_new_label boolean true
-d-i partman/choose_partition \
-       select Finish partitioning and write changes to disk
-d-i partman/confirm boolean true
-
-#### Boot loader installation.
-
-# Grub is the default boot loader (for x86). If you want lilo installed
-# instead, uncomment this:
-#d-i grub-installer/skip boolean true
-
-# This is fairly safe to set, it makes grub install automatically to the MBR
-# if no other operating system is detected on the machine.
-d-i grub-installer/only_debian boolean true
-
-# This one makes grub-installer install to the MBR if if finds some other OS
-# too, which is less safe as it might not be able to boot that other OS.
-d-i grub-installer/with_other_os boolean true
-
-# Alternatively, if you want to install to a location other than the mbr,
-# uncomment and edit these lines:
-#d-i grub-installer/bootdev  string (hd0,0)
-#d-i grub-installer/only_debian boolean false
-#d-i grub-installer/with_other_os boolean false
-
-#### Finishing up the first stage install.
-
-# Avoid that last message about the install being complete.
-d-i prebaseconfig/reboot_in_progress note
-
-# This will prevent the installer from ejecting the CD during the reboot,
-# which is useful in some situations.
-#d-i cdrom-detect/eject boolean false
-
-#### Shell commands.
-
-# d-i preseeding is inherently not secure. Nothing in the installer checks
-# for attempts at buffer overflows or other exploits of the values of a
-# preseed file like this one. Only use preseed files from trusted
-# locations! To drive that home, and because it's generally useful, here's
-# a way to run any shell command you'd like inside the installer,
-# automatically.
-
-# This first command is run as early as possible, just after
-# preseeding is read.
-#d-i preseed/early_command string anna-install some-udeb
-
-# This command is run just before the install finishes, but when there is
-# still a usable /target directory.
-#d-i preseed/late_command string echo foo > /target/etc/bar
-
-# This command is run just as base-config is starting up.
-#base-config base-config/early_command string echo hi mom
-
-# This command is run after base-config is done, just before the login:
-# prompt. This is a good way to install a set of packages you want, or to
-# tweak the configuration of the system.
-#base-config base-config/late_command \
-#      string apt-get install zsh; chsh -s /bin/zsh
-
-###### Preseeding the 2nd stage of the installation.
-
-#### Preseeding base-config.
-
-# Avoid the introductory message.
-base-config base-config/intro note
-
-# Avoid the final message.
-base-config base-config/login note
-
-# If you installed a display manager, but don't want to start it immediately
-# after base-config finishes.
-#base-config base-config/start-display-manager boolean false
-
-# Some versions of the installer can report back on what you've installed.
-# The default is not to report back, but sending reports helps the project
-# determine what software is most popular and include it on CDs.
-#popularity-contest popularity-contest/participate boolean false
-
-#### Clock and time zone setup.
-
-# Controls whether or not the hardware clock is set to UTC.
-d-i clock-setup/utc boolean true
-
-# You may set this to any valid setting for $TZ; see the contents of
-# /usr/share/zoneinfo/ for options.
-d-i time/zone string US/Eastern
-
-#### Account setup.
-
-# To preseed the root password, you have to put it in the clear in this
-# file. That is not a very good idea, use caution!
-#passwd passwd/root-password password r00tme
-#passwd passwd/root-password-again password r00tme
-
-# If you want to skip creation of a normal user account.
-#passwd passwd/make-user boolean false
-
-# Alternatively, you can preseed the user's name and login.
-#passwd passwd/user-fullname string Debian User
-#passwd passwd/username string debian
-# And their password, but use caution!
-#passwd passwd/user-password password insecure
-#passwd passwd/user-password-again password insecure
-
-#### Apt setup.
-
-# This question controls what source the second stage installation uses
-# for packages. Choices are cdrom, http, ftp, filesystem, edit sources list
-# by hand
-base-config apt-setup/uri_type select http
-
-# If you choose ftp or http, you'll be asked for a country and a mirror.
-base-config apt-setup/country select enter information manually
-base-config apt-setup/hostname string http.us.debian.org
-base-config apt-setup/directory string /debian
-# Stop after choosing one mirror.
-base-config apt-setup/another boolean false
-
-# You can choose to install non-free and contrib software.
-#base-config apt-setup/non-free boolean true
-#base-config apt-setup/contrib boolean true
-
-# Do enable security updates.
-base-config apt-setup/security-updates boolean true
-
-#### Package selection.
-
-# You can choose to install any combination of tasks that are available.
-# Available tasks as of this writing include: Desktop environment,
-# Web server, Print server, DNS server, File server, Mail server,
-# SQL database, Laptop, Standard system, manual package selection. The
-# last of those will run aptitude. You can also choose to install no
-# tasks, and force the installation of a set of packages in some other
-# way. We recommend always including the Standard system task.
-tasksel tasksel/first multiselect Desktop environment, Standard system
-#tasksel tasksel/first multiselect Web server, Standard system
-
-#### Mailer configuration.
-
-# During a normal install, exim asks only a few questions. Here's how to
-# avoid even those. More complicated preseeding is possible.
-exim4-config exim4/dc_eximconfig_configtype \
-       select no configuration at this time
-exim4-config exim4/no_config boolean true
-exim4-config exim4/no_config boolean true
-
-# It's a good idea to set this to whatever user account you choose to
-# create. Leaving the value blank results in postmaster mail going to
-# /var/mail/mail.
-exim4-config exim4/dc_postmaster string
-
-#### X Configuration.
-
-# Preseeding Debian's X config is possible, but you probably need to know
-# some details about the video hardware of the machine, since Debian's X
-# configurator does not do fully automatic configuration of everything.
-
-# X can detect the right driver for some cards, but if you're preseeding,
-# you override whatever it chooses. Still, vesa will work most places.
-#xserver-xfree86 xserver-xfree86/config/device/driver select vesa
-
-# A caveat with mouse autodetection is that if it fails, X will retry it
-# over and over. So if it's preseeded to be done, there is a possibility of
-# an infinite loop if the mouse is not autodetected.
-#xserver-xfree86 xserver-xfree86/autodetect_mouse boolean true
-
-# Monitor autodetection is recommended.
-xserver-xfree86 xserver-xfree86/autodetect_monitor boolean true
-# Uncomment if you have an LCD display.
-#xserver-xfree86 xserver-xfree86/config/monitor/lcd boolean true
-# X has three configuration paths for the monitor. Here's how to preseed
-# the "medium" path, which is always available. The "simple" path may not
-# be available, and the "advanced" path asks too many questions.
-xserver-xfree86 xserver-xfree86/config/monitor/selection-method \
-       select medium
-xserver-xfree86 xserver-xfree86/config/monitor/mode-list \
-       select 1024x768 @ 60 Hz
-
-#### Everything else.
-
-# Depending on what software you choose to install, or if things go wrong
-# during the installation process, it's possible that other questions may
-# be asked. You can preseed those too, of course. To get a list of every
-# possible question that could be asked during an install, do an
-# installation, and then run these commands:
-#   debconf-get-selections --installer > file
-#   debconf-get-selections >> file
-
-# If you like, you can include other preseed files into this one.
-# Any settings in those files will override pre-existing settings from this
-# file. More that one file can be listed, separated by spaces; all will be
-# loaded. The included files can have preseed/include directives of their
-# own as well. Note that if the filenames are relative, they are taken from
-# the same directory as the preseed file that includes them.
-#d-i preseed/include string x.cfg
-
-# The installer can optionally verify checksums of preseed files before
-# using them. Currently only md5sums are supported, list the md5sums
-# in the same order as the list of files to include.
-#d-i preseed/include/checksum string 5da499872becccfeda2c4872f9171c3d
-
-# More flexibly, this runs a shell command and if it outputs the names of
-# preseed files, includes those files. 
-#d-i preseed/include_command \
-#      string echo if [ "`hostname`" = bob ]; then echo bob.cfg; fi
-
-# To check the format of your preseed file before performing an install,
-# you can use debconf-set-selections:
-#   debconf-set-selections -c preseed.cfg
-</screen></informalexample>
diff --git a/en/appendix/example-preseed.xml b/en/appendix/example-preseed.xml
index c5fcd460b..8fc4f722c 100644
--- a/en/appendix/example-preseed.xml
+++ b/en/appendix/example-preseed.xml
@@ -1,7 +1,7 @@
 <!-- retain these comments for translator revision tracking -->
 <!-- $Id$ -->
 
-<sect1 id="example-preseed">
+<sect1 id="example-preseed" condition="sarge">
 <title>Preconfiguration File Example</title>
 
 <para>
@@ -12,7 +12,7 @@ may want to uncomment some of the lines before using the file.
 
 </para>
 
-<note condition="sarge"><para>
+<note><para>
 
 In order to be able to properly present this example in the manual, we've had
 to split some lines. This is indicated by the use of the line-continuation-character
@@ -26,14 +26,9 @@ A <quote>clean</quote> example file is available from &urlset-example-preseed;.
 
 </para></note>
 
-<para condition="etch">
-
-The example file is also available from &urlset-example-preseed;.
-
-</para><para>
+<para>
 
 &example-preseed-sarge.xml;
-&example-preseed-etch.xml;
 
 </para>
 </sect1>
diff --git a/en/appendix/example-preseed-etch-new.xml b/en/appendix/preseed.xml
index 460a1289f..96c3b1c9b 100644
--- a/en/appendix/example-preseed-etch-new.xml
+++ b/en/appendix/preseed.xml
@@ -2,10 +2,17 @@
 <!-- $Id: example-preseed-etch.xml 32158 2005-11-16 01:20:19Z joeyh $ -->
 
 <!--
-Should be renamed to this, but don't want to break link from ch4 now.
-<appendix id="appendix-preseed" condition="etch">
+Be carefull with the format of this file as it is parsed to generate
+the example preseed file.
+In that file all text between <informalexample> tags that have the
+attribute 'role="example"' set is included, except if a 'condition'
+attribute is in force that does not match the specified release or if an
+'arch' attribute is in force that does not match the specified architecture.
+
+Currently only a single variant of the example file is generated (for i386).
 -->
-<appendix id="example-preseed" condition="etch">
+
+<appendix id="appendix-preseed" condition="etch">
 <title>Automating the installation using preseeding</title>
 
 <para>
@@ -20,40 +27,256 @@ example preseed file from &urlset-example-preseed;.
 
 </para>
 
- <sect1 condition="FIXME" id="preseed-intro">
+ <sect1 id="preseed-intro">
  <title>Introduction</title>
+<para>
+
+Preseeding provides a way to set answers to dialogs without having to manually
+enter the answers while the installation is running. This makes it possible to
+fully automate most types of installation and even offers some features not
+available during normal installations.
+
+</para><para>
+
+Using preseeding it is possible to fill in answers to questions asked during
+both the first stage of the installation (before the reboot into the new
+system) and the second stage.
+
+</para>
+
+  <sect2 id="preseed-methods">
+  <title>Preseeding methods</title>
+<para>
+
+There are three methods that can be used for preseeding:
+<firstterm>initrd</firstterm>, <firstterm>file</firstterm> and
+<firstterm>network</firstterm>. Initrd preseeding will work with any
+installation method and gives the fullest coverage, but is requires the most
+preparation. File and network preseeding each can be used with different
+installation methods. With file and network preseeding the first few installer
+questions cannot be preseeded because the preseed configuration file is only
+loaded after they have been asked.
+
+</para><para>
+
+The following table shows which preseeding methods can be used with which
+installation methods.
+
+<informaltable>
+<tgroup cols="4">
+<thead>
+<row>
+  <entry>Installation method</entry><entry>initrd</entry>
+  <entry>file</entry><entry>network</entry>
+</row>
+</thead>
+
+<tbody>
+<row>
+  <entry>CD/DVD based</entry>
+  <entry>yes</entry>
+  <entry>yes</entry>
+  <entry>no</entry>
+</row><row>
+  <entry>netboot</entry>
+  <entry>yes</entry>
+  <entry>no</entry>
+  <entry>yes</entry>
+</row><row>
+  <entry>hd-media <phrase condition="bootable-usb">(including usb-stick)</phrase></entry>
+  <entry>yes</entry>
+  <entry>yes</entry>
+  <entry>no</entry>
+</row><row condition="supports-floppy-boot">
+  <entry>floppy based (cd-drivers)</entry>
+  <entry>yes</entry>
+  <entry>yes</entry>
+  <entry>no</entry>
+</row><row condition="supports-floppy-boot">
+  <entry>floppy based (net-drivers)</entry>
+  <entry>yes</entry>
+  <entry>no</entry>
+  <entry>yes</entry>
+</row><row arch="s390">
+  <entry>generic/tape</entry>
+  <entry>yes</entry>
+  <entry>no</entry>
+  <entry>yes</entry>
+</row>
+</tbody>
+
+</tgroup></informaltable>
+
+</para><para>
+
+An important difference between the preseeding methods is the point at which
+the preseed configuration file is loaded and processed. For initrd preseeding
+this is right at the start of the installation, before the first question is
+even processed. For file preseeding this is after the CD or CD image has been
+loaded. For network preseeding it is only after the network has been
+configured.
+
+</para><para>
+
+In practical terms this means for file and network preseeding that the
+questions about language, country and keyboard selection will already have
+been asked. For network preseeding add to that any questions related to
+network configuration. Some other questions that are only displayed
+at medium or low priority (like the first hardware detection run) will
+already have been processed.
+
+</para><para>
+
+Obviously, any questions that have been processed before the
+preseeding configuration file is loaded, cannot be preseeded. Section
+<xref linkend="preseed-bootparms"/> offers a way to avoid these
+questions being asked.
+
+</para>
+  </sect2>
+
+  <sect2 id="preseed-limitations">
+  <title>Limitations</title>
+<para>
+
+Although most dialogs used by &d-i; can be preseeded using this method,
+there are some notable exceptions. You can (re)partition an entire disk
+or use available free space on a disk; it is not possible to use existing
+partitions. You currently cannot use preseeding to set up RAID and LVM.
+
+</para>
+  </sect2>
+
+  <sect2 id="preseed-debconf">
+  <title>Debconf basics</title>
+<para>
+
+Preseeding makes use of the <classname>debconf</classname> framework. This
+framework is the preferred mechanism used in Debian to interact with the user
+when configuring packages and also forms the heart of &d-i;.
+In the <classname>debconf</classname> framework questions or dialogs are
+based on <firstterm>templates</firstterm>. There are different types of
+templates for different types of questions. The actual questions are
+<quote>generated</quote> from templates at runtime;  multiple questions can
+use the same template.
+
+</para><para>
+
+The following types of templates are relevant for preseeding.
+
+</para>
 
 <itemizedlist>
 <listitem><para>
-  Supports 1st and 2nd stage
+  string: allows the user to type any value
+</para></listitem>
+<listitem><para>
+  password: similar to string but the value typed is not displayed
+</para></listitem>
+<listitem><para>
+  boolean: for yes/no or true/false type of questions
 </para></listitem>
 <listitem><para>
-  Methods: initrd, net, file
+  select: allows the user to select one option from a list
 </para></listitem>
 <listitem><para>
-  Hooks
+  multiselect: allows the user to select zero, one or more options from a list
+</para></listitem>
+<listitem><para>
+  note: used to display a message
+</para></listitem>
+</itemizedlist>
+
+<para>
+
+In &d-i; templates are stored in a readable file
+<filename>/var/lib/templates.dat</filename>. This file contains all fixed
+text and all translations. It can also contain a default value for the
+template. The fixed text can include variables that will be replaced at
+runtime.
+
+</para><para>
+
+Another readable file <filename>/var/lib/questions.dat</filename> is used
+to store the values for variables and the answers given to questions.
+A question always refers to the template used to ask it. For obvious
+security reasons the values for templates of type <quote>password</quote>
+are stored in a separate, non-readable file in the same directory.
+
+</para>
+  </sect2>
+
+  <sect2 id="preseed-hooks">
+  <title>Running custom commands during the installation</title>
+<para>
+
+A very powerfull and flexible option offered by the preseeding tools is the
+ability to run commands or scripts at certain points in the installation.
+See <xref linkend="preseed-shell"/> for details.
+
+</para>
+
+<itemizedlist>
+<listitem><para>
+  <userinput>preseed/early_command</userinput>: is run as soon as the the
+  preseeding configuration file has been loaded
 </para></listitem>
 <listitem><para>
-  Seen flags
+  <userinput>preseed/late_command</userinput>: is run just before the reboot
+  at the end of the first stage of the installation, but before the
+  <filename>/target</filename> filesystem has been unmounted
 </para></listitem>
 <listitem><para>
-  Limitations
+  <userinput>base-config/early_command</userinput>: is run early in the second
+  stage of the installation when <command>base-config</command> is starting up
 </para></listitem>
 <listitem><para>
-  How 2nd stage preseeding works
+  <userinput>base-config/late_command</userinput>: is run at the end of
+  <command>base-config</command>, just before the login prompt
 </para></listitem>
 </itemizedlist>
 
+  </sect2>
+
+  <sect2 id="preseed-seenflag">
+  <title>Using preseeding to change default values</title>
+<para>
+
+It is possible to use preseeding to change the default answer for a
+question, but still have the question asked. To do this the
+<firstterm>seen</firstterm> flag must be reset to <quote>false</quote> after
+setting the value for a template.
+
+</para>
+
+<informalexample><screen>
+d-i foo/bar string value
+d-i foo/bar seen false
+</screen></informalexample>
+
+  </sect2>
  </sect1>
 
  <sect1 id="preseed-using">
  <title>Using preseeding</title>
+<para>
+
+Of course you will first need to create a preseed file and place it in the
+location from where you want to use it. Creating the preseed file is covered
+later in this appendix. Putting it in the correct location is fairly
+straightforward for network preseeding or if you want to read the file off
+a floppy or usb-stick. If you want to include the file on a CD or DVD, you
+will have to remaster the ISO image. How to get the preseed file included
+in the initrd is outside the scope of this document; please consult the
+developers documentation for &d-i;.
+
+</para>
 
   <sect2 id="preseed-loading">
   <title>Loading the preseed file</title>
 <para>
 
-If you using initrd preseeding, you only have to make sure a file named
+If you are using initrd preseeding, you only have to make sure a file named
 <filename>preseed.cfg</filename> is included in the root directory of the
 initrd. The installer will automatically check if this file is present and
 load it.
@@ -62,15 +285,16 @@ load it.
 
 For the other preseeding methods you need to tell the installer what file to
 use when you boot it. This is done by passing the kernel a boot parameter,
-either manually at boot or by editing the <filename>syslinux.cfg</filename>
-(or similar) file and adding the parameter to the end of the append line(s)
-for the kernel.
+either manually at boot time or by editing the bootloader configuration file
+(e.g. <filename>syslinux.cfg</filename>) and adding the parameter to the end
+of the append line(s) for the kernel.
 
 </para><para>
 
-If you do specify the preseed file in the syslinux configuration, you might
-set the timeout to 1 in syslinux.cfg to avoid needing to hit enter to boot
-the installer.
+If you do specify the preseed file in the bootloader configuration, you might
+change the configuration so you don't need to hit enter to boot the installer.
+For syslinux this means setting the timeout to 1 in
+<filename>syslinux.cfg</filename>.
 
 </para><para>
 
@@ -81,19 +305,19 @@ specified it must match the preseed file or the installer will refuse to use it.
 </para>
 
 <informalexample><screen>
-# Boot parameters to specify:
-# - if you're netbooting:
-#   preseed/url=http://host/path/to/preseed
-#   preseed/url/checksum=5da499872becccfeda2c4872f9171c3d
-#
-# - if you're booting a remastered CD:
-#   preseed/file=/cdrom/preseed
-#   preseed/file/checksum=5da499872becccfeda2c4872f9171c3d
-#
-# - if you're installing from USB media (put the preseed file in the
-#   toplevel directory of the USB stick):
-#   preseed/file=/hd-media/preseed
-#   preseed/file/checksum=5da499872becccfeda2c4872f9171c3d
+Boot parameters to specify:
+- if you're netbooting:
+  preseed/url=http://host/path/to/preseed.cfg
+  preseed/url/checksum=5da499872becccfeda2c4872f9171c3d
+
+- if you're booting a remastered CD:
+  preseed/file=/cdrom/preseed.cfg
+  preseed/file/checksum=5da499872becccfeda2c4872f9171c3d
+
+- if you're installing from USB media (put the preseed file in the
+  toplevel directory of the USB stick):
+  preseed/file=/hd-media/preseed.cfg
+  preseed/file/checksum=5da499872becccfeda2c4872f9171c3d
 </screen></informalexample>
 
 <para>
@@ -110,7 +334,7 @@ questions even if the preseeding below misses some.
 <para>
 
 Some parts of the installation process cannot be automated using some forms
-of preseeding, because the questions are asked before the preseed file is
+of preseeding because the questions are asked before the preseed file is
 loaded. For example, if the preseed file is downloaded over the network,
 the network setup must be done first. One reason to use initrd preseeding
 is that it allows preseeding of even these early steps of the installation
@@ -129,7 +353,7 @@ for any of the preseed variables listed in the examples.
 The 2.4 kernel accepts a maximum of 8 command line options and
 8 environment options (including any options added by default for the
 installer). If these numbers are exceeded, 2.4 kernels will drop any
-excess options and 2.6 kernels will panic. With kernel 2.6.9 or newer,
+excess options and 2.6 kernels will panic. For kernel 2.6.9 and later,
 you can use 32 command line options and 32 environment options.
 
 </para></note>
@@ -151,12 +375,27 @@ parameters, even if you delimit them with quotes.
 
  <sect1 condition="FIXME" id="preseed-creating">
  <title>Creating a preseed file</title>
+<para>
+
+The preconfiguration file is in the format used by the
+<command>debconf-set-selections</command> command.
+
+</para>
 
 <itemizedlist>
 <listitem><para>
+  File format
+</para></listitem>
+<listitem><para>
+  Only single space allowed between template type and value
+</para></listitem>
+<listitem><para>
   Relation with /var/lib/(c)debconf/templates
 </para></listitem>
 <listitem><para>
+  Types of templates and how to provide values for them
+</para></listitem>
+<listitem><para>
   Most values need to be in English or codes
 </para></listitem>
 <listitem><para>
@@ -207,7 +446,7 @@ The locale can be used to specify both language and country.
 To specify the locale as a boot parameter, use
 <userinput>debian-installer/locale=<replaceable>en_US</replaceable></userinput>.
 
-<informalexample><screen>
+<informalexample role="example"><screen>
 # Locale sets language and country.
 d-i debian-installer/locale string en_US
 </screen></informalexample>
@@ -219,6 +458,14 @@ keymap. In most cases the correct keyboard architecture is selected by
 default, so there's normally no need to preseed it. The keymap must of
 course be valid for the selected or preseeded architecture.
 
+<informalexample role="example"><screen>
+# Keyboard selection.
+#d-i console-tools/archs select at
+d-i console-keymaps-at/keymap select us
+# Example for a different keyboard architecture
+#d-i console-keymaps-usb/keymap select mac-usb-us
+</screen></informalexample>
+
 </para><para>
 
 To skip keyboard configuration preseed
@@ -228,15 +475,6 @@ This will result in the kernel keymap remaining active.
 
 </para>
 
-<informalexample><screen>
-# Keyboard selection.
-#d-i console-tools/archs select at
-d-i console-keymaps-at/keymap select us
-# Example for a different keyboard architecture
-#d-i console-keymaps-usb/keymap select mac-usb-us
-
-</screen></informalexample>
-
 <note><para>
 
 The changes in the input layer for 2.6 kernels have made the keyboard
@@ -258,7 +496,7 @@ boot parameters.
 
 </para>
 
-<informalexample><screen>
+<informalexample role="example"><screen>
 # netcfg will choose an interface that has link if possible. This makes it
 # skip displaying a list if there is more than one interface.
 d-i netcfg/choose_interface select auto
@@ -315,7 +553,7 @@ as <classname>mirror/suite</classname>.
 
 </para>
 
-<informalexample><screen>
+<informalexample role="example"><screen>
 d-i mirror/country string enter information manually
 d-i mirror/http/hostname string http.us.debian.org
 d-i mirror/http/directory string /debian
@@ -351,7 +589,7 @@ correct one will be selected before using preseeding.
 
 </para></warning>
 
-<informalexample><screen>
+<informalexample role="example"><screen>
 # If the system has free space you can choose to only partition that space.
 #d-i partman-auto/init_automatically_partition \
 #      select Use the largest continuous free space
@@ -407,7 +645,7 @@ d-i partman/confirm boolean true
   <sect2 id="preseed-time">
   <title>Clock and time zone setup</title>
 
-<informalexample><screen>
+<informalexample role="example"><screen>
 # Controls whether or not the hardware clock is set to UTC.
 d-i clock-setup/utc boolean true
 
@@ -418,7 +656,7 @@ d-i time/zone string US/Eastern
 
   </sect2>
 
-  <sect2 id="preseed-account" condition="NOT-YET">
+  <sect2 id="preseed-account">
   <title>Account setup</title>
 <para>
 
@@ -437,7 +675,7 @@ access to a MD5 hash allows for brute force attacks.
 
 </para></warning>
 
-<informalexample><screen>
+<informalexample role="example"><screen>
 # Root password, either in clear text
 #passwd passwd/root-password password r00tme
 #passwd passwd/root-password-again password r00tme
@@ -472,7 +710,7 @@ activities or root login (for instance by using SSH key authentication).
   <sect2 id="preseed-bootloader">
   <title>Boot loader installation</title>
 
-<informalexample><screen>
+<informalexample role="example"><screen>
 # Grub is the default boot loader (for x86). If you want lilo installed
 # instead, uncomment this:
 #d-i grub-installer/skip boolean true
@@ -497,7 +735,7 @@ d-i grub-installer/with_other_os boolean true
   <sect2 id="preseed-finish">
   <title>Finishing up the first stage install</title>
 
-<informalexample><screen>
+<informalexample role="example"><screen>
 # Avoid that last message about the install being complete.
 d-i prebaseconfig/reboot_in_progress note
 
@@ -507,37 +745,6 @@ d-i prebaseconfig/reboot_in_progress note
 </screen></informalexample>
 
   </sect2>
-
-  <sect2 id="preseed-shell">
-  <title>Shell commands</title>
-
-<informalexample><screen>
-# d-i preseeding is inherently not secure. Nothing in the installer checks
-# for attempts at buffer overflows or other exploits of the values of a
-# preseed file like this one. Only use preseed files from trusted
-# locations! To drive that home, and because it's generally useful, here's
-# a way to run any shell command you'd like inside the installer,
-# automatically.
-
-# This first command is run as early as possible, just after
-# preseeding is read.
-#d-i preseed/early_command string anna-install some-udeb
-
-# This command is run just before the install finishes, but when there is
-# still a usable /target directory.
-#d-i preseed/late_command string echo foo > /target/etc/bar
-
-# This command is run just as base-config is starting up.
-#base-config base-config/early_command string echo hi mom
-
-# This command is run after base-config is done, just before the login:
-# prompt. This is a good way to install a set of packages you want, or to
-# tweak the configuration of the system.
-#base-config base-config/late_command \
-#      string apt-get install zsh; chsh -s /bin/zsh
-</screen></informalexample>
-
-  </sect2>
  </sect1>
 
  <sect1 id="preseed-stage2">
@@ -546,7 +753,7 @@ d-i prebaseconfig/reboot_in_progress note
   <sect2 id="preseed-baseconfig">
   <title>Base config</title>
 
-<informalexample><screen>
+<informalexample role="example"><screen>
 # Avoid the introductory message.
 base-config base-config/intro note
 
@@ -565,32 +772,10 @@ base-config base-config/login note
 
   </sect2>
 
-  <sect2 id="preseed-account">
-  <title>Account setup</title>
-
-<informalexample><screen>
-# To preseed the root password, you have to put it in the clear in this
-# file. That is not a very good idea, use caution!
-#passwd passwd/root-password password r00tme
-#passwd passwd/root-password-again password r00tme
-
-# If you want to skip creation of a normal user account.
-#passwd passwd/make-user boolean false
-
-# Alternatively, you can preseed the user's name and login.
-#passwd passwd/user-fullname string Debian User
-#passwd passwd/username string debian
-# And their password, but use caution!
-#passwd passwd/user-password password insecure
-#passwd passwd/user-password-again password insecure
-</screen></informalexample>
-
-  </sect2>
-
   <sect2 id="preseed-apt">
   <title>Apt setup</title>
 
-<informalexample><screen>
+<informalexample role="example"><screen>
 # This question controls what source the second stage installation uses
 # for packages. Choices are cdrom, http, ftp, filesystem, edit sources list
 # by hand
@@ -620,6 +805,8 @@ base-config apt-setup/security-updates boolean true
 You can choose to install any combination of tasks that are available.
 Available tasks as of this writing include:
 
+</para>
+
 <itemizedlist>
 <listitem><para>
   <userinput>Standard system</userinput>
@@ -653,13 +840,15 @@ Available tasks as of this writing include:
 </para></listitem>
 </itemizedlist>
 
+<para>
+
 The last of these will run aptitude. You can also choose to install no tasks,
 and force the installation of a set of packages in some other way. We recommend
 always including the <userinput>Standard system</userinput> task.
 
 </para>
 
-<informalexample><screen>
+<informalexample role="example"><screen>
 tasksel tasksel/first multiselect Standard system, Desktop environment
 #tasksel tasksel/first multiselect Standard system, Web server
 </screen></informalexample>
@@ -675,7 +864,7 @@ avoid even those. More complicated preseeding is possible.
 
 </para>
 
-<informalexample><screen>
+<informalexample role="example"><screen>
 exim4-config exim4/dc_eximconfig_configtype \
        select no configuration at this time
 exim4-config exim4/no_config boolean true
@@ -699,7 +888,7 @@ configurator does not do fully automatic configuration of everything.
 
 </para>
 
-<informalexample><screen>
+<informalexample role="example"><screen>
 # X can detect the right driver for some cards, but if you're preseeding,
 # you override whatever it chooses. Still, vesa will work most places.
 #xserver-xfree86 xserver-xfree86/config/device/driver select vesa
@@ -727,7 +916,7 @@ xserver-xfree86 xserver-xfree86/config/monitor/mode-list \
   <sect2 id="preseed-other">
   <title>Preseeding other packages</title>
 
-<informalexample><screen>
+<informalexample role="example"><screen>
 # Depending on what software you choose to install, or if things go wrong
 # during the installation process, it's possible that other questions may
 # be asked. You can preseed those too, of course. To get a list of every
@@ -742,6 +931,40 @@ xserver-xfree86 xserver-xfree86/config/monitor/mode-list \
 
  <sect1 id="preseed-advanced">
  <title>Advanced options</title>
+
+  <sect2 id="preseed-shell">
+  <title>Shell commands</title>
+
+<informalexample role="example"><screen>
+# d-i preseeding is inherently not secure. Nothing in the installer checks
+# for attempts at buffer overflows or other exploits of the values of a
+# preseed file like this one. Only use preseed files from trusted
+# locations! To drive that home, and because it's generally useful, here's
+# a way to run any shell command you'd like inside the installer,
+# automatically.
+
+# This first command is run as early as possible, just after
+# preseeding is read.
+#d-i preseed/early_command string anna-install some-udeb
+
+# This command is run just before the install finishes, but when there is
+# still a usable /target directory.
+#d-i preseed/late_command string echo foo > /target/etc/bar
+
+# This command is run just as base-config is starting up.
+#base-config base-config/early_command string echo hi mom
+
+# This command is run after base-config is done, just before the login:
+# prompt. This is a good way to install a set of packages you want, or to
+# tweak the configuration of the system.
+#base-config base-config/late_command \
+#      string apt-get install zsh; chsh -s /bin/zsh
+</screen></informalexample>
+
+  </sect2>
+
+  <sect2 id="preseed-chainload">
+  <title>Chainloading preseed files</title>
 <para>
 
 It is possible to include other preseed files from a preseed file. Any
@@ -770,5 +993,6 @@ settings for certain configurations in other files.
 #      string echo if [ "`hostname`" = bob ]; then echo bob.cfg; fi
 </screen></informalexample>
 
+  </sect2>
  </sect1>
 </appendix>
diff --git a/en/install-methods/automatic-install.xml b/en/install-methods/automatic-install.xml
index 4000f2aea..f15c936b4 100644
--- a/en/install-methods/automatic-install.xml
+++ b/en/install-methods/automatic-install.xml
@@ -21,25 +21,30 @@ the Debian Installer itself.
 
 The Debian Installer supports automating installs via preconfiguration
 files. A preconfiguration file can be loaded from the network or from
-removable media, and used to fill in answers to question asked during the
+removable media, and used to fill in answers to questions asked during the
 installation process.
 
-</para><para>
+</para><para condition="etch">
+
+Full documentation on preseeding including a working example that you can
+edit is in <xref linkend="appendix-preseed"/>.
+
+</para><para condition="sarge">
 
 Although most dialogs used by &d-i; can be preseeded using this method,
 there are some notable exceptions. You can (re)partition an entire disk
 or use available free space on a disk; it is not possible to use existing
 partitions. You currently cannot use preseeding to set up RAID and LVM.
-<phrase condition="sarge">Also, with the exception of network driver modules,
-it is not possible to preconfigure kernel module parameters.</phrase>
+Also, with the exception of network driver modules, it is not possible
+to preconfigure kernel module parameters.
 
-</para><para>
+</para><para condition="sarge">
 
 The preconfiguration file is in the format used by the
-debconf-set-selections command. A well documented and working example that
-you can edit is in <xref linkend="example-preseed"/>.
+debconf-set-selections command. A well documented and working example
+that you can edit is in <xref linkend="example-preseed"/>.
 
-</para><para>
+</para><para condition="sarge">
 
 Alternatively, one way to get a complete file listing
 all the values that can be preseeded is to do a manual install,
@@ -57,14 +62,14 @@ However, a file generated in this manner will have some items that should
 not be preseeded, and the file in <xref linkend="example-preseed"/> is a
 better starting place for most users.
 
-</para><para>
+</para><para condition="sarge">
 
 Once you have a preconfiguration file, you can edit it if necessary, and
 place it on a web server, or copy it onto the installer's boot media. Wherever
 you place the file, you need to pass a parameter to the installer at boot
 time to tell it to use the file.
 
-</para><para>
+</para><para condition="sarge">
 
 To make the installer use a preconfiguration file downloaded from the
 network, add preseed/url=http://url/to/preseed.cfg to the kernel boot
@@ -75,14 +80,14 @@ any questions. You may want to set the installation priority to critical to
 avoid any questions while the network is being configured. See
 <xref linkend="installer-args"/>.
 
-</para><para>
+</para><para condition="sarge">
 
 To place a preconfiguration file on a CD, you would need to remaster the
 ISO image to include your preconfiguration file. See the manual page for
 mkisofs for details. Alternatively, put the preseed file on a floppy, and
 use preseed/file=/floppy/preseed.cfg
 
-</para><para arch="i386">
+</para><para arch="i386" condition="sarge">
 
 If you'll be booting from a USB memory stick, then you can simply copy your
 preconfiguration file onto the memory stick's filesystem, and edit the
@@ -90,22 +95,5 @@ syslinux.cfg file to add preseed/file=/hd-media/preseed.cfg to the kernel boot
 parameters.
 
 </para>
-
-   <sect3 condition="etch">
-   <title>Using Preseeding to Change Default Values</title>
-<para>
-
-It is also possible to use preseeding to change the default answer for a
-question, but still have the question asked. To do this the
-<firstterm>seen</firstterm> flag must be reset to <quote>false</quote> after
-setting the value for a template.
-
-<informalexample><screen>
-d-i foo/bar string value
-d-i foo/bar seen false
-</screen></informalexample>
-
-</para>
-   </sect3>
   </sect2>
  </sect1>