Re: documentation bugs to fix
Chris Tillman <tillman@azstarnet.com> writes:
> +<sect1>Setting Up Your Mouse
> +<p>
> +The mouse can be used in both the Linux console (gpm) and X windows.
> +The preferred configuration / signal flow are:
> +<example>
> +mouse => /dev/psaux => gpm => /dev/gpmdata -> /dev/mouse => X
> + /dev/ttyS0 (repeater) (symlink)
> + /dev/ttyS1
> +</example>
AFAIK the PS/2 stuff (psaux) is pretty much totally i386 specific so
should be marked up as such. The default case you talk should be bus
mice/serial mice, which don't need a repeater, and are also reasonable
arch-indep. Talk about psaux and the repeater requirement *after* you
talk about the basic, simpler stuff.
Why go to this much technical depth anyway? The user perspective
should be here installation of gpm, which will normally come in after
tasksel or dselect runs (since it's a standard pkg).
So please give this bit another cutg.
> --- documentation/en/post-install.sgml 2001/08/16 23:57:53 1.16
> +++ documentation/en/post-install.sgml 2001/10/19 03:48:28
> @@ -30,7 +30,9 @@
> 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.
> - <p>
> +
> + <sect1>Debian Packaging System
> +<p>
> 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:
> @@ -50,6 +52,61 @@
> work, but then if you upgrade your <package>perl</package> package,
> the file you put there will be replaced. Experts can get
> around this by putting packages on ``hold'' in <prgn>dselect</prgn>.
> +<p>
> + One of the best installation methods is apt. You can use it as a
> + method from dselect, or you can use the command line version
> + (info apt-get). Note apt will also let you merge non-us, main,
> + contrib, and non-free so you can have export-restricted
> + packages as well as standard versions.
Ok.
> + <sect1>Application Version Management
> +<p>
> + Alternative versions of applications are managed by
> + update-alternatives. You can set your preferred vi by modifying
> + the symlinks in /etc/alternatives/. For example, /usr/bin/vi ->
> + /etc/alternatives/vi -> {nvi, vim, whatever you like}.
Incorrect. Just point them to the update-alternatives man page. It's
better to use 'update-alternatives' rather than fudge with the
symlinks yourslef (slave links, priorities). But don't reproduce
stuff already in that man page, just point to it.
> + <sect1>Kernel Image Management
> +<p>
> + The debian way of building a kernel is also somewhat different.
Hmm. Shouldn't we talk about installing one of the stock kernels first?
Start by explaining that the user is using one of the stock kernels
now, even though the kernel-image-* package won't show up as
installed. This is just an artifact of the way the install system
works.
The benefits of using the kernel-images is that it hooks in with the
boot loader. For instance, on i386 at least, you can install a
kernel-image, maybe it blows up, but you have 'LinuxOLD' to fall back
on.
Explain that 2.4 kernels are available as kernel-images in Woody, even
if they aren't used to install with.
On i386 explain that the compact and idepci flavors don't come with
sound, so the user might wanna try the vanilla kernel. But that
doesn't work for a lot of people, they might have to build their own.
Now we segue install kernel building....
> + Get the kernel-package package, get the kernel source tree
> + (either debian version or standard linux archive kernel will
> + work), install
Untar you mean.
> in <file>/usr/src/linux</file> (or symlink to
> + that), and for any non-std modules (i.e., pcmcia) get that
> + source too (debian module sources will install to
> + <file>/usr/src/modules</file>).
You might as well give the package name, pcmcia-source.
> Then read
> + <file>/usr/doc/kernel-packages/README.gz</file>. 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;
> + <file>/boot</file> will hold the kernel, the System.map, and a
> + log of the active config file for the build.
> + <sect1>Cron Job Management
> +<p>
> + Only personal cron jobs should be in
> + <file>/var/spool/cron/crontabs</file> on a debian server.
Why are you talking about this? The should use 'crontab -e' and not
worry where the crontabs go. You shouldn't be editing files in this
directory alone.
> Any
> + jobs under the purview of the system administrator should be in
> + <file>/etc</file>, since they are configuration files. If you
> + have a root cron job for daily, weekly, or nightly runs, put
> + them in <file>/etc/cron.{daily,weekly,monthly}</file>. These
> + are invoked from <file>/etc/crontab</file>, and will run in
> + alphabetic order, which serializes them.
Good.
> +<p>
> + 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 <file>/etc/crontab</file>, or,
> + better yet, <file>/etc/cron.d/whatever</file>. These
> + particular files also have an extra field that allows you to
> + stipulate the user under which the cron job runs.
> +<p>
> + 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
> + <file>/usr/doc/cron/README.Debian</file>.
> +
Fine.
> <![ %i386 [
> <sect id="reactivating-win">Reactivating DOS and Windows
> @@ -112,7 +169,10 @@
> <p>
> There is lots of useful documentation in <file>/usr/doc</file> as
> well. In particular, <file>/usr/doc/HOWTO</file> and
> -<file>/usr/doc/FAQ</file> contain lots of interesting information.
> +<file>/usr/doc/FAQ</file> contain lots of interesting information. To
> +submit bugs, look at <file>/usr/doc/debian/bug*</file>. To read about
> +Debian-specific issues for particular programs, look at
> +<file>/usr/doc/<pkg>/README.Debian</file>.
> <p>
> The <url id="http://&www-debian-org;/"; name="Debian web
> site"> contains a large quantity of documentation about Debian. In
> Index: documentation/en/rescue-boot.sgml
> ===================================================================
> RCS file: /cvs/debian-boot/boot-floppies/documentation/en/rescue-boot.sgml,v
> retrieving revision 1.64
> diff -u -r1.64 rescue-boot.sgml
> --- documentation/en/rescue-boot.sgml 2001/10/14 23:03:34 1.64
> +++ documentation/en/rescue-boot.sgml 2001/10/19 03:48:30
> @@ -465,7 +465,7 @@
> Open Firmware prompt:
>
> <example>
> -O >
> +0 >
> </example>
Oops, heh.
> At the prompt, type
> Index: scripts/rootdisk/messages/C/release_notes
> ===================================================================
> RCS file: /cvs/debian-boot/boot-floppies/scripts/rootdisk/messages/C/release_notes,v
> retrieving revision 1.8
> diff -u -r1.8 release_notes
> --- scripts/rootdisk/messages/C/release_notes 2001/10/15 06:52:18 1.8
> +++ scripts/rootdisk/messages/C/release_notes 2001/10/19 03:48:31
> @@ -18,3 +18,4 @@
> developing the free software concept and the GNU project.
>
> Please be sure to visit the Debian WWW site: http://www.debian.org/
> +You will find an Installation Instructions link on the home page.
Fine.
--
...Adam Di Carlo..<adam@onshore-devel.com>...<URL:http://www.onshored.com/>
Reply to: