docs: sysctl: convert to ReST

Rename the /proc/sys/ documentation files to ReST, using the
README file as a template for an index.rst, adding the other
files there via TOC markup.

Despite being written on different times with different
styles, try to make them somewhat coherent with a similar
look and feel, ensuring that they'll look nice as both
raw text file and as via the html output produced by the
Sphinx build system.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

Documentation/admin-guide/kernel-parameters.txt

@@ -3144,7 +3144,7 @@
 	numa_zonelist_order= [KNL, BOOT] Select zonelist order for NUMA.
 			'node', 'default' can be specified
 			This can be set from sysctl after boot.
-			See Documentation/sysctl/vm.txt for details.
+			See Documentation/sysctl/vm.rst for details.
 
 	ohci1394_dma=early	[HW] enable debugging via the ohci1394 driver.
 			See Documentation/debugging-via-ohci1394.txt for more

Documentation/admin-guide/mm/index.rst

@@ -11,7 +11,7 @@ processes address space and many other cool things.
 Linux memory management is a complex system with many configurable
 settings. Most of these settings are available via ``/proc``
 filesystem and can be quired and adjusted using ``sysctl``. These APIs
-are described in Documentation/sysctl/vm.txt and in `man 5 proc`_.
+are described in Documentation/sysctl/vm.rst and in `man 5 proc`_.
 
 .. _man 5 proc: http://man7.org/linux/man-pages/man5/proc.5.html
 

Documentation/admin-guide/mm/ksm.rst

@@ -59,7 +59,7 @@ MADV_UNMERGEABLE is applied to a range which was never MADV_MERGEABLE.
 
 If a region of memory must be split into at least one new MADV_MERGEABLE
 or MADV_UNMERGEABLE region, the madvise may return ENOMEM if the process
-will exceed ``vm.max_map_count`` (see Documentation/sysctl/vm.txt).
+will exceed ``vm.max_map_count`` (see Documentation/sysctl/vm.rst).
 
 Like other madvise calls, they are intended for use on mapped areas of
 the user address space: they will report ENOMEM if the specified range

Documentation/core-api/printk-formats.rst

@@ -119,7 +119,7 @@ Kernel Pointers
 
 For printing kernel pointers which should be hidden from unprivileged
 users. The behaviour of %pK depends on the kptr_restrict sysctl - see
-Documentation/sysctl/kernel.txt for more details.
+Documentation/sysctl/kernel.rst for more details.
 
 Unmodified Addresses
 --------------------

Documentation/networking/ip-sysctl.txt

@@ -2287,7 +2287,7 @@ addr_scope_policy - INTEGER
 
 
 /proc/sys/net/core/*
-	Please see: Documentation/sysctl/net.txt for descriptions of these entries.
+	Please see: Documentation/sysctl/net.rst for descriptions of these entries.
 
 
 /proc/sys/net/unix/*

Documentation/sysctl/abi.txt → Documentation/sysctl/abi.rst

-Documentation for /proc/sys/abi/* kernel version 2.6.0.test2
-	(c) 2003,  Fabian Frederick <ffrederick@users.sourceforge.net>
+================================
+Documentation for /proc/sys/abi/
+================================
 
-For general info : README.
+kernel version 2.6.0.test2
 
-==============================================================
+Copyright (c) 2003,  Fabian Frederick <ffrederick@users.sourceforge.net>
+
+For general info: index.rst.
+
+------------------------------------------------------------------------------
 
 This path is binary emulation relevant aka personality types aka abi.
 When a process is executed, it's linked to an exec_domain whose
 personality is defined using values available from /proc/sys/abi.
 You can find further details about abi in include/linux/personality.h.
 
-Here are the files featuring in 2.6 kernel :
+Here are the files featuring in 2.6 kernel:
 
 - defhandler_coff
 - defhandler_elf
@@ -19,36 +24,44 @@ Here are the files featuring in 2.6 kernel :
 - fake_utsname
 - trace
 
-===========================================================
-defhandler_coff:
-defined value :
-PER_SCOSVR3
-0x0003 | STICKY_TIMEOUTS | WHOLE_SECONDS | SHORT_INODE
+defhandler_coff
+---------------
 
-===========================================================
-defhandler_elf:
-defined value :
-PER_LINUX
-0
+defined value:
+	PER_SCOSVR3::
+
+		0x0003 | STICKY_TIMEOUTS | WHOLE_SECONDS | SHORT_INODE
+
+defhandler_elf
+--------------
+
+defined value:
+	PER_LINUX::
+
+		0
+
+defhandler_lcall7
+-----------------
 
-===========================================================
-defhandler_lcall7:
 defined value :
-PER_SVR4
-0x0001 | STICKY_TIMEOUTS | MMAP_PAGE_ZERO,
+	PER_SVR4::
+
+		0x0001 | STICKY_TIMEOUTS | MMAP_PAGE_ZERO,
+
+defhandler_libsco
+-----------------
 
-===========================================================
-defhandler_libsco:
 defined value:
-PER_SVR4
-0x0001 | STICKY_TIMEOUTS | MMAP_PAGE_ZERO,
+	PER_SVR4::
 
-===========================================================
-fake_utsname:
-Unused
+		0x0001 | STICKY_TIMEOUTS | MMAP_PAGE_ZERO,
+
+fake_utsname
+------------
 
-===========================================================
-trace:
 Unused
 
-===========================================================
+trace
+-----
+
+Unused

Documentation/sysctl/README → Documentation/sysctl/index.rst

-Documentation for /proc/sys/		kernel version 2.2.10
-	(c) 1998, 1999,  Rik van Riel <riel@nl.linux.org>
+:orphan:
+
+===========================
+Documentation for /proc/sys
+===========================
+
+Copyright (c) 1998, 1999,  Rik van Riel <riel@nl.linux.org>
+
+------------------------------------------------------------------------------
 
 'Why', I hear you ask, 'would anyone even _want_ documentation
 for them sysctl files? If anybody really needs it, it's all in
@@ -12,11 +19,12 @@ have the time or knowledge to read the source code.
 Furthermore, the programmers who built sysctl have built it to
 be actually used, not just for the fun of programming it :-)
 
-==============================================================
+------------------------------------------------------------------------------
 
 Legal blurb:
 
 As usual, there are two main things to consider:
+
 1. you get what you pay for
 2. it's free
 
@@ -35,15 +43,17 @@ stories to: <riel@nl.linux.org>
 
 Rik van Riel.
 
-==============================================================
+--------------------------------------------------------------
 
-Introduction:
+Introduction
+============
 
 Sysctl is a means of configuring certain aspects of the kernel
 at run-time, and the /proc/sys/ directory is there so that you
 don't even need special tools to do it!
 In fact, there are only four things needed to use these config
 facilities:
+
 - a running Linux system
 - root access
 - common sense (this is especially hard to come by these days)
@@ -54,7 +64,9 @@ several (arch-dependent?) subdirs. Each subdir is mainly about
 one part of the kernel, so you can do configuration on a piece
 by piece basis, or just some 'thematic frobbing'.
 
-The subdirs are about:
+This documentation is about:
+
+=============== ===============================================================
 abi/		execution domains & personalities
 debug/		<empty>
 dev/		device specific information (eg dev/cdrom/info)
@@ -70,7 +82,19 @@ sunrpc/		SUN Remote Procedure Call (NFS)
 vm/		memory management tuning
 		buffer and cache management
 user/		Per user per user namespace limits
+=============== ===============================================================
 
 These are the subdirs I have on my system. There might be more
 or other subdirs in another setup. If you see another dir, I'd
 really like to hear about it :-)
+
+.. toctree::
+   :maxdepth: 1
+
+   abi
+   fs
+   kernel
+   net
+   sunrpc
+   user
+   vm

Documentation/sysctl/sunrpc.txt → Documentation/sysctl/sunrpc.rst

-Documentation for /proc/sys/sunrpc/*	kernel version 2.2.10
-	(c) 1998, 1999,  Rik van Riel <riel@nl.linux.org>
+===================================
+Documentation for /proc/sys/sunrpc/
+===================================
 
-For general info and legal blurb, please look in README.
+kernel version 2.2.10
 
-==============================================================
+Copyright (c) 1998, 1999,  Rik van Riel <riel@nl.linux.org>
+
+For general info and legal blurb, please look in index.rst.
+
+------------------------------------------------------------------------------
 
 This file contains the documentation for the sysctl files in
 /proc/sys/sunrpc and is valid for Linux kernel version 2.2.

Documentation/sysctl/user.txt → Documentation/sysctl/user.rst

-Documentation for /proc/sys/user/*	kernel version 4.9.0
-	(c) 2016		Eric Biederman <ebiederm@xmission.com>
+=================================
+Documentation for /proc/sys/user/
+=================================
 
-==============================================================
+kernel version 4.9.0
+
+Copyright (c) 2016		Eric Biederman <ebiederm@xmission.com>
+
+------------------------------------------------------------------------------
 
 This file contains the documentation for the sysctl files in
 /proc/sys/user.
@@ -30,37 +35,44 @@ user namespace does not allow a user to escape their current limits.
 
 Currently, these files are in /proc/sys/user:
 
-- max_cgroup_namespaces
+max_cgroup_namespaces
+=====================
 
   The maximum number of cgroup namespaces that any user in the current
   user namespace may create.
 
-- max_ipc_namespaces
+max_ipc_namespaces
+==================
 
   The maximum number of ipc namespaces that any user in the current
   user namespace may create.
 
-- max_mnt_namespaces
+max_mnt_namespaces
+==================
 
   The maximum number of mount namespaces that any user in the current
   user namespace may create.
 
-- max_net_namespaces
+max_net_namespaces
+==================
 
   The maximum number of network namespaces that any user in the
   current user namespace may create.
 
-- max_pid_namespaces
+max_pid_namespaces
+==================
 
   The maximum number of pid namespaces that any user in the current
   user namespace may create.
 
-- max_user_namespaces
+max_user_namespaces
+===================
 
   The maximum number of user namespaces that any user in the current
   user namespace may create.
 
-- max_uts_namespaces
+max_uts_namespaces
+==================
 
   The maximum number of user namespaces that any user in the current
   user namespace may create.

Documentation/vm/unevictable-lru.rst

@@ -439,7 +439,7 @@ Compacting MLOCKED Pages
 
 The unevictable LRU can be scanned for compactable regions and the default
 behavior is to do so.  /proc/sys/vm/compact_unevictable_allowed controls
-this behavior (see Documentation/sysctl/vm.txt).  Once scanning of the
+this behavior (see Documentation/sysctl/vm.rst).  Once scanning of the
 unevictable LRU is enabled, the work of compaction is mostly handled by
 the page migration code and the same work flow as described in MIGRATING
 MLOCKED PAGES will apply.

kernel/panic.c

@@ -372,7 +372,7 @@ const struct taint_flag taint_flags[TAINT_FLAGS_COUNT] = {
 /**
  * print_tainted - return a string to represent the kernel taint state.
  *
- * For individual taint flag meanings, see Documentation/sysctl/kernel.txt
+ * For individual taint flag meanings, see Documentation/sysctl/kernel.rst
  *
  * The string is overwritten by the next call to print_tainted(),
  * but is always NULL terminated.

mm/swap.c

@@ -8,7 +8,7 @@
 /*
  * This file contains the default values for the operation of the
  * Linux VM subsystem. Fine-tuning documentation can be found in
- * Documentation/sysctl/vm.txt.
+ * Documentation/sysctl/vm.rst.
  * Started 18.12.91
  * Swap aging added 23.2.95, Stephen Tweedie.
  * Buffermem limits added 12.3.98, Rik van Riel.