Update Documentation/00-INDEX

PATCH In review Mauro Carvalho Chehab 2 participants 10 messages Dec 5, 2016 – Dec 6, 2016 Documentation

lore

Share & tools

lore

Mauro Carvalho Chehab

author

2016-12-05 12:13 UTC #0 lore raw

cover Update Documentation/00-INDEX

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

Signature · 1 line

2.9.3

Mauro Carvalho Chehab

author

2016-12-05 12:13 UTC #1 lore raw

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

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 <[email protected]>

---
 scripts/check_00index.sh | 66 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100755 scripts/check_00index.sh

scripts/check_00index.sh new file +66 -0

new file mode 100755
index 000000000000..6ac9527aeddb
@@ -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

Signature · 1 line

2.9.3

Mauro Carvalho Chehab

author

2016-12-05 12:13 UTC #2 lore raw

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

In reply to 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 <[email protected]>

---
 Documentation/00-INDEX | 61 ++++----------------------------------------------
 1 file changed, 4 insertions(+), 57 deletions(-)

Documentation/00-INDEX +4 ~~-57~~

index c08de5574d48..02583a1f409c 100644
@@ -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/

Signature · 1 line

2.9.3

Mauro Carvalho Chehab

author

2016-12-05 12:13 UTC #3 lore raw

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

In reply to 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 <[email protected]>

---
 Documentation/00-INDEX | 64 ++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 60 insertions(+), 4 deletions(-)

Documentation/00-INDEX +60 -4

index 02583a1f409c..bd532a7e03e6 100644
@@ -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

Signature · 1 line

2.9.3

Mauro Carvalho Chehab

author

2016-12-05 12:13 UTC #4 lore raw

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

In reply to 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 <[email protected]>

---
 Documentation/00-INDEX | 52 --------------------------------------------------
 1 file changed, 52 deletions(-)

Documentation/00-INDEX +0 ~~-52~~

index bd532a7e03e6..272f5c4481f1 100644
@@ -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.

Signature · 1 line

2.9.3

Mauro Carvalho Chehab

author

2016-12-05 12:13 UTC #5 lore raw

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

In reply to 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 <[email protected]>

---
 Documentation/00-INDEX | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

Documentation/00-INDEX +19 -0

index 272f5c4481f1..6d488509285d 100644
@@ -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

Signature · 1 line

2.9.3

Jonathan Corbet

maintainer

2016-12-05 21:25 UTC #6 lore raw

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

Quoted 5 lines · On Mon, 5 Dec 2016 09:41:45 -0200 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.

As promised, a couple of quibbles...

Quoted 19 lines

Signed-off-by Mauro Carvalho Chehab <[email protected]>

---
 Documentation/00-INDEX | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

Documentation/00-INDEX +2 -0

index 272f5c4481f1..6d488509285d 100644
@@ -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

Documentation/00-INDEX Intel-IOMMU.txt · line 46

Quoted 6 lines

Documentation/00-INDEX +3 -0

@@ -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.

Quoted 13 lines

Documentation/00-INDEX +2 -0

 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/

Documentation/00-INDEX clk.txt · line 104

Quoted 5 lines

Documentation/00-INDEX +2 -0

@@ -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.

Quoted 31 lines

Documentation/00-INDEX +6 -0

 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/

Documentation/00-INDEX sound/ · line 406

Quoted 5 lines

Documentation/00-INDEX +2 -0

@@ -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.

Documentation/00-INDEX sound/ · line 411

Quoted 5 lines

Documentation/00-INDEX +2 -0

+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

Mauro Carvalho Chehab

author

2016-12-06 12:41 UTC #7 lore raw

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

Em Mon, 5 Dec 2016 14:25:40 -0700
Jonathan Corbet <[email protected]> escreveu:

Quoted 31 lines

Quoted 5 lines · On Mon, 5 Dec 2016 09:41:45 -0200 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.
As promised, a couple of quibbles...
Quoted 20 lines
Signed-off-by Mauro Carvalho Chehab <[email protected]>
---
 Documentation/00-INDEX | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
Documentation/00-INDEX +2 -0
index 272f5c4481f1..6d488509285d 100644
@@ -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

Quoted 8 lines

Documentation/00-INDEX Intel-IOMMU.txt · line 46
Quoted 5 lines
Documentation/00-INDEX +3 -0
 	- 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 ;)

Quoted 14 lines

Documentation/00-INDEX +2 -0

 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

Quoted 8 lines

Documentation/00-INDEX clk.txt · line 104
Quoted 5 lines
Documentation/00-INDEX +2 -0
 	- 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.

Quoted 31 lines

Documentation/00-INDEX +6 -0

 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/

Quoted 8 lines

Documentation/00-INDEX sound/ · line 406
Quoted 6 lines
Documentation/00-INDEX +2 -0
@@ -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.

Quoted 10 lines

Documentation/00-INDEX sound/ · line 411
Quoted 6 lines
Documentation/00-INDEX +2 -0
+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

Jonathan Corbet

maintainer

2016-12-05 21:23 UTC #8 lore raw

In reply to Mauro Carvalho Chehab

Quoted 7 lines · On Mon, 5 Dec 2016 09:41:40 -0200 Mauro Carvalho Chehab…

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

Mauro Carvalho Chehab

author

2016-12-06 12:58 UTC #9 lore raw

Em Mon, 5 Dec 2016 14:23:01 -0700
Jonathan Corbet <[email protected]> escreveu:

Quoted 8 lines

Quoted 5 lines · On Mon, 5 Dec 2016 09:41:40 -0200 Mauro Carvalho Chehab…
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.

Quoted 8 lines

Quoted 2 lines
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 <[email protected]>

Documentation/00-INDEX +5 -7

index 6d488509285d..5bd4b07c2f90 100644
@@ -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