21 Sep, 2016
40 commits
-
Reorder the on-line documents based on their timestamp or
copyright notes. More updated documents come first.While here, add the number of pages for POSIX4 document.
Signed-off-by: Mauro Carvalho Chehab
-
It is a way better to have a timestamp to help identifying
when something is too old.So, retrieve the dates marked on the existing documents.
Signed-off-by: Mauro Carvalho Chehab
-
There are still some broken docs: the URLs point to somewhere,
however, the texts are not there anymore. I was able to
find the texts on other URLs for some of those, but they're all
too old. So, just get rid of them.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
There are three places where it mentions in-kernel docs.
Move them to a separate topic.
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
The Linux Kernel - This book is for Kernel 2.0.33
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Add two books from my own bookshelf. I found them useful by
the time I bought; so it could be useful to others ;)Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Instead of using a random order, place the books on publication
date, from the newest to the oldest.Signed-off-by: Mauro Carvalho Chehab
-
- remove LDD versions 1 and 2, as there's already an entry for
LDD3;
- add a link between LDD online and published entries.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
- Use lower case for sections, as this is the standard used on
the other ReST files;
- The latest version of this document is at the Kernel source, and
not at the listed URL. So, move it to the end of the doc.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
This introduces a consistent indenting of 4 spaces for all
lists.[mchehab@s-opensource.com: rebased to apply before rename]
Signed-off-by: Richard Sailer
Signed-off-by: Mauro Carvalho Chehab -
Background/Reasoning:
Books:
------
* Linux Kernel Networking by Rami Rosen
While some parts are quite short and could be
more carefully explained it's still a good recomendation
for understanding linux kernel networking, (IMHO)* Linux Treiber entwickeln:
It sure is a drawback that this is a german book.
But it's quite recent, well structured and there are also
other non-english (spanish) books/papers in this list.Papers:
-------* On Submitting kernel Patches
Contains 2 case studies of bigger patch sets and how (or how not)
they were merged. I found it helpful* Tracing the Way of Data in a TCP Connection through the Linux Kernel
Since this was written by me this inclusion may be a bit biased :p
Neitherless I think this gives a good introduction on
understanding/exploring linux internals using ftrace and an overview
of Linux TCP internals.[mchehab@s-opensource.com: rebased to apply before rename]
Signed-off-by: Richard Sailer
Signed-off-by: Mauro Carvalho Chehab -
The dots at the ends of the list elements introduced
unnecesarry newlines in the "compiled" document.While this was not "mission critical" it's not nice to look at
either.[mchehab@s-opensource.com: rebased to apply before rename]
Signed-off-by: Richard Sailer
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
This removes all dead links to online docs which
are dead according to Jon and Mauro in
https://lkml.kernel.org/r/20160916182849.2a7101ea () vento ! lanAdditionally some references to very old articles refering to
linux 2.2 and 2.0 are deleted.[mchehab@s-opensource.com: rebased to apply before rename]
Signed-off-by: Richard Sailer
Signed-off-by: Mauro Carvalho Chehab -
Mauro's patch set introduced some bare :: lines; these can be represented
by a double colon at the end of the preceding text line. The result looks
a little less weird and is less verbose.Signed-off-by: Jonathan Corbet
-
- use ``foo`` to markup inline literal stuff, effectively making it
to be presented as a monospaced font when parsed by Sphinx;- the markup below the title should have the same length as the
title;- Fix the list markups, from "1:" to "1)";
- Split item 2 into a separate list for the build options, in order
to be presented as a list on Sphinx;Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Task 11 (kernel-doc) still mentions usage of make manpages, but
this won't work if the API is documented via Sphinx. So, update
it to use either htmldocs or pdfdocs, with are the documentation
targets that work for all.While here, add ReST reference to the kernel documentation book.
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
- A few link references were missing http://
- Several sites are now redirecting to https protocol. On such
cases, just use the https URL.NOTE: all URLs were checked and they're pointing to the right places.
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Do a series of minor improvements at the ReST output format:
- Instead of using the quote blocks (::) for quotes, use
italics. That looks nicer on epub (and html) output, as
no scroll bar will be added. Also, it will adjust line
breaks on the text automatically.- Add a missing reference to SubmittingPatches.rst and use
**foo** instead of _foo_.- use bold for "The Perfect Patch" by removing a newline.
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
The description there are pre-Sphinx. Update it to cover the
new way.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Add cross references for the documents mentioned at HOWTO and
are under the Documentation/ directory, using the ReST notation.It should be noticed that HOWTO also mentions the /README file.
We opted to not touch it, for now, as making it build on
Sphinx would require it to be moved to a Documentation/foo
directory.Signed-off-by: Mauro Carvalho Chehab
Acked-by: Greg Kroah-Hartman
Signed-off-by: Jonathan Corbet -
This one required lots of manual work, for it to be properly
displayed.Signed-off-by: Mauro Carvalho Chehab
-
Do a few changes to make the output look better:
- use bullets on trivial patches list;
- use monotonic font for tools name;
- use :manpage:`foo` for man pages;
- don't put all references to maintainer*html at the same line.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
- Change the sections to use ReST markup;
- Add cross-references where needed;
- convert aspas to verbatim text;
- use code block tags;
- make Sphinx happy.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
- Change the document title markup to make it on a higher level;
- Add blank lines as needed, to improve the output;
- use italics for the country-code at kernel.org ftp URL.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
- use ReST markups for section headers;
- add cross-references to the options;
- mark code blocks;
- a few minor changes to make Sphinx happy.Signed-off-by: Mauro Carvalho Chehab
Acked-by: Greg Kroah-Hartman
Signed-off-by: Jonathan Corbet -
Add markups for it to be properly parsed by Sphinx.
As people browsing this document may not notice that the source
file title is "stable_api_nonsense", I opted to use bold to
the rationale for this document. I also found it better to
add a note when it says that the nonsense applies only to the
kABI/kAPI, and not to uAPI.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Add a name for the document and convert the sections to
ReST markups.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
- Convert document name to ReST;
- Convert footnotes;
- Convert sections to ReST format;
- Don't use _foo_, as Sphinx doesn't support underline. Instead,
use bold;
- While here, remove whitespaces at the end of lines.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
There are two places there where there are notes that should
be highlighted. So, use the ReST note markup for such texts.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Sphinx doesn't accept underline markups by purpose.
While there are ways to support underline via CSS, this won't
be portable with non-html outputs.As we want CodingStyle to do emphasis, replace _foo_ by **foo**,
using bold emphasis.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
On Sphinx/ReST notation, ``foo`` means that foo will be will be
marked as inline literal, effectively making it to be presented
as a monospaced font.As we want this document to be parsed by Sphinx, instead of using
"foo", use ``foo`` for the names that are literal, because it is an
usual typographic convention to use monospaced fonts for functions
and language commands on documents, and we're following such
convention on the other ReST books.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
- Fix all chapter identation;
- add c blocks where needed;Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
As discussed at linux-doc ML, the best is to keep all documents
backward compatible with Sphinx version 1.2, as it is the latest
version found on some distros like Debian.All books currently support it.
Please notice that, while it mentions the eventual need of
XeLaTex and texlive to build pdf files, this is not a minimal
requirement, as one could just be interested on building html
documents. Also, identifying the minimal requirements for
texlive packages is not trivial, as each distribution seems to
use different criteria on grouping LaTex functionalities.While here, update the current kernel version to 4.x.
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
- Fix chapter identation inconsistencies;
- Convert table to ReST format;
- use the right tag for bullets;
- Fix bold emphasis;
- mark blocks with :: tags;
- use verbatim font for files;
- make Sphinx happySigned-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
This document is old: it is from Kernel v2.6.12 days.
Update it to the current status, and add a reference for the
linux-next tree.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
- use the correct markup to identify each section;
- Add some blank lines for Sphinx to properly interpret
the markups;- Remove a blank space on some paragraphs;
- Fix the verbatim and bold markups;
- Cleanup the remaining errors to make Sphinx happy.
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
This document is almost compliant with ReST notation, but some
small adjustments are needed to make it parse properly by
Sphinx (mostly, add blank lines where needed).Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Now that the files at Documentation/development-process/
were converted to ReST, make create a book at Sphinx.As we'll have other books related to the development process,
we'll add it as a sub-book.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Now that the documents were converted, rename them to .rst, as
this is needed by the Sphinx build logic.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
This document is on good shape for ReST: all it was needed was
to fix the section markups, add a toctree, convert the tables
and add a few code/quote blocks.While not strictly required, I opted to use lowercase for
the titles, just like the other books that were converted
to Sphinx.Signed-off-by: Mauro Carvalho Chehab
