0f776dc377
Pull documentation updates from Jonathan Corbet:
"Some big changes this month, headlined by the addition of a new
formatted documentation mechanism based on the Sphinx system.
The objectives here are to make it easier to create better-integrated
(and more attractive) documents while (eventually) dumping our
one-of-a-kind, cobbled-together system for something that is widely
used and maintained by others. There's a fair amount of information
what's being done, why, and how to use it in:
https://lwn.net/Articles/692704/
https://lwn.net/Articles/692705/
Closer to home, Documentation/kernel-documentation.rst describes how
it works.
For now, the new system exists alongside the old one; you should soon
see the GPU documentation converted over in the DRM pull and some
significant media conversion work as well. Once all the docs have
been moved over and we're convinced that the rough edges (of which are
are a few) have been smoothed over, the DocBook-based stuff should go
away.
Primary credit is to Jani Nikula for doing the heavy lifting to make
this stuff actually work; there has also been notable effort from
Markus Heiser, Daniel Vetter, and Mauro Carvalho Chehab.
Expect a couple of conflicts on the new index.rst file over the course
of the merge window; they are trivially resolvable. That file may be
a bit of a conflict magnet in the short term, but I don't expect that
situation to last for any real length of time.
Beyond that, of course, we have the usual collection of tweaks,
updates, and typo fixes"
* tag 'docs-for-linus' of git://git.lwn.net/linux: (77 commits)
doc-rst: kernel-doc: fix handling of address_space tags
Revert "doc/sphinx: Enable keep_warnings"
doc-rst: kernel-doc directive, fix state machine reporter
docs: deprecate kernel-doc-nano-HOWTO.txt
doc/sphinx: Enable keep_warnings
Documentation: add watermark_scale_factor to the list of vm systcl file
kernel-doc: Fix up warning output
docs: Get rid of some kernel-documentation warnings
doc-rst: add an option to ignore DocBooks when generating docs
workqueue: Fix a typo in workqueue.txt
Doc: ocfs: Fix typo in filesystems/ocfs2-online-filecheck.txt
Documentation/sphinx: skip build if user requested specific DOCBOOKS
Documentation: add cleanmediadocs to the documentation targets
Add .pyc files to .gitignore
Doc: PM: Fix a typo in intel_powerclamp.txt
doc-rst: flat-table directive - initial implementation
Documentation: add meta-documentation for Sphinx and kernel-doc
Documentation: tiny typo fix in usb/gadget_multi.txt
Documentation: fix wrong value in md.txt
bcache: documentation formatting, edited for clarity, stripe alignment notes
...
Documentation for /proc/sys/ kernel version 2.2.10 (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 the source...' Well, this documentation is written because some people either don't know they need to tweak something, or because they don't 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 The consequences are that I won't guarantee the correctness of this document, and if you come to me complaining about how you screwed up your system because of wrong documentation, I won't feel sorry for you. I might even laugh at you... But of course, if you _do_ manage to screw up your system using only the sysctl options used in this file, I'd like to hear of it. Not only to have a great laugh, but also to make sure that you're the last RTFMing person to screw up. In short, e-mail your suggestions, corrections and / or horror stories to: <riel@nl.linux.org> Rik van Riel. ============================================================== 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) - knowledge of what all those values mean As a quick 'ls /proc/sys' will show, the directory consists of 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: abi/ execution domains & personalities debug/ <empty> dev/ device specific information (eg dev/cdrom/info) fs/ specific filesystems filehandle, inode, dentry and quota tuning binfmt_misc <Documentation/binfmt_misc.txt> kernel/ global kernel info / tuning miscellaneous stuff net/ networking stuff, for documentation look in: <Documentation/networking/> proc/ <empty> sunrpc/ SUN Remote Procedure Call (NFS) vm/ memory management tuning buffer and cache management 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 :-)