Minor corrections and some rewrites based on suggestions from Clytie Siddall

1 files changed, 42 insertions, 21 deletions

diff --git a/en/using-d-i/modules/shell.xml b/en/using-d-i/modules/shell.xml
index 57081c7a2..796744900 100644
--- a/en/using-d-i/modules/shell.xml
+++ b/en/using-d-i/modules/shell.xml
@@ -3,39 +3,60 @@
 
    <sect3 id="shell">
    <title>Using the Shell and Viewing the Logs</title>
-   <!-- TODO: There is nothing about logs in this section! -->
 
 <para>
 
-There is an <guimenuitem>Execute a Shell</guimenuitem> item on the
-menu. If the menu is not available when you need to use the shell,
-press <keycombo><keycap>Left Alt</keycap> <keycap>F2</keycap></keycombo>
-(on a Mac keyboard, <keycombo><keycap>Option</keycap> <keycap>F2</keycap>
-</keycombo>) to switch to the second <emphasis>virtual
-console</emphasis>. That's the <keycap>Alt</keycap> key on the
-left-hand side of the <keycap>space bar</keycap>, and the
-<keycap>F2</keycap> function key, at the same time. This is a separate
-window running a Bourne shell clone called <command>ash</command>.
+There are several methods you can use to get a shell while running an
+installation. On most systems, and if you are not installing over
+serial console, the easiest method is to switch to the second
+<emphasis>virtual console</emphasis> by pressing <keycombo><keycap>Left
+Alt</keycap> <keycap>F2</keycap></keycombo><footnote>
+
+<para>
+That is: press the <keycap>Alt</keycap> key on the left-hand side of the
+<keycap>space bar</keycap> and the <keycap>F2</keycap> function key
+at the same time.
+</para>
+
+</footnote> (on a Mac keyboard, <keycombo><keycap>Option</keycap>
+<keycap>F2</keycap></keycombo>). Use <keycombo><keycap>Left Alt</keycap>
+<keycap>F1</keycap></keycombo> to switch back to installer itself.
+
+</para><para>
+
+If you cannot switch consoles, there is also an <guimenuitem>Execute
+a Shell</guimenuitem> item on the main menu that can be used to start
+a shell. To get back to the installer itself, type
+<userinput>exit</userinput> to close the shell.
 
 </para><para>
 
 At this point you are booted from the RAM disk, and there is a limited
 set of Unix utilities available for your use. You can see what
 programs are available with the command <command>ls /bin /sbin /usr/bin
-/usr/sbin</command> and by typing <command>help</command>. The
-text editor is <command>nano</command>. The shell has some nice features
-like autocompletion and history.
+/usr/sbin</command> and by typing <command>help</command>. 
+The shell is a Bourne shell clone called <command>ash</command> and has
+some nice features like autocompletion and history.
 
 </para><para>
 
-Use the menus to perform any task that they are able to do &mdash; the
-shell and commands are only there in case something goes wrong.  In
-particular, you should always use the menus, not the shell, to
-activate your swap partition, because the menu software can't detect
-that you've done this from the shell. Press <keycombo><keycap>Left
-Alt</keycap> <keycap>F1</keycap></keycombo> to get back to menus, or
-type <command>exit</command> if you used a menu item to open the
-shell.
+To edit and view files, use the text editor <command>nano</command>.
+Log files for the installation system can be found in the
+<filename>/var/log</filename> directory.
 
 </para>
+<note><para>
+
+Although you can do basically anything in a shell that the available
+commands allow you to do, the option to use a shell is really only there
+in case something goes wrong and for debugging.
+
+</para><para>
+
+Doing things manually from the shell may interfere with the installation
+process and result in errors or an incomplete installation.
+In particular, you should always use let the installer activate your swap
+partition and not do this yourself from a shell.
+
+</para></note>
    </sect3>