Skip to contentSkip to conversation

docs: admin-guide: Sort the "unordered guides" to avoid merge conflicts

RFC PATCH In review Jonathan Neuschäfer 3 participants 6 messages Oct 12, 2019 – Oct 15, 2019

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

RFC PATCH 1/4 docs: admin-guide: Sort the "unordered guides" to avoid merge conflicts

Since the "unordered guides" linked in admin-guide/index.rst are not supposed to be in any particular order, let's sort them alphabetically to avoid the risk of merge conflicts by spreading newly added lines more evenly.

---

Upon a second look, I noticed that the list wasn't completely unordered:
binfmt-misc is grouped with java and mono, the filesystems are grouped together.

For the filesystems, I think they should be moved to the filesystems/ directory, and the binfmt documents could perhaps be explicitly grouped too. But perhaps the loss of this grouping-by-position is reason enough to drop this patch for now.

---
 Documentation/admin-guide/index.rst | 64 ++++++++++++++---------------
 1 file changed, 32 insertions(+), 32 deletions(-)
Documentation/admin-guide/index.rst +32 -32
index 34cc20ee7f3a..545ea26364b7 100644
@@ -57,60 +57,60 @@ configure specific aspects of kernel behavior to your liking.
 .. toctree::
    :maxdepth: 1
 
-   initrd
-   cgroup-v2
-   cgroup-v1/index
-   serial-console
-   braille-console
-   parport
-   md
-   module-signing
-   rapidio
-   sysrq
-   unicode
-   vga-softcursor
-   binfmt-misc
-   mono
-   java
-   ras
-   bcache
-   blockdev/index
-   ext4
-   binderfs
-   cifs/index
-   xfs
-   jfs
-   ufs
-   pm/index
-   thunderbolt
-   LSM/index
-   mm/index
-   namespaces/index
-   perf-security
    acpi/index
    aoe/index
+   auxdisplay/index
+   bcache
+   binderfs
+   binfmt-misc
+   blockdev/index
+   braille-console
    btmrvl
+   cgroup-v1/index
+   cgroup-v2
+   cifs/index
    clearing-warn-once
    cpu-load
    cputopology
    device-mapper/index
    efi-stub
+   ext4
    gpio/index
    highuid
    hw_random
+   initrd
    iostats
+   java
+   jfs
    kernel-per-CPU-kthreads
    laptops/index
-   auxdisplay/index
    lcd-panel-cgram
    ldm
    lockup-watchdogs
+   LSM/index
+   md
+   mm/index
+   module-signing
+   mono
+   namespaces/index
    numastat
+   parport
+   perf-security
+   pm/index
    pnp
+   rapidio
+   ras
    rtc
+   serial-console
    svga
-   wimax/index
+   sysrq
+   thunderbolt
+   ufs
+   unicode
+   vga-softcursor
    video-output
+   wimax/index
+   xfs
 
 .. only::  subproject and html
 

--
2.20.1

#1 lore raw

PATCH 2/4 docs: admin-guide: Move Dell RBU document from driver-api

This document describes how an admin can use the dell_rbu driver, rather than any in-kernel API details.

---
 Documentation/{driver-api => admin-guide}/dell_rbu.rst | 0
 Documentation/admin-guide/index.rst                    | 1 +
 Documentation/driver-api/index.rst                     | 1 -
 drivers/platform/x86/Kconfig                           | 2 +-
 drivers/platform/x86/dell_rbu.c                        | 2 +-
 5 files changed, 3 insertions(+), 3 deletions(-)
 rename Documentation/{driver-api => admin-guide}/dell_rbu.rst (100%)
Documentation/admin-guide/dell_rbu.rst renamed from Documentation/driver-api/dell_rbu.rst +0 -0
similarity index 100%
rename from Documentation/driver-api/dell_rbu.rst
rename to Documentation/admin-guide/dell_rbu.rst
Documentation/admin-guide/index.rst +1 -0
index 545ea26364b7..4405b7485312 100644
@@ -72,6 +72,7 @@ configure specific aspects of kernel behavior to your liking.
    clearing-warn-once
    cpu-load
    cputopology
+   dell_rbu
    device-mapper/index
    efi-stub
    ext4
Documentation/driver-api/index.rst +0 -1
index 2b3b6949381e..6a3ac50f51f0 100644
@@ -72,7 +72,6 @@ available subsections can be seen below.
    connector
    console
    dcdbas
-   dell_rbu
    edid
    eisa
    ipmb
drivers/platform/x86/Kconfig +1 -1
index ae21d08c65e8..a890f47fbeec 100644
@@ -259,7 +259,7 @@ config DELL_RBU
 	 DELL system. Note you need a Dell OpenManage or Dell Update package (DUP)
 	 supporting application to communicate with the BIOS regarding the new
 	 image for the image update to take effect.
-	 See <file:Documentation/driver-api/dell_rbu.rst> for more details on the driver.
+	 See <file:Documentation/admin-guide/dell_rbu.rst> for more details on the driver.
 
 
 config FUJITSU_LAPTOP
drivers/platform/x86/dell_rbu.c +1 -1
index 3691391fea6b..7d5453326b43 100644
@@ -24,7 +24,7 @@
  * on every time the packet data is written. This driver requires an
  * application to break the BIOS image in to fixed sized packet chunks.
  *
- * See Documentation/driver-api/dell_rbu.rst for more info.
+ * See Documentation/admin-guide/dell_rbu.rst for more info.
  */
 #include <linux/init.h>
 #include <linux/module.h>

--
2.20.1

Acked-by on v1 2/4
#2 lore raw

Re: [PATCH 2/4] docs: admin-guide: Move Dell RBU document from driver-api

Quoted 3 lines · Jonathan Neuschäfer

This document describes how an admin can use the dell_rbu driver, rather than any in-kernel API details.

Quoted 67 lines
---
 Documentation/{driver-api => admin-guide}/dell_rbu.rst | 0
 Documentation/admin-guide/index.rst                    | 1 +
 Documentation/driver-api/index.rst                     | 1 -
 drivers/platform/x86/Kconfig                           | 2 +-
 drivers/platform/x86/dell_rbu.c                        | 2 +-
 5 files changed, 3 insertions(+), 3 deletions(-)
 rename Documentation/{driver-api => admin-guide}/dell_rbu.rst (100%)
Documentation/admin-guide/dell_rbu.rst renamed from Documentation/driver-api/dell_rbu.rst +0 -0
similarity index 100%
rename from Documentation/driver-api/dell_rbu.rst
rename to Documentation/admin-guide/dell_rbu.rst
Documentation/admin-guide/index.rst +1 -0
index 545ea26364b7..4405b7485312 100644
@@ -72,6 +72,7 @@ configure specific aspects of kernel behavior to your liking.
    clearing-warn-once
    cpu-load
    cputopology
+   dell_rbu
    device-mapper/index
    efi-stub
    ext4
Documentation/driver-api/index.rst +0 -1
index 2b3b6949381e..6a3ac50f51f0 100644
@@ -72,7 +72,6 @@ available subsections can be seen below.
    connector
    console
    dcdbas
-   dell_rbu
    edid
    eisa
    ipmb
drivers/platform/x86/Kconfig +1 -1
index ae21d08c65e8..a890f47fbeec 100644
@@ -259,7 +259,7 @@ config DELL_RBU
         DELL system. Note you need a Dell OpenManage or Dell Update package (DUP)
         supporting application to communicate with the BIOS regarding the new
         image for the image update to take effect.
-        See <file:Documentation/driver-api/dell_rbu.rst> for more details on the driver.
+        See <file:Documentation/admin-guide/dell_rbu.rst> for more details on the driver.
 
 
 config FUJITSU_LAPTOP
drivers/platform/x86/dell_rbu.c +1 -2
index 3691391fea6b..7d5453326b43 100644
@@ -24,7 +24,7 @@
  * on every time the packet data is written. This driver requires an
  * application to break the BIOS image in to fixed sized packet chunks.
  *
- * See Documentation/driver-api/dell_rbu.rst for more info.
+ * See Documentation/admin-guide/dell_rbu.rst for more info.
  */
 #include <linux/init.h>
 #include <linux/module.h>
--

2.20.1

Signature · 2 lines
With Best Regards,
Andy Shevchenko
#3 lore raw

PATCH 3/4 docs: admin-guide: dell_rbu: Rework the title

In reply to Jonathan Neuschäfer

- Mention the driver name, which is also used in sysfs (dell_rbu)
- Rewrite the title to be more concise

---
 Documentation/admin-guide/dell_rbu.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/admin-guide/dell_rbu.rst +3 -3
index 5d1ce7bcd04d..10830db9e616 100644
@@ -1,6 +1,6 @@
-=============================================================
-Usage of the new open sourced rbu (Remote BIOS Update) driver
-=============================================================
+=========================================
+Dell Remote BIOS Update driver (dell_rbu)
+=========================================
 
 Purpose
 =======
Signature · 1 line
2.20.1
#4 lore raw

PATCH 4/4 docs: admin-guide: dell_rbu: Improve formatting and spelling

In reply to Jonathan Neuschäfer

This improves readability a bit.

---
 Documentation/admin-guide/dell_rbu.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/admin-guide/dell_rbu.rst +4 -4
index 10830db9e616..8d70e1fc9f9d 100644
@@ -5,7 +5,7 @@ Dell Remote BIOS Update driver (dell_rbu)
 Purpose
 =======
 
-Document demonstrating the use of the Dell Remote BIOS Update driver.
+Document demonstrating the use of the Dell Remote BIOS Update driver
 for updating BIOS images on Dell servers and desktops.
 
 Scope
@@ -37,7 +37,7 @@ maintains a link list of packets for reading them back.
 
 If the dell_rbu driver is unloaded all the allocated memory is freed.
 
-The rbu driver needs to have an application (as mentioned above)which will
+The rbu driver needs to have an application (as mentioned above) which will
 inform the BIOS to enable the update in the next system reboot.
 
 The user should not unload the rbu driver after downloading the BIOS image
@@ -71,7 +71,7 @@ be downloaded. It is done as below::
 	echo XXXX > /sys/devices/platform/dell_rbu/packet_size
 
 In the packet update mechanism, the user needs to create a new file having
-packets of data arranged back to back. It can be done as follows
+packets of data arranged back to back. It can be done as follows:
 The user creates packets header, gets the chunk of the BIOS image and
 places it next to the packetheader; now, the packetheader + BIOS image chunk
 added together should match the specified packet_size. This makes one
@@ -114,7 +114,7 @@ The entries can be recreated by doing the following::
 
 	echo init > /sys/devices/platform/dell_rbu/image_type
 
-.. note:: echoing init in image_type does not change it original value.
+.. note:: echoing init in image_type does not change its original value.
 
 Also the driver provides /sys/devices/platform/dell_rbu/data readonly file to
 read back the image downloaded.

--
2.20.1

maintainer
#5 lore raw
In reply to Jonathan Neuschäfer
Quoted 6 lines · On Sat, 12 Oct 2019 19:11:09 +0200 Jonathan Neuschäfer <[email protected]>…

Since the "unordered guides" linked in admin-guide/index.rst are not supposed to be in any particular order, let's sort them alphabetically to avoid the risk of merge conflicts by spreading newly added lines more evenly.

I've applied this as being better than nothing, but I would *really* be pleased if somebody could spend some time imposing a more interesting order on those unordered guides. Making readers pick through a long list of random documents isn't all that friendly.

(The rest of the set is applied as well).

Thanks,

jon