[PATCH 0/5] Update Documentation/00-INDEX

[PATCH 0/5] Update Documentation/00-INDEX

[Mauro Carvalho Chehab]

Keeping a manually filled index over time is not perfect, as people often
forget to keep the index file updated.

As Brian noticed, the recent conversion to ReST caused some new
issues. It turns, however, that the problem with this file predates the
ReST conversion, as several entries were missing, including really old
ones like PCI/ and isa.txt.

Well, after converting everything to ReST file, the 00-INDEX one will
become obsoleted by index.rst, but, as there are still a lot stuff
to do, it will take some time.

So, in order to check it, I wrote a small script that compares the files
and directories at Documentation/ with the ones at 00-INDEX.

Then, I synchronized the entries, making the script happy.

We might think on integrating the script with checkpatch.pl, but, as
we should get rid of 00-INDEX, it probably not worth the efforts.

Mauro Carvalho Chehab (5):
  scripts: add a script to check if Documentation/00-INDEX is sane
  docs: 00-INDEX: consolidate process/ and admin-guide/ description
  docs: 00-INDEX: add missing entries for documentation files/dirs
  docs: 00-INDEX: remove non-existing entries
  docs: 00-INDEX: document directories/files with no docs

 Documentation/00-INDEX   | 196 ++++++++++++++++++++---------------------------
 scripts/check_00index.sh |  66 ++++++++++++++++
 2 files changed, 149 insertions(+), 113 deletions(-)
 create mode 100755 scripts/check_00index.sh

-- 
2.9.3

[PATCH 1/5] scripts: add a script to check if Documentation/00-INDEX is sane

[Mauro Carvalho Chehab]

It is easy to forget adding/removing entries at the
Documentation/00-INDEX file. In a matter of fact, even before
ReST conversion, people use to forget adding things here, as
there are lots of missing stuff out there.

Now that we're doing a hard work converting entries to ReST,
and while this hole file is not outdated, it is good to have
some tool that would help to verify that this file is kept
updated.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 scripts/check_00index.sh | 66 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100755 scripts/check_00index.sh

diff --git a/scripts/check_00index.sh b/scripts/check_00index.sh
new file mode 100755
index 000000000000..6ac9527aeddb
--- /dev/null
+++ b/scripts/check_00index.sh
@@ -0,0 +1,66 @@
+#!/bin/bash
+
+cd Documentation/
+
+# Check entries that should be removed
+
+obsolete=""
+for i in $(tail -n +12 00-INDEX |grep -E '^[a-zA-Z0-9]+'); do
+	if [ ! -e $i ]; then
+		obsolete="$obsolete $i"
+	fi
+done
+
+# Check directory entries that should be added
+search=""
+dir=""
+for i in $(find . -maxdepth 1 -type d); do
+	if [ "$i" != "." ]; then
+		new=$(echo $i|perl -ne 's,./(.*),$1/,; print $_')
+		search="$search $new"
+	fi
+done
+
+for i in $search; do
+	if [ "$(grep -P "^$i" 00-INDEX)" == "" ]; then
+		dir="$dir $i"
+	fi
+done
+
+# Check file entries that should be added
+search=""
+file=""
+for i in $(find . -maxdepth 1 -type f); do
+	if [ "$i" != "./.gitignore" ]; then
+		new=$(echo $i|perl -ne 's,./(.*),$1,; print $_')
+		search="$search $new"
+	fi
+done
+
+for i in $search; do
+	if [ "$(grep -P "^$i\$" 00-INDEX)" == "" ]; then
+		file="$file $i"
+	fi
+done
+
+# Output its findings
+
+echo -e "Documentation/00-INDEX check results:\n"
+
+if [ "$obsolete" != "" ]; then
+	echo -e "- Should remove those entries:\n\t$obsolete\n"
+else
+	echo -e "- No obsolete entries\n"
+fi
+
+if [ "$dir" != "" ]; then
+	echo -e "- Should document those directories:\n\t$dir\n"
+else
+	echo -e "- No new directories to add\n"
+fi
+
+if [ "$file" != "" ]; then
+	echo -e "- Should document those files:\n\t$file"
+else
+	echo "- No new files to add"
+fi
-- 
2.9.3

[PATCH 2/5] docs: 00-INDEX: consolidate process/ and admin-guide/ description

[Mauro Carvalho Chehab]

Instead of having descriptions for individual files inside
the process/ and admin-guide/ documentation, consolidate them
into one entry per directory, just like other descriptions
inside 00-INDEX.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/00-INDEX | 61 ++++----------------------------------------------
 1 file changed, 4 insertions(+), 57 deletions(-)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index c08de5574d48..02583a1f409c 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -14,13 +14,6 @@ Following translations are available on the WWW:
 	- this file.
 ABI/
 	- info on kernel <-> userspace ABI and relative interface stability.
-
-admin-guide/bug-hunting.rst
-	- brute force method of doing binary search of patches to find bug.
-process/changes.rst
-	- list of changes that break older software packages.
-process/coding-style.rst
-	- how the maintainers expect the C code in the kernel to look.
 DMA-API.txt
 	- DMA API, pci_ API & extensions for non-consistent memory machines.
 DMA-API-HOWTO.txt
@@ -33,8 +26,6 @@ DocBook/
 	- directory with DocBook templates etc. for kernel documentation.
 EDID/
 	- directory with info on customizing EDID for broken gfx/displays.
-process/howto.rst
-	- the process and procedures of how to do Linux kernel development.
 IPMI.txt
 	- info on Linux Intelligent Platform Management Interface (IPMI) Driver.
 IRQ-affinity.txt
@@ -48,32 +39,22 @@ Intel-IOMMU.txt
 Makefile
 	- This file does nothing. Removing it breaks make htmldocs and
 	  make distclean.
-process/management-style.rst
-	- how to (attempt to) manage kernel hackers.
 RCU/
 	- directory with info on RCU (read-copy update).
 SAK.txt
 	- info on Secure Attention Keys.
 SM501.txt
 	- Silicon Motion SM501 multimedia companion chip
-admin-guide/security-bugs.rst
-	- procedure for reporting security bugs found in the kernel.
-process/submit-checklist.rst
-	- Linux kernel patch submission checklist.
-process/submitting-drivers.rst
-	- procedure to get a new driver source included into the kernel tree.
-process/submitting-patches.rst
-	- procedure to get a source patch included into the kernel tree.
 VGA-softcursor.txt
 	- how to change your VGA cursor from a blinking underscore.
 accounting/
 	- documentation on accounting and taskstats.
 acpi/
 	- info on ACPI-specific hooks in the kernel.
+admin-guide/
+	- info related to Linux users and system admins.
 aoe/
 	- description of AoE (ATA over Ethernet) along with config examples.
-process/applying-patches.rst
-	- description of various trees and how to apply their patches.
 arm/
 	- directory with info about Linux on the ARM architecture.
 arm64/
@@ -86,8 +67,6 @@ auxdisplay/
 	- misc. LCD driver documentation (cfag12864b, ks0108).
 backlight/
 	- directory with info on controlling backlights in flat panel displays
-admin-guide/bad-memory.rst
-	- how to use kernel parameters to exclude bad RAM regions.
 basic_profiling.txt
 	- basic instructions for those who wants to profile Linux kernel.
 bcache.txt
@@ -152,12 +131,8 @@ debugging-via-ohci1394.txt
 	- how to use firewire like a hardware debugger memory reader.
 dell_rbu.txt
 	- document demonstrating the use of the Dell Remote BIOS Update driver.
-process/
-	- how to work with the mainline kernel development process.
 device-mapper/
 	- directory with info on Device Mapper.
-admin-guide/devices.rst
-	- plain ASCII listing of all the nodes in /dev/ with major minor #'s.
 devicetree/
 	- directory with info on device tree files used by OF/PowerPC/ARM
 digsig.txt
@@ -178,8 +153,6 @@ efi-stub.txt
 	- How to use the EFI boot stub to bypass GRUB or elilo on EFI systems.
 eisa.txt
 	- info on EISA bus support.
-process/email-clients.rst
-	- info on how to use e-mail to send un-mangled (git) patches.
 extcon/
 	- directory with porting guide for Android kernel switch driver.
 fault-injection/
@@ -226,10 +199,6 @@ ia64/
 	- directory with info about Linux on Intel 64 bit architecture.
 infiniband/
 	- directory with documents concerning Linux InfiniBand support.
-admin-guide/init.rst
-	- what to do when the kernel can't find the 1st process to run.
-admin-guide/initrd.rst
-	- how to use the RAM disk as an initial/temporary root filesystem.
 input/
 	- info on Linux input device support.
 intel_txt.txt
@@ -248,20 +217,14 @@ isapnp.txt
 	- info on Linux ISA Plug & Play support.
 isdn/
 	- directory with info on the Linux ISDN support, and supported cards.
-admin-guide/java.rst
-	- info on the in-kernel binary support for Java(tm).
 ja_JP/
 	- directory with Japanese translations of various documents
 kbuild/
 	- directory with info about the kernel build process.
 kdump/
 	- directory with mini HowTo on getting the crash dump code to work.
-process/kernel-docs.rst
-	- listing of various WWW + books that document kernel internals.
 doc-guide/
 	- how to write and format reStructuredText kernel documentation
-admin-guide/kernel-parameters.rst
-	- summary listing of command line / boot prompt args for the kernel.
 kernel-per-CPU-kthreads.txt
 	- List of all per-CPU kthreads and how they introduce jitter.
 kmemcheck.txt
@@ -302,8 +265,6 @@ magic-number.txt
 	- list of magic numbers used to mark/protect kernel data structures.
 mailbox.txt
 	- How to write drivers for the common mailbox framework (IPC).
-admin-guide/md.rst
-	- info on boot arguments for the multiple devices driver.
 media-framework.txt
 	- info on media framework, its data structures, functions and usage.
 memory-barriers.txt
@@ -326,8 +287,6 @@ module-signing.txt
 	- Kernel module signing for increased security when loading modules.
 mtd/
 	- directory with info about memory technology devices (flash)
-admin-guide/mono.rst
-	- how to execute Mono-based .NET binaries with the help of BINFMT_MISC.
 namespaces/
 	- directory with various information about namespaces
 netlabel/
@@ -340,8 +299,6 @@ nommu-mmap.txt
 	- documentation about no-mmu memory mapping support.
 numastat.txt
 	- info on how to read Numa policy hit/miss statistics in sysfs.
-admin-guide/oops-tracing.rst
-	- how to decode those nasty internal kernel error dump messages.
 padata.txt
 	- An introduction to the "padata" parallel execution API
 parisc/
@@ -372,14 +329,14 @@ preempt-locking.txt
 	- info on locking under a preemptive kernel.
 printk-formats.txt
 	- how to get printk format specifiers right
+process/
+	- how to work with the mainline kernel development process.
 pps/
 	- directory with information on the pulse-per-second support
 ptp/
 	- directory with info on support for IEEE 1588 PTP clocks in Linux.
 pwm.txt
 	- info on the pulse width modulation driver subsystem
-admin-guide/ramoops.rst
-	- documentation of the ramoops oops/panic logging module.
 rapidio/
 	- directory with info on RapidIO packet-based fabric interconnect
 rbtree.txt
@@ -406,8 +363,6 @@ security/
 	- directory that contains security-related info
 serial/
 	- directory with info on the low level serial API.
-admin-guide/serial-console.rst
-	- how to set up Linux with a serial line console as the default.
 sgi-ioc4.txt
 	- description of the SGI IOC4 PCI (multi function) device.
 sh/
@@ -420,10 +375,6 @@ sparse.txt
 	- info on how to obtain and use the sparse tool for typechecking.
 spi/
 	- overview of Linux kernel Serial Peripheral Interface (SPI) support.
-process/stable-api-nonsense.rst
-	- info on why the kernel does not have a stable in-kernel api or abi.
-process/stable-kernel-rules.rst
-	- rules and procedures for the -stable kernel releases.
 static-keys.txt
 	- info on how static keys allow debug code in hotpaths via patching
 svga.txt
@@ -444,8 +395,6 @@ trace/
 	- directory with info on tracing technologies within linux
 unaligned-memory-access.txt
 	- info on how to avoid arch breaking unaligned memory access in code.
-admin-guide/unicode.rst
-	- info on the Unicode character/font mapping used in Linux.
 unshare.txt
 	- description of the Linux unshare system call.
 usb/
@@ -464,8 +413,6 @@ vm/
 	- directory with info on the Linux vm code.
 vme_api.txt
 	- file relating info on the VME bus API in linux
-process/volatile-considered-harmful.rst
-	- Why the "volatile" type class should not be used
 w1/
 	- directory with documents regarding the 1-wire (w1) subsystem.
 watchdog/
-- 
2.9.3

[PATCH 3/5] docs: 00-INDEX: add missing entries for documentation files/dirs

[Mauro Carvalho Chehab]

Several directories and individual files don't have entries at
00-INDEX. Add them, using, as reference, the initial text inside
the documentation file(s).

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/00-INDEX | 64 ++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 60 insertions(+), 4 deletions(-)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 02583a1f409c..bd532a7e03e6 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -39,6 +39,8 @@ Intel-IOMMU.txt
 Makefile
 	- This file does nothing. Removing it breaks make htmldocs and
 	  make distclean.
+PCI/
+	- info related to PCI drivers.
 RCU/
 	- directory with info on RCU (read-copy update).
 SAK.txt
@@ -93,12 +95,16 @@ cachetlb.txt
 	- describes the cache/TLB flushing interfaces Linux uses.
 cdrom/
 	- directory with information on the CD-ROM drivers that Linux has.
-cgroups/
-	- cgroups features, including cpusets and memory controller.
+cgroup-v1/
+	- cgroups v1 features, including cpusets and memory controller.
+cgroup-v2.txt
+	- cgroups v2 features, including cpusets and memory controller.
 circular-buffers.txt
 	- how to make use of the existing circular buffer infrastructure
 clk.txt
 	- info on the common clock framework
+cma/
+	- Continuous Memory Area (CMA) debugfs interface.
 coccinelle.txt
 	- info on how to get and use the Coccinelle code checking tool.
 connector/
@@ -131,8 +137,12 @@ debugging-via-ohci1394.txt
 	- how to use firewire like a hardware debugger memory reader.
 dell_rbu.txt
 	- document demonstrating the use of the Dell Remote BIOS Update driver.
+dev-tools/
+	- directory with info on development tools for the kernel.
 device-mapper/
 	- directory with info on Device Mapper.
+dmaengine/
+	- the DMA engine and controller API guides.
 devicetree/
 	- directory with info on device tree files used by OF/PowerPC/ARM
 digsig.txt
@@ -141,6 +151,8 @@ dma-buf-sharing.txt
 	- the DMA Buffer Sharing API Guide
 dontdiff
 	- file containing a list of files that should never be diff'ed.
+driver-api/
+	- the Linux driver implementer's API guide.
 driver-model/
 	- directory with info about Linux driver model.
 dynamic-debug-howto.txt
@@ -155,10 +167,14 @@ eisa.txt
 	- info on EISA bus support.
 extcon/
 	- directory with porting guide for Android kernel switch driver.
+isa.txt
+	- info on EISA bus support.
 fault-injection/
 	- dir with docs about the fault injection capabilities infrastructure.
 fb/
 	- directory with info on the frame buffer graphics abstraction layer.
+features/
+	- status of feature implementation on different architectures.
 filesystems/
 	- info on the vfs and the various filesystems that Linux supports.
 firmware_class/
@@ -167,14 +183,20 @@ flexible-arrays.txt
 	- how to make use of flexible sized arrays in linux
 fmc/
 	- information about the FMC bus abstraction
+fpga/
+	- FPGA Manager Core.
 frv/
 	- Fujitsu FR-V Linux documentation.
 futex-requeue-pi.txt
 	- info on requeueing of tasks from a non-PI futex to a PI futex
+gcc-plugins.txt
+	- GCC plugin infrastructure.
 gcov.txt
 	- use of GCC's coverage testing tool "gcov" with the Linux kernel
 gpio/
 	- gpio related documentation
+gpu/
+	- directory with information on GPU driver developer's guide.
 hid/
 	- directory with information on human interface devices
 highuid.txt
@@ -197,6 +219,10 @@ x86/i386/
 	- directory with info about Linux on Intel 32 bit architecture.
 ia64/
 	- directory with info about Linux on Intel 64 bit architecture.
+ide/
+	- Information regarding the Enhanced IDE drive.
+iio/
+	- info on industrial IIO configfs support.
 infiniband/
 	- directory with documents concerning Linux InfiniBand support.
 input/
@@ -221,6 +247,8 @@ ja_JP/
 	- directory with Japanese translations of various documents
 kbuild/
 	- directory with info about the kernel build process.
+kernel-doc-nano-HOWTO.txt
+	- outdated info about kernel-doc documentation.
 kdump/
 	- directory with mini HowTo on getting the crash dump code to work.
 doc-guide/
@@ -247,6 +275,8 @@ ldm.txt
 	- a brief description of LDM (Windows Dynamic Disks).
 leds/
 	- directory with info about LED handling under Linux.
+livepatch/
+	- info on kernel live patching.
 local_ops.txt
 	- semantics and behavior of local atomic operations.
 locking/
@@ -265,16 +295,22 @@ magic-number.txt
 	- list of magic numbers used to mark/protect kernel data structures.
 mailbox.txt
 	- How to write drivers for the common mailbox framework (IPC).
-media-framework.txt
-	- info on media framework, its data structures, functions and usage.
+md-cluster.txt
+	- info on shared-device RAID MD cluster.
+media/
+	- info on media drivers: uAPI, kAPI and driver documentation.
 memory-barriers.txt
 	- info on Linux kernel memory barriers.
 memory-devices/
 	- directory with info on parts like the Texas Instruments EMIF driver
 memory-hotplug.txt
 	- Hotpluggable memory support, how to use and current status.
+men-chameleon-bus.txt
+	- info on MEN chameleon bus.
 metag/
 	- directory with info about Linux on Meta architecture.
+mic/
+	- Intel Many Integrated Core (MIC) architecture device driver.
 mips/
 	- directory with info about Linux on MIPS architecture.
 misc-devices/
@@ -295,10 +331,18 @@ networking/
 	- directory with info on various aspects of networking with Linux.
 nfc/
 	- directory relating info about Near Field Communications support.
+nios2/
+	- Linux on the Nios II architecture.
 nommu-mmap.txt
 	- documentation about no-mmu memory mapping support.
 numastat.txt
 	- info on how to read Numa policy hit/miss statistics in sysfs.
+ntb.txt
+	- info on Non-Transparent Bridge (NTB) drivers.
+nvdimm/
+	- info on non-volatile devices.
+nvmem/
+	- info on non volatile memory framework.
 padata.txt
 	- An introduction to the "padata" parallel execution API
 parisc/
@@ -311,12 +355,18 @@ pcmcia/
 	- info on the Linux PCMCIA driver.
 percpu-rw-semaphore.txt
 	- RCU based read-write semaphore optimized for locking for reading
+perf/
+	- info about the APM X-Gene SoC Performance Monitoring Unit (PMU).
+phy/
+	- ino on Samsung USB 2.0 PHY adaptation layer.
 phy.txt
 	- Description of the generic PHY framework.
 pi-futex.txt
 	- documentation on lightweight priority inheritance futexes.
 pinctrl.txt
 	- info on pinctrl subsystem and the PINMUX/PINCONF and drivers
+platform/
+	- List of supported hardware by compal and Dell laptop.
 pnp.txt
 	- Linux Plug and Play documentation.
 power/
@@ -333,6 +383,8 @@ process/
 	- how to work with the mainline kernel development process.
 pps/
 	- directory with information on the pulse-per-second support
+pti/
+	- directory with info on Intel MID PTI.
 ptp/
 	- directory with info on support for IEEE 1588 PTP clocks in Linux.
 pwm.txt
@@ -379,6 +431,8 @@ static-keys.txt
 	- info on how static keys allow debug code in hotpaths via patching
 svga.txt
 	- short guide on selecting video modes at boot via VGA BIOS.
+sync_file.txt
+	- Sync file API guide.
 sysfs-rules.txt
 	- How not to use sysfs.
 sysctl/
@@ -393,6 +447,8 @@ thermal/
 	- directory with information on managing thermal issues (CPU/temp)
 trace/
 	- directory with info on tracing technologies within linux
+translations/
+	- translations of this document from English to another language
 unaligned-memory-access.txt
 	- info on how to avoid arch breaking unaligned memory access in code.
 unshare.txt
-- 
2.9.3

[PATCH 4/5] docs: 00-INDEX: remove non-existing entries

[Mauro Carvalho Chehab]

Several entries were moved to a directory; others got simply
removed. Get rid of those entries.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/00-INDEX | 52 --------------------------------------------------
 1 file changed, 52 deletions(-)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index bd532a7e03e6..272f5c4481f1 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -47,8 +47,6 @@ SAK.txt
 	- info on Secure Attention Keys.
 SM501.txt
 	- Silicon Motion SM501 multimedia companion chip
-VGA-softcursor.txt
-	- how to change your VGA cursor from a blinking underscore.
 accounting/
 	- documentation on accounting and taskstats.
 acpi/
@@ -61,28 +59,18 @@ arm/
 	- directory with info about Linux on the ARM architecture.
 arm64/
 	- directory with info about Linux on the 64 bit ARM architecture.
-assoc_array.txt
-	- generic associative array intro.
-atomic_ops.txt
-	- semantics and behavior of atomic and bitmask operations.
 auxdisplay/
 	- misc. LCD driver documentation (cfag12864b, ks0108).
 backlight/
 	- directory with info on controlling backlights in flat panel displays
-basic_profiling.txt
-	- basic instructions for those who wants to profile Linux kernel.
 bcache.txt
 	- Block-layer cache on fast SSDs to improve slow (raid) I/O performance.
-binfmt_misc.txt
-	- info on the kernel support for extra binary formats.
 blackfin/
 	- directory with documentation for the Blackfin arch.
 block/
 	- info on the Block I/O (BIO) layer.
 blockdev/
 	- info on block devices & drivers
-braille-console.txt
-	- info on how to use serial devices for Braille support.
 bt8xxgpio.txt
 	- info on how to modify a bt8xx video card for GPIO usage.
 btmrvl.txt
@@ -105,8 +93,6 @@ clk.txt
 	- info on the common clock framework
 cma/
 	- Continuous Memory Area (CMA) debugfs interface.
-coccinelle.txt
-	- info on how to get and use the Coccinelle code checking tool.
 connector/
 	- docs on the netlink based userspace<->kernel space communication mod.
 console/
@@ -155,8 +141,6 @@ driver-api/
 	- the Linux driver implementer's API guide.
 driver-model/
 	- directory with info about Linux driver model.
-dynamic-debug-howto.txt
-	- how to use the dynamic debug (dyndbg) feature.
 early-userspace/
 	- info about initramfs, klibc, and userspace early during boot.
 edac.txt
@@ -191,8 +175,6 @@ futex-requeue-pi.txt
 	- info on requeueing of tasks from a non-PI futex to a PI futex
 gcc-plugins.txt
 	- GCC plugin infrastructure.
-gcov.txt
-	- use of GCC's coverage testing tool "gcov" with the Linux kernel
 gpio/
 	- gpio related documentation
 gpu/
@@ -201,8 +183,6 @@ hid/
 	- directory with information on human interface devices
 highuid.txt
 	- notes on the change from 16 bit to 32 bit user/group IDs.
-hsi.txt
-	- HSI subsystem overview.
 hwspinlock.txt
 	- hardware spinlock provides hardware assistance for synchronization
 timers/
@@ -213,8 +193,6 @@ hwmon/
 	- directory with docs on various hardware monitoring drivers.
 i2c/
 	- directory with info about the I2C bus/protocol (2 wire, kHz speed).
-i2o/
-	- directory with info about the Linux I2O subsystem.
 x86/i386/
 	- directory with info about Linux on Intel 32 bit architecture.
 ia64/
@@ -243,8 +221,6 @@ isapnp.txt
 	- info on Linux ISA Plug & Play support.
 isdn/
 	- directory with info on the Linux ISDN support, and supported cards.
-ja_JP/
-	- directory with Japanese translations of various documents
 kbuild/
 	- directory with info about the kernel build process.
 kernel-doc-nano-HOWTO.txt
@@ -255,12 +231,6 @@ doc-guide/
 	- how to write and format reStructuredText kernel documentation
 kernel-per-CPU-kthreads.txt
 	- List of all per-CPU kthreads and how they introduce jitter.
-kmemcheck.txt
-	- info on dynamic checker that detects uses of uninitialized memory.
-kmemleak.txt
-	- info on how to make use of the kernel memory leak detection system
-ko_KR/
-	- directory with Korean translations of various documents
 kobject.txt
 	- info of the kobject infrastructure of the Linux kernel.
 kprobes.txt
@@ -277,8 +247,6 @@ leds/
 	- directory with info about LED handling under Linux.
 livepatch/
 	- info on kernel live patching.
-local_ops.txt
-	- semantics and behavior of local atomic operations.
 locking/
 	- directory with info about kernel locking primitives
 lockup-watchdogs.txt
@@ -291,8 +259,6 @@ lzo.txt
 	- kernel LZO decompressor input formats
 m68k/
 	- directory with info about Linux on Motorola 68k architecture.
-magic-number.txt
-	- list of magic numbers used to mark/protect kernel data structures.
 mailbox.txt
 	- How to write drivers for the common mailbox framework (IPC).
 md-cluster.txt
@@ -319,8 +285,6 @@ mmc/
 	- directory with info about the MMC subsystem
 mn10300/
 	- directory with info about the mn10300 architecture port
-module-signing.txt
-	- Kernel module signing for increased security when loading modules.
 mtd/
 	- directory with info about memory technology devices (flash)
 namespaces/
@@ -347,8 +311,6 @@ padata.txt
 	- An introduction to the "padata" parallel execution API
 parisc/
 	- directory with info on using Linux on PA-RISC architecture.
-parport.txt
-	- how to use the parallel-port driver.
 parport-lowlevel.txt
 	- description and usage of the low level parallel port functions.
 pcmcia/
@@ -423,8 +385,6 @@ smsc_ece1099.txt
 	-info on the smsc Keyboard Scan Expansion/GPIO Expansion device.
 sound/
 	- directory with info on sound card support.
-sparse.txt
-	- info on how to obtain and use the sparse tool for typechecking.
 spi/
 	- overview of Linux kernel Serial Peripheral Interface (SPI) support.
 static-keys.txt
@@ -433,12 +393,8 @@ svga.txt
 	- short guide on selecting video modes at boot via VGA BIOS.
 sync_file.txt
 	- Sync file API guide.
-sysfs-rules.txt
-	- How not to use sysfs.
 sysctl/
 	- directory with info on the /proc/sys/* files.
-sysrq.txt
-	- info on the magic SysRq key.
 target/
 	- directory with info on generating TCM v4 fabric .ko modules
 this_cpu_ops.txt
@@ -455,20 +411,14 @@ unshare.txt
 	- description of the Linux unshare system call.
 usb/
 	- directory with info regarding the Universal Serial Bus.
-vDSO/
-	- directory with info regarding virtual dynamic shared objects
 vfio.txt
 	- info on Virtual Function I/O used in guest/hypervisor instances.
-vgaarbiter.txt
-	- info on enable/disable the legacy decoding on different VGA devices
 video-output.txt
 	- sysfs class driver interface to enable/disable a video output device.
 virtual/
 	- directory with information on the various linux virtualizations.
 vm/
 	- directory with info on the Linux vm code.
-vme_api.txt
-	- file relating info on the VME bus API in linux
 w1/
 	- directory with documents regarding the 1-wire (w1) subsystem.
 watchdog/
@@ -485,7 +435,5 @@ xtensa/
 	- directory with documents relating to arch/xtensa port/implementation
 xz.txt
 	- how to make use of the XZ data compression within linux kernel
-zh_CN/
-	- directory with Chinese translations of various documents
 zorro.txt
 	- info on writing drivers for Zorro bus devices found on Amigas.
-- 
2.9.3

[PATCH 5/5] docs: 00-INDEX: document directories/files with no docs

[Mauro Carvalho Chehab]

There are a number of files/directories that don't contain
any documentation. They're related to ReST file conversion.

As a matter of completeness, since Makefile is also documented
there, add an entry for those files too.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/00-INDEX | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 272f5c4481f1..6d488509285d 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -14,6 +14,8 @@ Following translations are available on the WWW:
 	- this file.
 ABI/
 	- info on kernel <-> userspace ABI and relative interface stability.
+CodingStyle
+	- nothing here, just a pointer to process/coding-style.rst.
 DMA-API.txt
 	- DMA API, pci_ API & extensions for non-consistent memory machines.
 DMA-API-HOWTO.txt
@@ -39,6 +41,9 @@ Intel-IOMMU.txt
 Makefile
 	- This file does nothing. Removing it breaks make htmldocs and
 	  make distclean.
+Makefile.sphinx
+	- This file does nothing. Removing it breaks make htmldocs and
+	  make distclean.
 PCI/
 	- info related to PCI drivers.
 RCU/
@@ -47,6 +52,8 @@ SAK.txt
 	- info on Secure Attention Keys.
 SM501.txt
 	- Silicon Motion SM501 multimedia companion chip
+SubmittingPatches
+	- nothing here, just a pointer to process/coding-style.rst.
 accounting/
 	- documentation on accounting and taskstats.
 acpi/
@@ -93,6 +100,8 @@ clk.txt
 	- info on the common clock framework
 cma/
 	- Continuous Memory Area (CMA) debugfs interface.
+conf.py
+	- nothing here. Just a configuration file for Sphinx.
 connector/
 	- docs on the netlink based userspace<->kernel space communication mod.
 console/
@@ -135,6 +144,8 @@ digsig.txt
 	-info on the Digital Signature Verification API
 dma-buf-sharing.txt
 	- the DMA Buffer Sharing API Guide
+docutils.conf
+	- nothing here. Just a configuration file for docutils.
 dontdiff
 	- file containing a list of files that should never be diff'ed.
 driver-api/
@@ -201,6 +212,8 @@ ide/
 	- Information regarding the Enhanced IDE drive.
 iio/
 	- info on industrial IIO configfs support.
+index.rst
+	- main index for the documentation at ReST format.
 infiniband/
 	- directory with documents concerning Linux InfiniBand support.
 input/
@@ -307,6 +320,8 @@ nvdimm/
 	- info on non-volatile devices.
 nvmem/
 	- info on non volatile memory framework.
+output/
+	- default directory where html/LaTeX/pdf files will be written.
 padata.txt
 	- An introduction to the "padata" parallel execution API
 parisc/
@@ -387,6 +402,10 @@ sound/
 	- directory with info on sound card support.
 spi/
 	- overview of Linux kernel Serial Peripheral Interface (SPI) support.
+sphinx/
+	- no doumentation here, just files required by Sphinx toolchain.
+sphinx-static/
+	- no doumentation here, just files required by Sphinx toolchain.
 static-keys.txt
 	- info on how static keys allow debug code in hotpaths via patching
 svga.txt
-- 
2.9.3

Re: [PATCH 5/5] docs: 00-INDEX: document directories/files with no docs

[Jonathan Corbet]

On Mon,  5 Dec 2016 09:41:45 -0200
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> There are a number of files/directories that don't contain
> any documentation. They're related to ReST file conversion.
> 
> As a matter of completeness, since Makefile is also documented
> there, add an entry for those files too.

As promised, a couple of quibbles...

> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/00-INDEX | 19 +++++++++++++++++++
>  1 file changed, 19 insertions(+)
> 
> diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
> index 272f5c4481f1..6d488509285d 100644
> --- a/Documentation/00-INDEX
> +++ b/Documentation/00-INDEX
> @@ -14,6 +14,8 @@ Following translations are available on the WWW:
>  	- this file.
>  ABI/
>  	- info on kernel <-> userspace ABI and relative interface stability.
> +CodingStyle
> +	- nothing here, just a pointer to process/coding-style.rst.
>  DMA-API.txt
>  	- DMA API, pci_ API & extensions for non-consistent memory machines.
>  DMA-API-HOWTO.txt
> @@ -39,6 +41,9 @@ Intel-IOMMU.txt
>  Makefile
>  	- This file does nothing. Removing it breaks make htmldocs and
>  	  make distclean.
> +Makefile.sphinx
> +	- This file does nothing. Removing it breaks make htmldocs and
> +	  make distclean.

To say that this file "does nothing" is clearly incorrect - it controls how
the sphinx build is done.

>  PCI/
>  	- info related to PCI drivers.
>  RCU/
> @@ -47,6 +52,8 @@ SAK.txt
>  	- info on Secure Attention Keys.
>  SM501.txt
>  	- Silicon Motion SM501 multimedia companion chip
> +SubmittingPatches
> +	- nothing here, just a pointer to process/coding-style.rst.
>  accounting/
>  	- documentation on accounting and taskstats.
>  acpi/
> @@ -93,6 +100,8 @@ clk.txt
>  	- info on the common clock framework
>  cma/
>  	- Continuous Memory Area (CMA) debugfs interface.
> +conf.py
> +	- nothing here. Just a configuration file for Sphinx.

Again, it's not "nothing"; we could say it's not of interest to people who
aren't doing things with the build system.

>  connector/
>  	- docs on the netlink based userspace<->kernel space communication mod.
>  console/
> @@ -135,6 +144,8 @@ digsig.txt
>  	-info on the Digital Signature Verification API
>  dma-buf-sharing.txt
>  	- the DMA Buffer Sharing API Guide
> +docutils.conf
> +	- nothing here. Just a configuration file for docutils.
>  dontdiff
>  	- file containing a list of files that should never be diff'ed.
>  driver-api/
> @@ -201,6 +212,8 @@ ide/
>  	- Information regarding the Enhanced IDE drive.
>  iio/
>  	- info on industrial IIO configfs support.
> +index.rst
> +	- main index for the documentation at ReST format.
>  infiniband/
>  	- directory with documents concerning Linux InfiniBand support.
>  input/
> @@ -307,6 +320,8 @@ nvdimm/
>  	- info on non-volatile devices.
>  nvmem/
>  	- info on non volatile memory framework.
> +output/
> +	- default directory where html/LaTeX/pdf files will be written.
>  padata.txt
>  	- An introduction to the "padata" parallel execution API
>  parisc/
> @@ -387,6 +402,10 @@ sound/
>  	- directory with info on sound card support.
>  spi/
>  	- overview of Linux kernel Serial Peripheral Interface (SPI) support.
> +sphinx/
> +	- no doumentation here, just files required by Sphinx toolchain.

Indeed there's no "doumentation" there :)  No documentation either.

> +sphinx-static/
> +	- no doumentation here, just files required by Sphinx toolchain.
>  static-keys.txt
>  	- info on how static keys allow debug code in hotpaths via patching
>  svga.txt

Thanks,

jon

Re: [PATCH 5/5] docs: 00-INDEX: document directories/files with no docs

[Mauro Carvalho Chehab]

Em Mon, 5 Dec 2016 14:25:40 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Mon,  5 Dec 2016 09:41:45 -0200
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > There are a number of files/directories that don't contain
> > any documentation. They're related to ReST file conversion.
> > 
> > As a matter of completeness, since Makefile is also documented
> > there, add an entry for those files too.  
> 
> As promised, a couple of quibbles...
> 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > ---
> >  Documentation/00-INDEX | 19 +++++++++++++++++++
> >  1 file changed, 19 insertions(+)
> > 
> > diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
> > index 272f5c4481f1..6d488509285d 100644
> > --- a/Documentation/00-INDEX
> > +++ b/Documentation/00-INDEX
> > @@ -14,6 +14,8 @@ Following translations are available on the WWW:
> >  	- this file.
> >  ABI/
> >  	- info on kernel <-> userspace ABI and relative interface stability.
> > +CodingStyle
> > +	- nothing here, just a pointer to process/coding-style.rst.
> >  DMA-API.txt
> >  	- DMA API, pci_ API & extensions for non-consistent memory machines.
> >  DMA-API-HOWTO.txt
> > @@ -39,6 +41,9 @@ Intel-IOMMU.txt
> >  Makefile
> >  	- This file does nothing. Removing it breaks make htmldocs and
> >  	  make distclean.
> > +Makefile.sphinx
> > +	- This file does nothing. Removing it breaks make htmldocs and
> > +	  make distclean.  
> 
> To say that this file "does nothing" is clearly incorrect - it controls how
> the sphinx build is done.

Basically, I repeated the same text as the one for Makefile. I'll
send a patch changing both texts ;)

> 
> >  PCI/
> >  	- info related to PCI drivers.
> >  RCU/
> > @@ -47,6 +52,8 @@ SAK.txt
> >  	- info on Secure Attention Keys.
> >  SM501.txt
> >  	- Silicon Motion SM501 multimedia companion chip
> > +SubmittingPatches
> > +	- nothing here, just a pointer to process/coding-style.rst.
> >  accounting/
> >  	- documentation on accounting and taskstats.
> >  acpi/
> > @@ -93,6 +100,8 @@ clk.txt
> >  	- info on the common clock framework
> >  cma/
> >  	- Continuous Memory Area (CMA) debugfs interface.
> > +conf.py
> > +	- nothing here. Just a configuration file for Sphinx.  
> 
> Again, it's not "nothing"; we could say it's not of interest to people who
> aren't doing things with the build system.

Ok.

> 
> >  connector/
> >  	- docs on the netlink based userspace<->kernel space communication mod.
> >  console/
> > @@ -135,6 +144,8 @@ digsig.txt
> >  	-info on the Digital Signature Verification API
> >  dma-buf-sharing.txt
> >  	- the DMA Buffer Sharing API Guide
> > +docutils.conf
> > +	- nothing here. Just a configuration file for docutils.
> >  dontdiff
> >  	- file containing a list of files that should never be diff'ed.
> >  driver-api/
> > @@ -201,6 +212,8 @@ ide/
> >  	- Information regarding the Enhanced IDE drive.
> >  iio/
> >  	- info on industrial IIO configfs support.
> > +index.rst
> > +	- main index for the documentation at ReST format.
> >  infiniband/
> >  	- directory with documents concerning Linux InfiniBand support.
> >  input/
> > @@ -307,6 +320,8 @@ nvdimm/
> >  	- info on non-volatile devices.
> >  nvmem/
> >  	- info on non volatile memory framework.
> > +output/
> > +	- default directory where html/LaTeX/pdf files will be written.
> >  padata.txt
> >  	- An introduction to the "padata" parallel execution API
> >  parisc/
> > @@ -387,6 +402,10 @@ sound/
> >  	- directory with info on sound card support.
> >  spi/
> >  	- overview of Linux kernel Serial Peripheral Interface (SPI) support.
> > +sphinx/
> > +	- no doumentation here, just files required by Sphinx toolchain.  
> 
> Indeed there's no "doumentation" there :)  No documentation either.

Heh ;) I'll fix the typo.

> 
> > +sphinx-static/
> > +	- no doumentation here, just files required by Sphinx toolchain.
> >  static-keys.txt
> >  	- info on how static keys allow debug code in hotpaths via patching
> >  svga.txt  
> 
> Thanks,
> 
> jon



Thanks,
Mauro

Re: [PATCH 0/5] Update Documentation/00-INDEX

[Jonathan Corbet]

On Mon,  5 Dec 2016 09:41:40 -0200
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> So, in order to check it, I wrote a small script that compares the files
> and directories at Documentation/ with the ones at 00-INDEX.
> 
> Then, I synchronized the entries, making the script happy.
> 
> We might think on integrating the script with checkpatch.pl, but, as
> we should get rid of 00-INDEX, it probably not worth the efforts.

I would agree with that; I don't see the point of keeping those files
around in the longer term.

I've applied the set.  I do have a few quibbles with the final patch that
I'll send separately, but they're not something to hold this set up for.

Thanks,

jon

Re: [PATCH 0/5] Update Documentation/00-INDEX

[Mauro Carvalho Chehab]

Em Mon, 5 Dec 2016 14:23:01 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Mon,  5 Dec 2016 09:41:40 -0200
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > So, in order to check it, I wrote a small script that compares the files
> > and directories at Documentation/ with the ones at 00-INDEX.
> > 
> > Then, I synchronized the entries, making the script happy.
> > 
> > We might think on integrating the script with checkpatch.pl, but, as
> > we should get rid of 00-INDEX, it probably not worth the efforts.  
> 
> I would agree with that; I don't see the point of keeping those files
> around in the longer term.
> 
> I've applied the set.  I do have a few quibbles with the final patch that
> I'll send separately, but they're not something to hold this set up for.

Jon,

Did a patch fixing the quibbles.

As it seems you didn't push yet the changeset upstream, feel free to
just fold it with patch 5/5 if you prefer so, or to add as a separate
patch at the end of the series.

Patch enclosed.

Thanks,
Mauro

[PATCH] docs: 00-INDEX: change text related to the building system

Let be clearer on those files related to the build system.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 6d488509285d..5bd4b07c2f90 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -39,11 +39,9 @@ IRQ.txt
 Intel-IOMMU.txt
 	- basic info on the Intel IOMMU virtualization support.
 Makefile
-	- This file does nothing. Removing it breaks make htmldocs and
-	  make distclean.
+	- It's not of interest for those who aren't touching the build system.
 Makefile.sphinx
-	- This file does nothing. Removing it breaks make htmldocs and
-	  make distclean.
+	- It's not of interest for those who aren't touching the build system.
 PCI/
 	- info related to PCI drivers.
 RCU/
@@ -101,7 +99,7 @@ clk.txt
 cma/
 	- Continuous Memory Area (CMA) debugfs interface.
 conf.py
-	- nothing here. Just a configuration file for Sphinx.
+	- It's not of interest for those who aren't touching the build system.
 connector/
 	- docs on the netlink based userspace<->kernel space communication mod.
 console/
@@ -403,9 +401,9 @@ sound/
 spi/
 	- overview of Linux kernel Serial Peripheral Interface (SPI) support.
 sphinx/
-	- no doumentation here, just files required by Sphinx toolchain.
+	- no documentation here, just files required by Sphinx toolchain.
 sphinx-static/
-	- no doumentation here, just files required by Sphinx toolchain.
+	- no documentation here, just files required by Sphinx toolchain.
 static-keys.txt
 	- info on how static keys allow debug code in hotpaths via patching
 svga.txt