Draft content

intermediate changes intermediate changes draft content complete Solved build problem by changing root element from topic to article Fixed typo trivial changes Fixes based on review comments Splitting DC file into two for profiling using PROFOS intermediate changes total revamp of core content restructuring in progress Intermediate changes in assembly structure rearrangements temporary and permanent procedure modularization linuxrc difference partial modularization complete modularization; attempting solution of build errors build problem solved removed the generic profiling dc file
SUSE · Mar 4, 2024 · e64595d · e64595d
1 parent a4dff01
commit e64595d
Show file tree

Hide file tree

Showing 11 changed files with 826 additions and 321 deletions.
diff --git a/DC-kernel-boot-parameters-modify-non-sles b/DC-kernel-boot-parameters-modify-non-sles
@@ -0,0 +1,21 @@
+## Basics
+MAIN="kernel-boot-parameters-modify.asm.xml"
+SRC_DIR="articles"
+ROOTID="kernel-boot-parameters-modify"
+IMG_SRC_DIR="images"
+
+# Profiling
+PROFOS="non-sles"
+PROFARCH="x86_64;zseries;power;aarch64"
+PROFCONDITION="suse-product;beta"
+PROFCONDITION="community-project"
+
+# When content is ready for publication, comment the 
+# line below or set DRAFT=0
+DRAFT=0
+
+## stylesheet location
+STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
+FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse-ns"
+
+DOCBOOK5_RNG_URI="urn:x-suse:rng:v2:geekodoc-flat"
diff --git a/DC-kernel-boot-parameters-modify-sles b/DC-kernel-boot-parameters-modify-sles
@@ -0,0 +1,21 @@
+## Basics
+MAIN="kernel-boot-parameters-modify.asm.xml"
+SRC_DIR="articles"
+ROOTID="kernel-boot-parameters-modify"
+IMG_SRC_DIR="images"
+
+# Profiling
+PROFOS="sles"
+PROFARCH="x86_64;zseries;power;aarch64"
+PROFCONDITION="suse-product;beta"
+PROFCONDITION="community-project"
+
+# When content is ready for publication, comment the 
+# line below or set DRAFT=0
+DRAFT=0
+
+## stylesheet location
+STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
+FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse-ns"
+
+DOCBOOK5_RNG_URI="urn:x-suse:rng:v2:geekodoc-flat"
diff --git a/DC-task-modify-kernel-boot-parameter b/DC-task-modify-kernel-boot-parameter
diff --git a/articles/kernel-boot-parameters-modify.asm.xml b/articles/kernel-boot-parameters-modify.asm.xml
@@ -0,0 +1,215 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- file: templates/articles/assembly.xml -->
+<?xml-model href="https://cdn.docbook.org/schema/5.2/rng/assemblyxi.rnc"
+            type="application/relax-ng-compact-syntax"?>
+<!DOCTYPE assembly
+[
+    <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
+<!-- point back to this document with a similar comment added to your legacy doc piece -->
+<!-- refer to README.md for file and id naming conventions -->
+<assembly version="5.2" xml:lang="en"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:trans="http://docbook.org/ns/transclusion"
+          xmlns:its="http://www.w3.org/2005/11/its"
+          xmlns="http://docbook.org/ns/docbook">
+  <!-- resources section references all topic chunks used in the final article
+    -->
+  <!-- R E S O U R C E S -->
+  <!-- Glue files -->
+  <resources>
+    <resource xml:id="_kernel-boot-parameters-modify-more-info" href="../glues/kernel-boot-parameters-modify-more-info.xml">
+      <description>For more information</description>
+    </resource>
+  </resources>
+  <!-- Concept files -->
+  <resources>
+    <resource xml:id="_kernel-boot-parameters-modify-introduction" href="../concepts/kernel-boot-parameters-modify-introduction.xml">
+      <description>Introduction to kernel boot parameters</description>
+    </resource>
+    <resource xml:id="_kernel-boot-parameters-modify-difference-linuxrc-parameters" href="../concepts/kernel-boot-parameters-modify-difference-linuxrc-parameters.xml">
+     <description>Difference between kernel boot parameters and linuxrc parameters</description>
+   </resource>
+  </resources>
+  <!-- Tasks -->
+  <resources>
+    <resource xml:id="_kernel-boot-parameters-modify-temporary" href="../tasks/kernel-boot-parameters-modify-temporary.xml">
+      <description>Temporarily modify kernel boot parameters</description>
+    </resource>
+    <resource xml:id="_kernel-boot-parameters-modify-permanent" href="../tasks/kernel-boot-parameters-modify-permanent.xml">
+     <description>Permanently modify kernel boot parameters</description>
+   </resource>
+   <resource xml:id="_kernel-boot-parameters-modify-troubleshoot" href="../tasks/kernel-boot-parameters-modify-troubleshoot.xml">
+    <description>Troubleshooting modified kernel boot parameters</description>
+  </resource>
+  </resources>
+  <!-- Legal -->
+  <resources>
+    <resource href="../common/legal.xml" xml:id="_legal">
+      <description>Legal Notice</description>
+    </resource>
+    <resource href="../common/license_gfdl1.2.xml" xml:id="_gfdl">
+      <description>GNU Free Documentation License</description>
+    </resource>
+  </resources>
+  <!-- S T R U C T U R E -->
+  <structure renderas="article" xml:id="kernel-boot-parameters-modify" xml:lang="en">
+    <merge>
+      <title>Modifying kernel boot parameters</title>
+      <!--subtitle>Subtitle if necessary</subtitle-->
+      <!-- Create changelog to enable versioning; add most recent entries at the top. -->
+      <revhistory xml:id="rh-kernel-boot-parameters-modify">
+        <revision><revnumber>1</revnumber><date>2023-11-28</date>
+          <revdescription>
+            <para>
+              Initial version
+            </para>
+          </revdescription>
+        </revision>
+      </revhistory>
+      <!-- TODO: provide a listing of possible and validatable meta entry values. Maybe in our geekodoc repo? -->
+      <!-- add author's e-mail -->
+      <meta name="maintainer" content="[email protected]" its:translate="no"/>
+      <!-- ISO date of last update as YYYY-MM-DD -->
+      <meta name="updated" content="2023-11-28" its:translate="no"/>
+      <!-- this does not work yet. Use the dm tags listed below for now
+        <meta name="bugtracker" its:translate="no">
+        <phrase role="url">https://bugzilla.suse.com/enter_bug.cgi</phrase>
+        <phrase role="component">Non-product-specific documentation</phrase>
+        <phrase role="product">Smart Docs</phrase>
+        <phrase role="assignee">[email protected]</phrase>
+        </meta>
+        -->
+      <!-- not supported, yet. Use dm: tag for now
+        <meta name="translation" its:translate="no">
+        <phrase role="trans">yes</phrase>
+        <phrase role="language">de-de,cs-cz</phrase>
+        </meta>
+        -->
+      <!-- enter the platform identifier or a list of
+        identifiers, separated by ; -->
+      <meta name="architecture" content="x86" its:translate="no"/>
+      <meta name="productname" its:translate="no">
+        <!-- enter product name and version --><productname version="15-SP5">&sles;</productname><productname version="15-SP4">&sles;</productname><productname version="15-SP3">&sles;</productname><productname version="15-SP2">&sles;</productname><productname version="15-SP1">&sles;</productname><productname version="15-GA">&sles;</productname>
+      </meta>
+      <meta name="title" its:translate="yes">Modifying kernel boot parameters</meta>
+      <meta name="description" its:translate="yes">Concepts, examples and modification process of kernel boot
+        parameters for customizing the boot process.</meta>
+      <meta name="social-descr" its:translate="yes">Process for modifying
+      kernel boot parameters</meta>
+      <!-- suitable category, comma-separated list of categories -->
+      <meta name="category" content="Systems Management" its:translate="no"/>
+      <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
+        <dm:bugtracker>
+          <dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
+          <dm:component>Smart Docs</dm:component>
+          <dm:product>Documentation</dm:product>
+          <dm:assignee>[email protected]</dm:assignee>
+        </dm:bugtracker>
+        <dm:translation>yes</dm:translation>
+      </dm:docmanager>
+      <abstract>
+        <variablelist>
+          <varlistentry>
+            <term>WHAT?</term>
+            <listitem>
+              <para>
+                Concepts, examples and modification process of kernel boot
+                parameters for customizing the boot process and the subsequent
+                environment.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>WHY?</term>
+            <listitem>
+              <para>
+                Modifying kernel boot parameters is essential for achieving
+                specific system configurations and addressing several
+                scenarios, including performance optimization, better hardware
+                compatibility, and troubleshooting issues such as graphics
+                drivers.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>EFFORT</term>
+            <listitem>
+              <para>
+                It 15 minutes to fully understand the concepts and the process,
+                and 5 minutes to modify kernel boot parameters and observe its
+                effect after reboot.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>GOAL</term>
+            <listitem>
+              <para>
+                Modify kernel parameters to customize the boot process and the
+                subsequent environment.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>REQUIREMENTS</term>
+            <listitem>
+              <para>
+                Depending on whether you want to apply changes in kernel boot
+                parameters to the upcoming boot process, or all subsequent boot
+                processes, the requirements are as follows:
+              </para>
+              <itemizedlist>
+                <listitem>
+                  <para>
+                    To change kernel boot parameters on an experimental basis
+                    only for the upcoming boot process, there are no
+                    requirements.
+                  </para>
+                </listitem>
+                <listitem>
+                  <para>
+                    To change kernel boot parameters for all subsequent boot
+                    processes, you should have <literal>root</literal> or
+                    equivalent administrative privileges.
+                  </para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+      </abstract>
+    </merge>
+    <!-- pull in all the topic files you need -->
+    <!-- pick the appropriate type of include to match your needs -->
+    <!-- pull in a topic as is -->
+    <!--concept-->
+    <module resourceref="_kernel-boot-parameters-modify-introduction" renderas="section"/>
+    <!--concept-->
+    <module resourceref="_kernel-boot-parameters-modify-difference-linuxrc-parameters" renderas="section"/>
+    <!--task-->
+    <module resourceref="_kernel-boot-parameters-modify-temporary" renderas="section"/>
+    <!--task-->
+    <module resourceref="_kernel-boot-parameters-modify-permanent" renderas="section"/>
+    <!--task-->
+    <module resourceref="_kernel-boot-parameters-modify-troubleshoot" renderas="section">
+      <merge>
+        <title>Troubleshooting and FAQs</title>
+      </merge>
+    </module>
+    <!--glue-more-info-->
+    <module resourceref="_kernel-boot-parameters-modify-more-info" renderas="section">
+      <merge>
+        <title>For more information</title>
+      </merge>
+    </module>
+    <!--common-->
+    <module resourceref="_legal"/>
+    <!--common-->
+    <module resourceref="_gfdl">
+      <output renderas="appendix"/>
+    </module>
+  </structure>
+</assembly>
diff --git a/concepts/kernel-boot-parameters-modify-difference-linuxrc-parameters.xml b/concepts/kernel-boot-parameters-modify-difference-linuxrc-parameters.xml
@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- This file originates from the project https://github.com/openSUSE/doc-kit -->
+<!-- This file can be edited downstream. -->
+<!DOCTYPE topic
+[
+  <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
+<!-- point back to this document with a similar comment added to your legacy doc piece -->
+<!-- refer to README.md for file and id naming conventions -->
+<!-- metadata is dealt with on the assembly level -->
+<topic xml:id="kernel-boot-parameters-modify-difference-linuxrc-parameters"
+ role="concept" xml:lang="en"
+ xmlns="http://docbook.org/ns/docbook" version="5.2"
+ xmlns:its="http://www.w3.org/2005/11/its"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:trans="http://docbook.org/ns/transclusion">
+  <info>
+    <title>Difference between kernel boot parameters and linuxrc parameters</title>
+    <!-- can be changed via merge in the assembly -->
+    <!--add author's email address-->
+    <meta name="maintainer" content="[email protected]" its:translate="no"/>
+    <abstract>
+      <!-- can be changed via merge in the assembly -->
+      <para>
+        Kernel boot parameters and linuxrc parameters are often similar in
+        appearance, but conceptually they are entirely different. It is
+        important that you do not confuse them and understand their basic
+        difference.
+      </para>
+    </abstract>
+  </info>
+  <section xml:id="kernel-boot-parameters-modify-linuxrc-parameter-introduction">
+    <title>What are linuxrc parameters?</title>
+    <para>
+      In &productname;, the <literal>linuxrc</literal> is a script that runs
+      during the boot process before the systems's root file system is mounted,
+      and serves as the initial RAM disk (initrd) entry point. The
+      <literal>linuxrc</literal> parameters are used within this script to
+      configure the system further before transitioning to the actual root file
+      system.
+    </para>
+    <para>
+      Similar to kernel boot parameters, you can pass linuxrc parameters either
+      using the command line, or using configuration files. The entries for
+      linuxrc parameters are similar in appearance to that of the kernel boot
+      parameters.
+    </para>
+    <para>
+      However, the kernel boot parameters and the linuxrc parameters are
+      different concepts. To learn more about the linuxrc parameters, refer to
+      <link xlink:href="https://documentation.suse.com/sles/html/SLES-all/appendix-linuxrc.html" os="sles"></link><link
+        xlink:href="https://en.opensuse.org/SDB:Linuxrc" os="non-sles"></link>.
+    </para>
+  </section>
+  <section xml:id="kernel-boot-parameters-modify-linuxrc-parameter-examples">
+    <title>Examples of linuxrc parameters</title>
+    <para>
+      To highlight the similarity in appearance, observe the following
+      examples:
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          <literal>rd.driver.blacklist=</literal>: Specifies drivers to be
+          blacklisted in the initrd. For example,
+          <literal>rd.driver.blacklist=nouveau</literal> prevents the
+          <literal>nouveau</literal> graphics driver from loading.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>rd.break</literal>: Interrupts the boot process and drops
+          the system to a shell for debugging purposes within the initrd.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>rd.retry=</literal>: Specifies the number of retries for
+          device scanning in the initrd. For example,
+          <literal>rd.retry=3</literal>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>rd.luks=1</literal>: Activates support for encrypted devices
+          in the initrd.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </section>
+</topic>