move manual to top-level directory, split out of debian-installer package

8 files changed, 551 insertions, 0 deletions

diff --git a/en/post-install/further-reading.xml b/en/post-install/further-reading.xml
new file mode 100644
index 000000000..9f52631b0
--- /dev/null
+++ b/en/post-install/further-reading.xml
@@ -0,0 +1,49 @@
+<!-- retain these comments for translator revision tracking -->
+<!-- $Id$ -->
+
+ <sect1 id="further-reading"><title>Further Reading and Information</title>
+<para>
+
+If you need information about a particular program, you should first
+try <userinput>man <replaceable>program</replaceable></userinput>, or
+<userinput>info <replaceable>program</replaceable></userinput>.
+
+</para><para>
+
+There is lots of useful documentation in
+<filename>/usr/share/doc</filename> as well.  In particular,
+<filename>/usr/share/doc/HOWTO</filename> and
+<filename>/usr/share/doc/FAQ</filename> contain lots of interesting
+information.  To submit bugs, look at
+<filename>/usr/share/doc/debian/bug*</filename>.  To read about
+Debian-specific issues for particular programs, look at
+<filename>/usr/share/doc/(package name)/README.Debian</filename>.
+
+</para><para>
+
+The
+<ulink url="http://www.debian.org/">Debian web site</ulink>
+contains a large quantity of documentation about Debian.  In
+particular, see the
+<ulink url="http://www.debian.org/doc/FAQ/">Debian GNU/Linux FAQ</ulink> and the
+<ulink url="http://www.debian.org/doc/user-manuals#quick-reference">Debian
+Reference</ulink>.
+An index of more Debian documentation is available from the
+<ulink url="http://www.debian.org/doc/ddp">Debian Documentation Project</ulink>.
+The Debian community is self-supporting; to subscribe to
+one or more of the Debian mailing lists, see the
+<ulink url="http://www.debian.org/MailingLists/subscribe">
+Mail List Subscription</ulink> page.
+Last, but not least, the <ulink url="http://lists.debian.org/">Debian Mailing
+List Archives</ulink> contain a wealth of information on Debian.
+
+</para><para>
+
+A general source of information on GNU/Linux is the
+<ulink url="http://www.tldp.org/">Linux Documentation Project</ulink>.
+There you will find the HOWTOs and pointers to other very valuable
+information on parts of a GNU/Linux system.
+
+</para>
+
+ </sect1>
diff --git a/en/post-install/kernel-baking.xml b/en/post-install/kernel-baking.xml
new file mode 100644
index 000000000..9d02ce08a
--- /dev/null
+++ b/en/post-install/kernel-baking.xml
@@ -0,0 +1,182 @@
+<!-- retain these comments for translator revision tracking -->
+<!-- $Id$ -->
+
+ <sect1 id="kernel-baking"><title>Compiling a New Kernel</title>
+<para>
+
+Why would someone want to compile a new kernel? It is often not
+necessary since the default kernel shipped with Debian handles most
+configurations. However, it is useful to compile a new kernel in order
+to:
+
+<itemizedlist>
+<listitem><para>
+
+handle special hardware needs, or hardware conflicts with the pre-supplied
+kernels
+
+</para></listitem>
+<listitem><para>
+
+handle hardware or options not included in the stock kernel, such as
+APM or SMP
+
+</para></listitem>
+<listitem><para>
+
+optimize the kernel by removing useless drivers to speed up boot
+time
+
+</para></listitem>
+<listitem><para>
+
+use options of the kernel which are not supported by the default
+kernel (such as high memory support)
+
+</para></listitem>
+<listitem><para>
+
+run an updated or development kernel
+
+</para></listitem>
+<listitem><para>
+
+impress your friends, try new things
+
+</para></listitem>
+</itemizedlist>
+
+</para>
+
+  <sect2><title>Kernel Image Management</title>
+<para>
+
+Don't be afraid to try compiling the kernel.  It's fun and profitable.
+
+</para><para>
+
+To compile a kernel the Debian way, you need some packages:
+<classname>kernel-package</classname>,
+<classname>kernel-source-&kernelversion;</classname> (the most recent version
+at the time of this writing), <classname>fakeroot</classname> and a
+few others which are probably already installed (see
+<filename>/usr/share/doc/kernel-package/README.gz</filename> for the
+complete list).
+
+</para><para>
+
+This method will make a .deb of your kernel source, and, if you have
+non-standard modules, make a synchronized dependent .deb of those
+too. It's a better way to manage kernel images;
+<filename>/boot</filename> will hold the kernel, the System.map, and a
+log of the active config file for the build.
+
+</para><para>
+
+Note that you don't <emphasis>have</emphasis> to compile your kernel
+the <quote>Debian way</quote>; but we find that using the packaging system
+to manage your kernel is actually safer and easier.  In fact, you can get
+your kernel sources right from Linus instead of
+<classname>kernel-source-&kernelversion;</classname>, yet still use the
+<classname>kernel-package</classname> compilation method.
+
+</para><para>
+
+Note that you'll find complete documentation on using
+<classname>kernel-package</classname> under
+<filename>/usr/share/doc/kernel-package</filename>.  This section just
+contains a brief tutorial.
+
+</para><para>
+
+Hereafter, we'll assume you have free rein over your machine and will
+extract your kernel source to somewhere in your home directory<footnote>
+
+<para>
+
+There are other locations where you can extract kernel sources and build
+your custom kernel, but this is easiest as it does not require special
+permissions.
+
+</para>
+
+</footnote>. We'll also assume that your kernel version is
+&kernelversion;. Make sure you are in the directory to where you want to
+unpack the kernel sources, extract them using <userinput>tar xjf
+/usr/src/kernel-source-&kernelversion;.tar.bz2</userinput> and change
+to the directory <filename>kernel-source-&kernelversion;</filename>
+that will have been created.
+
+</para><para>
+
+Now, you can configure your kernel.  Run <userinput>make
+xconfig</userinput> if X11 is installed, configured and being run; run
+<userinput>make menuconfig</userinput> otherwise (you'll need
+<classname>libncurses5-dev</classname> installed). Take the time to read
+the online help and choose carefully. When in doubt, it is typically
+better to include the device driver (the software which manages
+hardware peripherals, such as Ethernet cards, SCSI controllers, and so
+on) you are unsure about.  Be careful: other options, not related to a
+specific hardware, should be left at the default value if you do not
+understand them.  Do not forget to select <quote>Kernel module loader</quote>
+in <quote>Loadable module support</quote> (it is not selected by default).
+If not included, your Debian installation will experience problems.
+
+</para><para>
+
+Clean the source tree and reset the <classname>kernel-package</classname>
+parameters.  To do that, do <userinput>make-kpkg clean</userinput>.
+
+</para><para>
+
+Now, compile the kernel:
+<userinput>fakeroot make-kpkg --revision=custom.1.0 kernel_image</userinput>.
+The version number of <quote>1.0</quote> can be changed at will; this is just
+a version number that you will use to track your kernel builds.
+Likewise, you can put any word you like in place of <quote>custom</quote>
+(e.g., a host name).  Kernel compilation may take quite a while, depending on
+the power of your machine.
+
+</para><para condition="supports-pcmcia">
+
+If you require PCMCIA support, you'll also need to install the
+<classname>pcmcia-source</classname> package.  Unpack the gzipped tar file
+as root in the directory <filename>/usr/src</filename> (it's important that
+modules are found where they are expected to be found, namely,
+<filename>/usr/src/modules</filename>).  Then, as root, do <userinput>make-kpkg
+modules_image</userinput>.
+
+</para><para>
+
+Once the compilation is complete, you can install your custom kernel
+like any package.  As root, do <userinput>dpkg -i
+../kernel-image-&kernelversion;-<replaceable>subarchitecture</replaceable>_custom.1.0_&architecture;.deb</userinput>.
+The <replaceable>subarchitecture</replaceable> part is an optional
+sub-architecture,
+<phrase arch="i386"> such as <quote>i586</quote>, </phrase>
+depending on what kernel options you set.
+<userinput>dpkg -i kernel-image...</userinput> will install the
+kernel, along with some other nice supporting files.  For instance,
+the <filename>System.map</filename> will be properly installed
+(helpful for debugging kernel problems), and
+<filename>/boot/config-&kernelversion;</filename> will be installed,
+containing your current configuration set.  Your new
+<classname>kernel-image-&kernelversion;</classname> package is also clever
+enough to automatically use your platform's boot-loader to run an
+update on the booting, allowing you to boot without re-running the
+boot loader.  If you have created a modules package, e.g., if you have
+PCMCIA, you'll need to install that package as well.
+
+</para><para>
+
+It is time to reboot the system: read carefully any warning that the
+above step may have produced, then <userinput>shutdown -r now</userinput>.
+
+</para><para>
+
+For more information on <classname>kernel-package</classname>, read
+the fine documentation in <filename>/usr/share/doc/kernel-package</filename>.
+
+</para>
+  </sect2>
+ </sect1>
diff --git a/en/post-install/new-to-unix.xml b/en/post-install/new-to-unix.xml
new file mode 100644
index 000000000..50284c380
--- /dev/null
+++ b/en/post-install/new-to-unix.xml
@@ -0,0 +1,29 @@
+<!-- retain these comments for translator revision tracking -->
+<!-- $Id$ -->
+
+
+ <sect1 id="unix-intro">
+ <title>If You Are New to Unix</title>
+<para>
+
+If you are new to Unix, you probably should go out and buy some books
+and do some reading.  A lot of valuable information can also be found
+in the <ulink url="&url-debian-reference;">Debian Reference</ulink>.
+This <ulink url="&url-unix-faq;">list of Unix FAQs</ulink> contains a
+number of UseNet documents which provide a nice historical reference.
+
+</para><para>
+
+Linux is an implementation of Unix.  The
+<ulink url="&url-ldp;">Linux Documentation Project (LDP)</ulink>
+collects a number of HOWTOs and online books
+relating to Linux.  Most of these documents can be installed locally;
+just install the <classname>doc-linux-html</classname> package (HTML
+versions) or the <classname>doc-linux-text</classname> package (ASCII
+versions), then look in <filename>/usr/share/doc/HOWTO</filename>.
+International versions of the LDP HOWTOs are also available as Debian
+packages.
+
+</para>
+
+ </sect1>
diff --git a/en/post-install/orientation.xml b/en/post-install/orientation.xml
new file mode 100644
index 000000000..680979342
--- /dev/null
+++ b/en/post-install/orientation.xml
@@ -0,0 +1,109 @@
+<!-- retain these comments for translator revision tracking -->
+<!-- $Id$ -->
+
+
+ <sect1 id="debian-orientation"><title>Orienting Yourself to Debian</title>
+<para>
+
+Debian is a little different from other distributions.  Even if you're
+familiar with Linux in other distributions, there are things you
+should know about Debian to help you to keep your system in a good,
+clean state.  This chapter contains material to help you get oriented;
+it is not intended to be a tutorial for how to use Debian, but just a
+very brief glimpse of the system for the very rushed.
+
+</para>
+
+  <sect2><title>Debian Packaging System</title>
+<para>
+
+The most important concept to grasp is the Debian packaging system.
+In essence, large parts of your system should be considered under the
+control of the packaging system.  These include:
+
+<itemizedlist>
+<listitem><para>
+
+<filename>/usr</filename> (excluding <filename>/usr/local</filename>)
+
+</para></listitem>
+<listitem><para>
+
+<filename>/var</filename> (you could make
+<filename>/var/local</filename> and be safe in there)
+
+</para></listitem>
+<listitem><para>
+
+<filename>/bin</filename>
+
+</para></listitem>
+<listitem><para>
+
+<filename>/sbin</filename>
+
+</para></listitem>
+<listitem><para>
+
+<filename>/lib</filename>
+
+</para></listitem>
+</itemizedlist>
+
+For instance, if you replace <filename>/usr/bin/perl</filename>, that
+will work, but then if you upgrade your <classname>perl</classname>
+package, the file you put there will be replaced.  Experts can get
+around this by putting packages on <quote>hold</quote> in
+<command>aptitude</command>.
+
+</para><para>
+
+One of the best installation methods is apt. You can use the command
+line version <command>apt-get</command> or full-screen text version
+<application>aptitude</application>.  Note apt will also let you merge
+main, contrib, and non-free so you can have export-restricted packages
+as well as standard versions.
+
+</para>
+  </sect2>
+
+  <sect2><title>Application Version Management</title>
+<para>
+
+
+Alternative versions of applications are managed by update-alternatives. If
+you are maintaining multiple versions of your applications, read the
+update-alternatives man page.
+
+</para>
+  </sect2>
+
+  <sect2><title>Cron Job Management</title>
+<para>
+
+Any jobs under the purview of the system administrator should be in
+<filename>/etc</filename>, since they are configuration files.  If you
+have a root cron job for daily, weekly, or monthly runs, put them in
+<filename>/etc/cron.{daily,weekly,monthly}</filename>.  These are
+invoked from <filename>/etc/crontab</filename>, and will run in
+alphabetic order, which serializes them.
+
+</para><para>
+
+On the other hand, if you have a cron job that (a) needs to run as a
+special user, or (b) needs to run at a special time or frequency, you
+can use either <filename>/etc/crontab</filename>, or, better yet,
+<filename>/etc/cron.d/whatever</filename>.  These particular files
+also have an extra field that allows you to stipulate the user under
+which the cron job runs.
+
+</para><para>
+
+In either case, you just edit the files and cron will notice them
+automatically. There is no need to run a special command. For more
+information see cron(8), crontab(5), and
+<filename>/usr/share/doc/cron/README.Debian</filename>.
+
+</para>
+  </sect2>
+ </sect1>
diff --git a/en/post-install/post-install.xml b/en/post-install/post-install.xml
new file mode 100644
index 000000000..fae552701
--- /dev/null
+++ b/en/post-install/post-install.xml
@@ -0,0 +1,14 @@
+<!-- retain these comments for translator revision tracking -->
+<!-- $Id$ -->
+
+<chapter id="post-install">
+ <title>Next Steps and Where to Go From Here</title>
+
+&new-to-unix.xml;
+&orientation.xml;
+&reactivating-win.xml;
+&further-reading.xml;
+&kernel-baking.xml;
+&rescue.xml;
+
+</chapter>
diff --git a/en/post-install/reactivating-win.xml b/en/post-install/reactivating-win.xml
new file mode 100644
index 000000000..728585b9b
--- /dev/null
+++ b/en/post-install/reactivating-win.xml
@@ -0,0 +1,72 @@
+<!-- retain these comments for translator revision tracking -->
+<!-- $Id$ -->
+
+
+ <sect1 arch="i386" id="reactivating-win">
+ <title>Reactivating DOS and Windows</title>
+<para>
+
+After installing the base system and writing to the <emphasis>Master Boot
+Record</emphasis>, you will be able to boot Linux, but probably nothing else.
+This depends what you have chosen during the installation. This chapter
+will describe how you can reactivate your old systems so that you can also
+boot your DOS or Windows again.
+
+</para><para>
+
+<command>LILO</command> is a boot manager with which you can also boot
+other operating systems than Linux, which complies to PC
+conventions. The boot manager is configured via
+<filename>/etc/lilo.conf</filename> file. Whenever you edited this
+file you have to run <command>lilo</command> afterwards. The reason
+for this is that the changes will take place only when you call the
+program.
+
+</para><para>
+
+Important parts of the <filename>lilo.conf</filename> file are the
+lines containing the <userinput>image</userinput> and
+<userinput>other</userinput> keywords, as well as the lines following
+those. They can be used to describe a system which can be booted by
+<command>LILO</command>. Such a system can include a kernel
+(<userinput>image</userinput>), a root partition, additional kernel
+parameters, etc. as well as a configuration to boot another, non-Linux
+(<userinput>other</userinput>) operating system.  These keywords can
+also be used more than once.  The ordering of these systems within the
+configuration file is important because it determines which system
+will be booted automatically after, for instance, a timeout
+(<userinput>delay</userinput>) presuming <command>LILO</command>
+wasn't stopped by pressing the <keycap>shift</keycap> key.
+
+</para><para>
+
+After a fresh install of Debian, just the current system is configured
+for booting with <command>LILO</command>. If you want to boot another
+Linux kernel, you have to edit the configuration file
+<filename>/etc/lilo.conf</filename> to add the following lines:
+
+<informalexample><screen>
+&additional-lilo-image;
+</screen></informalexample>
+
+For a basic setup just the first two lines are necessary. If you want
+to know more about the other two options please have a look at the
+<command>LILO</command> documentation. This can be found in
+<filename>/usr/share/doc/lilo/</filename>. The file which should be
+read is <filename>Manual.txt</filename>. To have a quicker start into
+the world of booting a system you can also look at the
+<command>LILO</command> man pages <filename>lilo.conf</filename> for
+an overview of configuration keywords and <filename>lilo</filename>
+for description of the installation of the new configuration into the
+boot sector.
+
+</para><para>
+
+Notice that there are other boot loaders available in &debian;, such as
+GRUB (in <classname>grub</classname> package),
+CHOS (in <classname>chos</classname> package),
+Extended-IPL (in <classname>extipl</classname> package),
+loadlin (in <classname>loadlin</classname> package) etc.
+
+</para>
+ </sect1>
diff --git a/en/post-install/rescue.xml b/en/post-install/rescue.xml
new file mode 100644
index 000000000..f920f6078
--- /dev/null
+++ b/en/post-install/rescue.xml
@@ -0,0 +1,71 @@
+<!-- retain these comments for translator revision tracking -->
+<!-- $Id$ -->
+
+ <sect1 id="rescue" condition="etch">
+ <title>Recovering a Broken System</title>
+<para>
+
+Sometimes, things go wrong, and the system you've carefully installed is no
+longer bootable. Perhaps the boot loader configuration broke while trying
+out a change, or perhaps a new kernel you installed won't boot, or perhaps
+cosmic rays hit your disk and flipped a bit in
+<filename>/sbin/init</filename>. Regardless of the cause, you'll need to
+have a system to work from while you fix it, and rescue mode can be useful
+for this.
+
+</para><para>
+
+<!-- TODO: describe what to do on arches where this isn't set up in the
+     bootloader -->
+
+To access rescue mode, type <userinput>rescue</userinput> at the
+<prompt>boot:</prompt> prompt, or boot with the
+<userinput>rescue/enable=true</userinput> boot parameter. You'll be shown
+the first few screens of the installer, with a note in the corner of the
+display to indicate that this is rescue mode, not a full installation. Don't
+worry, your system is not about to be overwritten! Rescue mode simply takes
+advantage of the hardware detection facilities available in the installer to
+ensure that your disks, network devices, and so on are available to you
+while repairing your system.
+
+</para><para>
+
+Instead of the partitioning tool, you should now be presented with a list of
+the partitions on your system, and asked to select one of them. Normally,
+you should select the partition containing the root file system that you
+need to repair. You may select partitions on RAID and LVM devices as well as
+those created directly on disks.
+
+</para><para>
+
+If possible, the installer will now present you with a shell prompt in the
+file system you selected, which you can use to perform any necessary
+repairs.
+
+<phrase arch="i386">
+For example, if you need to reinstall the GRUB boot loader into the master
+boot record of the first hard disk, you could enter the command
+<userinput>grub-install '(hd0)'</userinput> to do so.
+</phrase>
+
+</para><para>
+
+If the installer cannot run a usable shell in the root file system you
+selected, perhaps because the file system is corrupt, then it will issue a
+warning and offer to give you a shell in the installer environment instead.
+You may not have as many tools available in this environment, but they will
+often be enough to repair your system anyway. The root file system you
+selected will be mounted on the <filename>/target</filename> directory.
+
+</para><para>
+
+In either case, after you exit the shell, the system will reboot.
+
+</para><para>
+
+Finally, note that repairing broken systems can be difficult, and this
+manual does not attempt to go into all the things that might have gone wrong
+or how to fix them. If you have problems, consult an expert.
+
+</para>
+ </sect1>
diff --git a/en/post-install/shutdown.xml b/en/post-install/shutdown.xml
new file mode 100644
index 000000000..d838a38c2
--- /dev/null
+++ b/en/post-install/shutdown.xml
@@ -0,0 +1,25 @@
+<!-- retain these comments for translator revision tracking -->
+<!-- $Id$ -->
+
+
+ <sect1 id="shutdown">
+ <title>Shutting Down the System</title>
+
+<para>
+
+To shut down a running Linux system, you must not reboot with the
+reset switch on the front or back of your computer, or just turn off
+the computer.  Linux must be shut down in a controlled manner,
+otherwise files may be lost and disk damage incurred. You can press
+the key combination <keycombo> <keycap>Ctrl</keycap>
+<keycap>Alt</keycap> <keycap>Del</keycap> </keycombo>
+<phrase arch="powerpc;m68k"> or <keycombo> <keycap>Control</keycap>
+<keycap>Shift</keycap> <keycap>Power</keycap> </keycombo> on Macintosh
+systems</phrase>. You may also log in as
+root and type <userinput>shutdown -h now</userinput>,
+<userinput>reboot</userinput>, or <userinput>halt</userinput> if
+either of the key combinations do not work or you prefer to type
+commands.
+
+</para>
+ </sect1>