Linux Archive - Improvements to doc/en/genkernel.xml

Change log (top to bottom in patch):
- Remove obsolete disclaimer
- Use simpler English (no "akin", no "privy")
- Remove misleading note on module parameters
- Remove notes on Gentoo Reference Platform
- Mention --symlink
- Mention incompleteness of options/flags, point to better sources
- Indicate incompleteness by repeated addition of "..."
- Fix misleading highlighting of --no-ramdisk-modules
- Mention --disklabel, --iscsi, --multipath
- Remove outdated notes on root=/dev/ram0 and init=/linuxrc
- Migrate from hda to sda

All of this applies to genkernel stable.

Thanks for consideration.

Best,

Sebastian
Index: genkernel.xml
================================================== =================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/genkernel.xml,v
retrieving revision 1.34
diff -u -r1.34 genkernel.xml
--- genkernel.xml 7 Dec 2010 20:49:23 -0000 1.34
+++ genkernel.xml 16 Jan 2011 16:18:31 -0000
@@ -2,7 +2,7 @@

<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

-<guide disclaimer="obsolete">
+<guide>
<title>Gentoo Linux Genkernel Guide</title>

<author title="Author">
@@ -32,8 +32,8 @@

<license/>

-<version>4</version>
-<date>2010-12-07</date>
+<version>5</version>
+<date>2011-01-16</date>

<chapter>
<title>Introduction</title>
@@ -42,14 +42,11 @@
<body>


-For users who are not privy to kernel compilation, genkernel is a tool to
-automate this process. It can help you create a kernel image akin to those
+For users who do not want to engage with kernel compilation, genkernel is a tool to
+automate this process. It can help you create a kernel image similar to those
available on Gentoo Installation CDs, which are designed to auto-detect the
hardware configuration of your system. Some users may also be interested in
-using genkernel for hardware requiring initialization and a working kernel
-before the system starts up. Since genkernel automatically compiles your kernel
-modules, you can use hardware that may require certain module parameters to be
-loaded for proper operation.
+using genkernel for hardware requiring initialization before the system starts up.


</body>
@@ -81,11 +78,8 @@
<body>


-To obtain genkernel, run <c>emerge genkernel</c> from the command line. If you
-are using the <uri link="/doc/en/handbook/2008.0/hb-install-about.xml">Gentoo
-Reference Platform</uri> (GRP), remember to install binary packages by passing
-the <c>-k</c> flag to emerge. Since the GRP is bundled with an older version
-of genkernel, the flags may be different. In any case, consult <c>genkernel
+To obtain genkernel, run <c>emerge genkernel</c> from the command line.
+Consult <c>man genkernel</c> or <c>genkernel
--help</c> for help on how to use the version of genkernel installed on your
system.

@@ -127,7 +121,8 @@
There are other flags which alter the result provided by genkernel. For
instance, replacing <c>--no-install</c> with the <c>--install</c> flag allows
genkernel to automatically install the new kernel in the <path>/boot</path>
-directory. Using the <c>--mountboot</c> flag allows genkernel to mount your
+directory, and create symlinks for you if <c>--symlink</c> is specified.
+Using the <c>--mountboot</c> flag allows genkernel to mount your
<path>/boot</path> partition automatically, if necessary.


@@ -142,8 +137,10 @@



-The rest of this chapter examines the functionality of various flags and
-actions available for genkernel. Some of the flags have variants which perform
+The rest of this chapter examines the functionality of selected flags, configuration
+variables and actions available for genkernel. For a more complete list please
+refer to <c>man genkernel</c> and the comments in <path>/etc/genkernel.conf</path>.
+Some of the flags have variants which perform
a converse operation. The converse variants carry the <c>no-</c> prefix,
and their effects are enclosed within the square brackets, [].

@@ -188,6 +185,9 @@
configuration to a file in the <path>/etc/kernels/</path> directory for
later use.
</li>
+ <li>
+ ...
+ </li>
</ul>

</body>
@@ -263,7 +263,7 @@
compiled modules will be installed as well.
</li>
<li>
- --<c>no-</c>ramdisk-modules: Refrains from copying any modules to the
+ --no-ramdisk-modules: Refrains from copying any modules to the
genkernel-created initrd image. This flag is an exception to the rule about
the <c>no-</c> prefix; omission of this prefix creates an invalid genkernel
flag.
@@ -276,6 +276,9 @@
--genzimage: Creates the initrd image, prior to the kernel image.
(This hack currently applies only to PPC Pegasos systems.)
</li>
+ <li>
+ ...
+ </li>
</ul>

</body>
@@ -341,6 +344,9 @@
</e><c>-j3</c><e> flag, provided Symmetric Multi-Processing (SMP) support is
enabled in the kernel.)</e>
</li>
+ <li>
+ ...
+ </li>
</ul>

</body>
@@ -372,6 +378,9 @@
--no-color: Activates <e>[or deactivates]</e> colored output of
debugging information (reported by genkernel) using escape sequences.
</li>
+ <li>
+ ...
+ </li>
</ul>

</body>
@@ -444,6 +453,15 @@
creates).
</li>
<li>
+ --disklabel: Adds support for disk label and UUID support to your initrd.
+ </li>
+ <li>
+ --iscsi: Adds support for iSCSI to your initrd.
+ </li>
+ <li>
+ --multipath: Adds support for Multipath to your initrd.
+ </li>
+ <li>
--linuxrc=/path/to/your/linuxrc: Specifies a user-created
<e>linuxrc</e> — a script that is initialized during the start-up
stage of the kernel, prior to the actual boot process. (A default linuxrc
@@ -464,6 +482,9 @@
link="http://www.fsl.cs.sunysb.edu/project-unionfs.html">Unification File
System</uri> in the initrd image.
</li>
+ <li>
+ ...
+ </li>
</ul>

</body>
@@ -490,6 +511,9 @@
images produced are kernel-<c>NickName</c>-version and
initramfs-<c>NickName</c>-version.
</li>
+ <li>
+ ...
+ </li>
</ul>

</body>
@@ -532,12 +556,8 @@

<ol>
<li>
- Add <c>root=/dev/ram0</c> and <c>init=/linuxrc</c> to the kernel parameters
- passed to the kernel image.
- </li>
- <li>
- Add <c>real_root=/dev/hda3</c>, for example, to the kernel parameters
- passed to the kernel image, if <path>/dev/hda3</path> contains your root
+ Add <c>real_root=/dev/sda3</c>, for example, to the kernel parameters
+ passed to the kernel image, if <path>/dev/sda3</path> contains your root
partition.
</li>
<li>
@@ -634,9 +654,17 @@
genkernel; setting this option to '5' with <c>--loglevel=5</c> provides
the user with all output produced by genkernel.
</li>
+ <li>
+ ...
+ </li>
</ul>


+More options are desribed in <path>/etc/genkernel.conf</path>.
+Most of the commad line flags mentioned above have an option counterpart in that file.
+
+
+
By choosing the appropriate options in <path>/etc/genkernel.conf</path>, you
can halve the number of flags passed to genkernel from the command line: