introduction: Use new kernel configuration rendering in conventions

introduction/welcome/conventions-kernel.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE note PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!-- Automatically generated by kernel-config.py
+     DO NOT EDIT! -->
+<screen>M<emphasis role='blue'>a</emphasis>ster section ---&gt;
+  <emphasis role='blue'>S</emphasis>ubsection ---&gt;
+    [*]     <emphasis role='blue'>R</emphasis>equired parameter                                        [REQU_PAR]
+    &lt;*&gt;     <emphasis role='blue'>R</emphasis>equired parameter (not as module)                   [REQU_PAR_NMOD]
+    &lt;*/M&gt;   <emphasis role='blue'>R</emphasis>equired parameter (could be a module)                [REQU_PAR_MOD]
+    &lt;M&gt;     <emphasis role='blue'>R</emphasis>equired parameter (as a module)                 [REQU_PAR_MOD_ONLY]
+    &lt; /*/M&gt; <emphasis role='blue'>O</emphasis>ptional parameter                                         [OPT_PAR]
+    &lt; /M&gt;   <emphasis role='blue'>O</emphasis>ptional parameter (as a module if enabled)       [OPT_PAR_MOD_ONLY]
+    [ ]     <emphasis role='blue'>I</emphasis>ncompatible parameter                                  [INCOMP_PAR]
+    &lt; &gt;     <emphasis role='blue'>I</emphasis>ncompatible parameter (even as module)             [INCOMP_PAR_MOD]</screen>

introduction/welcome/conventions.xml

@@ -135,18 +135,14 @@ EOF</userinput></screen>
     <para>Some packages require specific kernel configuration options.
     The general layout for these looks like this:</para>
 
-<screen><literal>Master section ---&gt;
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
-  Subsection ---&gt;
+      href="conventions-kernel.xml"/>
-    [*]     Required parameter                     [CONFIG_REQU_PAR]
-    &lt;*&gt;     Required parameter (not as module)     [CONFIG_REQU_PAR_NMOD]
-    &lt;*/M&gt;   Required parameter (could be a module) [CONFIG_REQU_PAR_MOD]
-    &lt;*/M/ &gt; Optional parameter                     [CONFIG_OPT_PAR]
-    [ ] Incompatible parameter                     [CONFIG_INCOMP_PAR]
-    &lt; &gt; Incompatible parameter (even as module)    [CONFIG_INCOMP_PAR_MOD]</literal></screen>
 
-    <para>[CONFIG_...] on the right gives the name of the option, so you can
+    <para>[...] on the right gives the symbolic name of the option, so you
-    easily check whether it is set in your <filename>.config</filename> file.
+    can easily check whether it is set in your <filename>.config</filename>
-    The meaning of the various entries is:
+    file. Note that the <filename>.config</filename> file contains a
+    <literal>CONFIG_</literal> prefix before all symbolic names.  The
+    meaning of the various entries is:
 
     <blockquote>
     <informaltable frame='none'><tgroup cols="2">
@@ -187,13 +183,36 @@ EOF</userinput></screen>
           it must be selected, either as built-in or as a module
         </entry>
       </row>
+      <row>
+        <entry>
+          <emphasis role="bold">Required parameter (as
+          a module)</emphasis>
+        </entry>
+        <entry>
+          the option can be built-in, a module, or not selected:
+          it must be selected as a module; selecting it as built-in
+          may cause unwanted effects
+        </entry>
+      </row>
       <row>
         <entry>
           <emphasis role="bold">Optional parameter</emphasis>
         </entry>
         <entry>
-          rarely used: the option can be built-in, a module, or not
+          the option can be built-in, a module, or not
-          selected: it may be set any way you wish
+          selected: it may be selected as a module or built-in if you
+          need it for driving the hardware or optional kernel features
+        </entry>
+      </row>
+      <row>
+        <entry>
+          <emphasis role="bold">Optional parameter</emphasis>
+        </entry>
+        <entry>
+          the option can be built-in, a module, or not
+          selected: it may be selected as a module if you need it
+          for driving the hardware or optional kernel features, but
+          selecting it as built-in may cause unwanted effects
         </entry>
       </row>
       <row>
@@ -224,6 +243,13 @@ EOF</userinput></screen>
     The help text describing the option specifies the other selections on which this
     option relies, and how those other selections are set.</para>
 
+    <para>
+      The letter in <emphasis role='blue'>blue</emphasis> is the hotkey
+      for this option.  If you are running
+      <command>make menuconfig</command>, you can press a key to quickly
+      traverse all the options with this key as the hotkey on the screen.
+    </para>
+
     <para>&nbsp;</para> <!-- add extra white space to improve readability -->
   </sect2>
 

kernel-config/Makefile

@@ -5,7 +5,7 @@ ifeq ($(KERNEL_TREE),)
 $(error "must set KERNEL_TREE=/path/to/kernel/source")
 endif
 
-all: $(OUTPUT)
+all: $(OUTPUT) ../introduction/welcome/conventions-kernel.xml
 
 kernel.version: s-kernel-version; @true
 s-kernel-version: Makefile kernel_version.py
@@ -17,3 +17,6 @@ s-kernel-version: Makefile kernel_version.py
 
 ../%-kernel.xml: %.toml kernel-config.py kernel_version.py kernel.version
 	./kernel-config.py $(KERNEL_TREE) $< > $@
+
+../introduction/welcome/conventions-kernel.xml: kernel-config.py testdata/Kconfig testdata/config.toml.example
+	./kernel-config.py testdata testdata/config.toml.example > $@

kernel-config/kernel-config.py

@@ -301,9 +301,6 @@ for i0, val, i1, title, arrow, key, menu, comment in r:
 
     buf += [line.rstrip()]
 
-import kernel_version
-kver = kernel_version.kernel_version(path)
-
 from jinja2 import Template
 
 t = Template('''<?xml version="1.0" encoding="ISO-8859-1"?>

kernel-config/testdata/Kconfig

@@ -0,0 +1,31 @@
+menu "Master section"
+
+menu "Subsection"
+
+config REQU_PAR
+	bool "Required parameter"
+
+config REQU_PAR_NMOD
+	tristate "Required parameter (not as module)"
+
+config REQU_PAR_MOD
+	tristate "Required parameter (could be a module)"
+
+config REQU_PAR_MOD_ONLY
+	tristate "Required parameter (as a module)"
+
+config OPT_PAR
+	tristate "Optional parameter"
+
+config OPT_PAR_MOD_ONLY
+	tristate "Optional parameter (as a module if enabled)"
+
+config INCOMP_PAR
+	bool "Incompatible parameter"
+
+config INCOMP_PAR_MOD
+	tristate "Incompatible parameter (even as module)"
+
+endmenu # subsection
+
+endmenu # master section

kernel-config/testdata/config.toml.example

@@ -0,0 +1,8 @@
+REQU_PAR='*'
+REQU_PAR_NMOD='*'
+REQU_PAR_MOD='*M'
+OPT_PAR='*M '
+INCOMP_PAR=' '
+INCOMP_PAR_MOD=' '
+REQU_PAR_MOD_ONLY='M'
+OPT_PAR_MOD_ONLY=' M'