Re: release-notes/FC4 kernel.xml,1.3,1.4

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



I suppose since these are commented out they don't affect anything
except ... well, I can't figure what.  I'm soooo curious, how do they
make editing easier?  Is it to keep track of the entities used?

BTW, I think your <screen> style is off from the style guidelines ...

http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen.html

Some of your check-ins have funky indenting ... the <para> content is
two characters from the left.  We all seem to have subtle differences.
Not sure how to resolve that.

When I get a chance, I'm going to first reformat kernel.xml, then
commit, then edit the content, all to make for a saner, happier diff.

This worked great, btw.  Everyone formed like Voltron, really brought a
lot of good content and shine to the relnotes.

- Karsten

On Mon, 2005-05-30 at 19:27 -0400, Tommy Reynolds wrote:

> +<!-- $Id: -->
> +<!--
> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"; [
> +
> + <!ENTITY BOILERPLATE "These FAKE ENTITIES are just to make editing easier" >
> + <!ENTITY FC            "FC"                                  >
> + <!ENTITY LOCALVER      "LOCALVER"                            >
> + <!ENTITY DISTRO        "DISTRO"                              >
> + <!ENTITY DISTROVER     "DISTROVER"                           >
> +
> +]>
>  -->
> +<section id="sn-kernel">
> +  <title>
> +    Linux Kernel
> +  </title>
> +  <section id="sn-kernel-lotsa">
> +    <title>Version</title>
> +    <para>
> +      The &DISTRO; is based on a 2.6.11 kernel.
> +      &FC; may include additional patches for improvements, bug fixes, or additional features.
> +      For this reason, the &FC; kernel may not be line-for-line equivalent to the so-called vanilla kernel from the <ulink url="http://ww.kernel.org";><filename>kernel.org</filename></ulink> web site.
> +    </para>
> +    <para>
> +      You may obtain a list of any such patches by using the command on the &FC; package:
> +    </para>
> +    <screen width="56"><prompt>$ </prompt><command>rpm</command> <parameter class="option">-qpl</parameter> <filename>kernel-</filename><replaceable>&lt;version&gt;</replaceable><filename>.src.rpm</filename></screen>
> +  </section>
> +  <section id="sn-kernel-flavors">
> +    <title>Kernel Flavors</title>
> +    <para>
> +      &FC; includes the following kernel builds:
> +    </para>
> +    <itemizedlist>
> +      <listitem>
> +        <para>
> +          Native kernel, in both uniprocessor and <abbrev>SMP</abbrev> varieties.
> +        </para>
> +        <para>
> +          Configured sources are available in the <filename>kernel-devel-</filename><replaceable>&lt;version&gt;</replaceable><filename>.</filename><replaceable>&lt;arch&gt;</replaceable><filename>.rpm</filename> package.
> +        </para>
> +      </listitem>
> +      <listitem>
> +        <para>
> +          Virtual kernel for use with the <wordasword>XEN</wordasword> emulator package.
> +        </para>
> +        <para>
> +          Configured sources are available in the <filename>kernel-xen0-devel-</filename><replaceable>&lt;version&gt;</replaceable><filename>.</filename><replaceable>&lt;arch&gt;</replaceable><filename>.rpm</filename> package.
> +        </para>
> +      </listitem>
> +    </itemizedlist>
> +    <para>
> +      Sources for both kernel flavors may be installed at the same time.
> +      The files will be installed into the <filename>/usr/src/kernels/</filename><replaceable>&lt;version&gt;</replaceable>[<filename>-xen0</filename>]<filename>-</filename><replaceable>&lt;arch&gt;</replaceable><filename>/</filename> tree.
> +      Use the command:
> +    </para>
> +    <screen width="56"><prompt># </prompt><command>rpm</command> <parameter class="option">-Uvh</parameter> <filename>kernel-devel[-xen0]-</filename><replaceable>&lt;version&gt;</replaceable><filename>.</filename><replaceable>&lt;arch&gt;</replaceable><filename>.rpm</filename></screen>
> +    <para>
> +      as appropriate.
> +    </para>
> +    <tip>
> +      <title>Following Generic Textbooks</title>
> +      <para>
> +        Many of the tutorials, examples, and textbooks about Linux kernel development assume the kernel sources are installed under the <filename>/usr/src/linux</filename> directory.
> +        If you make a symbolic link, as shown below, you should be able to use those learning materials with the &FC; packages.
> +        Install the appropriate kernel sources, as shown earlier, and then:
> +      </para>
> +      <screen width="56"><prompt># </prompt><command>ln</command> <parameter class="option">-s</parameter> <filename>/usr/src/kernels/kernel-</filename><replaceable>&lt;all-the-rest&gt;</replaceable> <filename>/usr/src/linux</filename></screen>
> +    </tip>
> +  </section>
> +  <!--
>    <tip>
>      <title>Using <command>yum</command> to Uninstall Kernel
>      Packages</title>
>      <para>
> -      &FC; &LOCALVER; contains support for clustering systems using CMAN
> -      and GFS. These kernels require assistance from some user-space
> -      packages.  These packages are not removed when using <command>rpm
> -      -e</command> to uninstall older versions of the kernel packages.
> +      &FC; &LOCALVER; contains support for clustering systems using CMAN and GFS.
> +      These kernels require assistance from some user-space packages.
> +      These packages are not removed when using <command>rpm -e</command> to uninstall older versions of the kernel packages.
>      </para>
>      <para>
> -      When using <command>rpm -e
> -	kernel-<replaceable>&lt;version&gt;</replaceable></command> to
> -      uninstall the kernel, you must also remove the assisting
> -      user-space packages.  You may wish to consider a dependecy
> -      resolving tool such as <command>yum remove
> -	kernel-<replaceable>&lt;version&gt;</replaceable></command>.
> +      When using <command>rpm -e kernel-<replaceable>&lt;version&gt;</replaceable> </command> to uninstall the kernel, you must also remove the assisting user-space packages.  You may wish to consider a dependecy resolving tool such as <command>yum remove kernel-<replaceable>&lt;version&gt;</replaceable> </command>.
>        This automatically removes any dependant packages.
>      </para>
>    </tip>
> -  <para>
> -    In order to eliminate the redundancy inherent in providing a
> -    separate package for the kernel source code when that source code
> -    already exists in the kernel's <filename>.src.rpm</filename> file,
> -    &DISTRO; &DISTROVER; no longer includes the
> -    <filename>kernel-source</filename> package.  Users that require
> -    access to the kernel sources can find them in the
> -    <filename>kernel</filename> <filename>.src.rpm</filename> file. To
> -    create an exploded source tree from this file, perform the following
> -    steps (note that
> -    <filename><replaceable>&lt;version&gt;</replaceable></filename>
> -    refers to the version specification for your currently-running
> -    kernel):
> -  </para>
> -  <procedure>
> -    <step>
> -      <para>
> -	Obtain the
> -	<filename>kernel-<replaceable>&lt;version&gt;</replaceable>.src.rpm</filename> 
> -	file from one of the following sources:
> -      </para>
> -      <itemizedlist>
> -	<listitem>
> -	  <para>
> -	    The <filename>SRPMS</filename> directory on the appropriate
> -	    "SRPMS" CD iso image
> -	  </para>
> -	</listitem>
> -	<listitem>
> -	  <para>
> -	    The FTP site where you got the kernel package
> -	  </para>
> -	</listitem>
> -	<listitem>
> -	  <para>
> -	    By running the following command:
> -	  </para>
> -	  <para>
> -	    <command>up2date --get-source kernel</command>
> -	  </para>
> -	</listitem>
> -      </itemizedlist>
> -    </step>
> -    <step>
> -      <para>
> -	Install
> -	<filename>kernel-<replaceable>&lt;version&gt;</replaceable>.src.rpm</filename> 
> -	(given the default RPM configuration, the files this package
> -	contains will be written to
> -	<filename>/usr/src/redhat/</filename>)
> -      </para>
> -    </step>
> -    <step>
> -      <para>
> -	Change directory to <filename>/usr/src/redhat/SPECS/</filename>,
> -	and issue the following command:
> -      </para>
> -      <para>
> -	<command>rpmbuild -bp
> -	  --target=<replaceable>&lt;arch&gt;</replaceable>
> -	  kernel.spec</command>
> -      </para>
> -      <para>
> -	(Where
> -	<command><replaceable>&lt;arch&gt;</replaceable></command> is
> -	the desired target architecture.)
> -      </para>
> -      <para>
> -	On a default RPM configuration, the kernel tree will be located
> -	in <filename>/usr/src/redhat/BUILD/</filename>.
> -      </para>
> -    </step>
> -    <step>
> -      <para>
> -	In the resulting tree, the configurations for the specific
> -	kernels shipped in &DISTRO; &DISTROVER; are in the
> -	<filename>/configs/</filename> directory.  For example, the i686
> -	SMP configuration file is named
> -	<filename>/configs/kernel-<replaceable>&lt;version&gt;</replaceable>-i686-smp.config</filename>. 
> -	Issue the following command to place the desired configuration
> -	file in the proper place for building:
> -      </para>
> -      <para>
> -	<command>cp <replaceable>&lt;desired-file&gt;</replaceable>
> -	  ./.config</command>
> -      </para>
> -    </step>
> -    <step>
> -      <para>
> -	Issue the following command:
> -      </para>
> -      <para>
> -	<command>make oldconfig</command>
> -      </para>
> -    </step>
> -  </procedure>
> -  <para>
> -    You can then proceed as usual.
> +  -->
> +  <section id="sn-kernel-exploding">
> +    <title>
> +      Preparing for Kernel Development
> +    </title>
> +    <para>
> +      &DISTRO; &DISTROVER; does not include the <filename>kernel-source</filename> package provided by older versions.
> +      Instead, configured sources are available as described in <xref linkend="sn-kernel-flavors"/>.
> +      Users that require access to &FC; original kernel sources can find them in the <filename>kernel</filename> <filename>.src.rpm</filename> package.
> +      To create an exploded source tree from this file, perform the following steps:
>    </para>
> -  <tip>
> -    <title>Source not required to build kernel modules</title>
> +  <warning>
> +    <title>These Instructions Refer The Currently-running Kernel!</title>
> +    <para>
> +      To simplify the following directions, we have assumed that you want to configure the kernel sources to match your currently-running kernel.
> +      In the steps below, you must understand that the phrase <wordasword>&lt;version&gt;</wordasword> refers to the kernel version shown by the:
> +    </para>
> +    <screen width="56"><prompt>$ </prompt><command>uname</command> <parameter class="option">-r</parameter></screen>
> +    <para>
> +      command.
> +    </para>
> +  </warning>
> +    <procedure id="sn-kernel-exploding-steps">
> +      <step>
> +        <para>
> +          Obtain the <filename>kernel-<replaceable>&lt;version&gt;</replaceable>.src.rpm</filename> file from one of the following sources:
> +        </para>
> +        <itemizedlist>
> +          <listitem>
> +            <para>
> +                The <filename>SRPMS</filename> directory on the appropriate <wordasword>SRPMS</wordasword> <abbrev>CD</abbrev> <filename>iso</filename> image.
> +              </para>
> +          </listitem>
> +          <listitem>
> +            <para>
> +              The FTP site where you got the kernel package.
> +            </para>
> +          </listitem>
> +          <listitem>
> +            <para>
> +              By running the following command:
> +            </para>
> +            <screen width="56"><prompt># </prompt><command>up2date</command> <parameter class="option">--get-source</parameter> <filename>kernel</filename></screen>
> +          </listitem>
> +        </itemizedlist>
> +      </step>
> +      <step>
> +        <para>
> +          Install  <filename>kernel-<replaceable>&lt;version&gt;</replaceable>.src.rpm</filename> using the command:
> +        </para>
> +        <screen width="56"><prompt># </prompt><command>rpm</command> <parameter class="option">-Uvh</parameter> <filename>kernel-</filename><replaceable>&lt;version&gt;</replaceable><filename>.src.rpm</filename></screen>
> +        <para>
> +          This writes the <abbrev>RPM</abbrev> contents into <filename>/usr/src/redhat/SOURCES</filename> and <filename>/usr/src/redhat/SPECS</filename>.
> +        </para>
> +      </step>
> +      <step>
> +        <para>
> +          Prepare the kernel sources using the commands:
> +        </para>
> +        <screen width="56"><prompt># </prompt><command>cd</command> <filename>/usr/src/redhat/SPECS</filename>
> +<prompt># </prompt><command>rpmbuild</command> <parameter class="option">-bp --target $(arch)</parameter> <filename>kernel.spec</filename></screen>
> +        <para>
> +          The kernel source tree will be located in the <filename>/usr/src/redhat/BUILD/kernel-</filename><replaceable>&lt;version&gt;</replaceable> directory.
> +          It is common practice to move the resulting <filename>linux-</filename><replaceable>&lt;version&gt;</replaceable> directory to the <filename>/usr/src</filename> tree; while not strictly necessary, we suggest that you do this to match the generally-available documentation.
> +        </para>
> +        <screen width="56"><prompt># </prompt><command>cd</command> <filename>/usr/src/redhat/BUILD/kernel-</filename><replaceable>&lt;version&gt;</replaceable> <filename>/usr/src/</filename>
> +<prompt># </prompt><command>mv</command> <filename>linux-</filename><replaceable>&lt;version&gt;</replaceable> <filename>/usr/src/</filename>
> +<prompt># </prompt><command>cd</command> <filename>/usr/src</filename>
> +<prompt># </prompt><command>ln</command> <parameter class="option">-s</parameter> <filename>./linux-</filename><replaceable>&lt;version&gt;</replaceable> <filename>linux</filename>
> +<prompt># </prompt><command>cd</command> <filename>/usr/src/linux</filename></screen>
> +      </step>
> +      <step>
> +        <para>
> +          The configurations for the specific kernels shipped in &DISTRO; &DISTROVER; are in the <filename>configs/</filename> directory.
> +          For example, the i686 SMP configuration file is named <filename>configs/kernel-<replaceable>&lt;version&gt;</replaceable>-i686-smp.config</filename>.
> +          Issue the following command to place the desired configuration file in the proper place for building:
> +        </para>
> +        <screen width="56"><prompt># </prompt><command>cp</command> <filename>configs/</filename><replaceable>&lt;desired-config-file&gt;</replaceable> <filename>.config</filename></screen>
> +      </step>
> +      <step>
> +        <para>
> +          Issue the following command:
> +        </para>
> +        <screen width="56"><prompt># </prompt><command>make oldconfig</command></screen>
> +      </step>
> +    </procedure>
> +    <para>
> +      You can then proceed as usual.
> +    </para>
> +  </section>
> +  <section id="sn-kernel-3rdparty">
> +    <title>Building Only Kernel Modules</title>
>      <para>
> -      An exploded source tree is <emphasis>not</emphasis> required to
> -      build kernel modules against the currently in-use kernel.
> +      An exploded source tree is <emphasis>not</emphasis> required to build a kernel module, such as your own device driver, against the currently in-use kernel.
>      </para>
>      <para>
> -      For example, to build the <filename>foo.ko</filename> module,
> -      create the following file (named <filename>Makefile</filename>) in
> -      the directory containing the <filename>foo.c</filename> file:
> +      For example, to build the <filename>foo.ko</filename> module, create the following <filename>Makefile</filename> in the directory containing the <filename>foo.c</filename> file:
>      </para>
> -<screen>
> -<computeroutput>
> -obj-m    := foo.o
> +<programlisting width="56">
> +obj-m := foo.o
>  
> -KDIR    := /lib/modules/$(shell uname -r)/build
> -PWD    := $(shell pwd)
> +KDIR  := /lib/modules/$(shell uname -r)/build
> +PWD   := $(shell pwd)
>  
>  default:
> -    $(MAKE) -C $(KDIR) SUBDIRS=$(PWD) modules
> -</computeroutput>
> -</screen>
> -    <para>
> +    $(MAKE) -C $(KDIR) M=$(PWD) modules
> +</programlisting>
> +      <para>
>        Issue the <command>make</command> command to build the
>        <filename>foo.ko</filename> module.
>      </para>
> -  </tip>
> +  </section>
> +  <section id="sn-kernel-coop">
> +    <title>Userspace Dependancies on the Kernel</title>
> +    <para>
> +      &DISTRO; adds support for clustered systems.
> +      This requires a special kernel that works in conjunction with some user-space utilities, such as management daemons.
> +      Consequently, to remove such a kernel, perhaps after an update, you <emphasis>cannot</emphasis> simply use the <command>rpm -e kernel-</command><replaceable>&lt;version&gt;</replaceable> command as in earlier distributions because these userspace packages depend on the kernel package.
> +      You may either list both the kernel package and its userspace dependant packages on the <command>rpm -e</command> command, or you may wish to use the <command>yum remove kernel-</command><replaceable>&lt;version&gt;</replaceable> command instead since <command>yum</command> automatically removes dependant packages if necesssary.
> +    </para>
> +  </section>
>  </section>
>  <!--
>  Local variables:
> 
> --
> Fedora-docs-commits mailing list
> Fedora-docs-commits@xxxxxxxxxx
> https://www.redhat.com/mailman/listinfo/fedora-docs-commits
-- 
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint:  2680 DBFD D968 3141 0115    5F1B D992 0E06 AD0E 0C41   
                       Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/

Attachment: signature.asc
Description: This is a digitally signed message part

-- 

fedora-docs-list@xxxxxxxxxx
To unsubscribe: 
http://www.redhat.com/mailman/listinfo/fedora-docs-list

[Index of Archives]     [Fedora Users]     [Fedora Desktop]     [Red Hat 9]     [Yosemite News]     [KDE Users]

  Powered by Linux