Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > linux.kernel > #1483201 > unrolled thread
| Started by | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| First post | 2016-09-14 13:20 +0200 |
| Last post | 2016-09-16 23:30 +0200 |
| Articles | 13 — 2 participants |
Back to article view | Back to linux.kernel
[PATCH v3 00/21] Create a book for Kernel development Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-14 13:20 +0200
[PATCH v3 03/21] docs-rst: create a book for the development process Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-14 13:20 +0200
[PATCH v3 12/21] Documentation/ManagementStyle: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-14 13:20 +0200
[PATCH v3 07/21] Documentation/CodingStyle: Convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-14 13:20 +0200
Re: [PATCH v3 07/21] Documentation/CodingStyle: Convert to ReST markup Jonathan Corbet <corbet@lwn.net> - 2016-09-16 19:20 +0200
Re: [PATCH v3 07/21] Documentation/CodingStyle: Convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-16 22:40 +0200
Re: [PATCH v3 07/21] Documentation/CodingStyle: Convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-17 12:00 +0200
[PATCH v3 14/21] Documentation/stable_api_nonsense.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-14 13:20 +0200
[PATCH v3 06/21] Documentation/Changes: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-14 13:20 +0200
Re: [PATCH v3 11/21] Documentation/kernel-docs.txt: convert it to ReST markup Jonathan Corbet <corbet@lwn.net> - 2016-09-16 19:20 +0200
Re: [PATCH v3 11/21] Documentation/kernel-docs.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-16 22:50 +0200
Re: [PATCH v3 11/21] Documentation/kernel-docs.txt: convert it to ReST markup Jonathan Corbet <corbet@lwn.net> - 2016-09-16 23:10 +0200
Re: [PATCH v3 11/21] Documentation/kernel-docs.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-16 23:30 +0200
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-14 13:20 +0200 |
| Subject | [PATCH v3 00/21] Create a book for Kernel development |
| Message-ID | <shgop-ao-3@gated-at.bofh.it> |
That's the third version of this series. Version 1 was submitted to
linux-doc only.
There are several documents related to Kernel development, where the
HOWTO works like an index to several such documents. There are also
a series of files describing the development process.
This patch series:
1) converts the Documentation/development-process/ to ReST
and creates a Sphinx book, prepared to support sub-books;
2) Converts several files under Documentation (Changes, CodingStyle,
HOWTO, ManagementStyle, SecurityBugs, SubmittingDrivers,
SubmittingPatches, applying-patches.txt, kernel-docs.txt,
stable_api_nonsense.txt, stable_kernel_rules.txt) to ReST markup;
3) Move the converted files to development-process/ directory, adding
a .rst extension to them, adjusting cross-references and adding them
to the development-process book.
NOTE: HOWTO also mentions the /README document on it. While IMHO it
makes sense to convert it to ReST, moving it out of the main directory
didn't sound a good idea. So, I'm leaving this one untouched.
PS.: I decided to do such conversion because I received yet another
email from one developer wanted to submit drivers, but not being
aware of the right proceures. As usual, I pointed him to the Kernel
sources, but there are a way too much documentation there with a mix of
procedures and API docs inside.
It would be a way easier to point to a single URL where the submission
procedures would be altoghether. Hopefully, this will have a lot of time
in the future. My evil plan is to put this doc somewhere at LinuxTV and
have a standard e-mail prepared for such next requests :-D
The produced output, in HTML, is at:
https://mchehab.fedorapeople.org/development-process/
The LaTeX version at:
https://mchehab.fedorapeople.org/development-process/latex/development-process.tex
And the PDF version at:
https://mchehab.fedorapeople.org/development-process/latex/development-process.pdf
--
Version 3 changes:
- Almost all changes here are just a patch set reordering to do first the
ReST conversion and then renames. Hopefully, Jon will be happier with
such approach ;)
- Fixed some issues pointed by Joe Pershes at the CodingStyle conversion;
- Better explain the rationale for using ``foo`` instead of "foo" at
CodingStyle.
Jani suggested to take the opportunity to standardize file name between
DocumentFoo, document-foo and document_foo. I opted to not do it
on this series, as we need first to agree on the convension. Once we have
some agreement, it should be easy to adjust the files to the agreed
nomenclature.
Version 2 changes:
- On version 1, I forgot to c/c LKML. Since v2, I'm c/c it, to give it a
broader audience.
- Per Jonathan Corbet's suggestion, this version is placing all documents at
the already existing developing-process/ directory, instead of creating a
new dir;
- Also per Jon's suggestion, it also converts the development-process files
to rst.
- Replaced all occurrences of the renamed files at the Kernel Documentation
dir;
- Added conf.py and the need logic to produce both LaTeX and PDF output;
Mauro Carvalho Chehab (21):
doc: development-process: convert it to ReST markup
doc: development-process: rename files to rst
docs-rst: create a book for the development process
Documentation/HOWTO: convert to ReST notation
Documentation/applying-patches.txt: convert it to ReST markup
Documentation/Changes: convert it to ReST markup
Documentation/CodingStyle: Convert to ReST markup
Documentation/CodingStyle: use the proper tag for verbatim font
Documentation/CodingStyle: replace underline markups
Documentation/CodingStyle: use the .. note:: markup where needed
Documentation/kernel-docs.txt: convert it to ReST markup
Documentation/ManagementStyle: convert it to ReST markup
Documentation/SecurityBugs: convert it to ReST markup
Documentation/stable_api_nonsense.txt: convert it to ReST markup
Documentation/stable_kernel_rules.txt: convert it to ReST markup
Documentation/SubmittingDrivers: convert it to ReST markup
Documentation/SubmittingPatches: convert it to ReST markup
Documentation/HOWTO: add cross-references to other documents
docs-rst: move HOWTO and mentioned documents to development-process/
doc: adjust references to development-process
doc-rst: Add the new development-process/ files to Sphinx build
Documentation/ABI/README | 2 +-
Documentation/BUG-HUNTING | 2 +-
Documentation/DocBook/kernel-hacking.tmpl | 4 +-
Documentation/SubmitChecklist | 4 +-
Documentation/adding-syscalls.txt | 2 +-
Documentation/conf.py | 2 +
.../development-process/{1.Intro => 1.Intro.rst} | 68 +-
.../{2.Process => 2.Process.rst} | 41 +-
.../{3.Early-stage => 3.Early-stage.rst} | 22 +-
.../development-process/{4.Coding => 4.Coding.rst} | 48 +-
.../{5.Posting => 5.Posting.rst} | 30 +-
.../{6.Followthrough => 6.Followthrough.rst} | 14 +-
.../{7.AdvancedTopics => 7.AdvancedTopics.rst} | 13 +-
.../{8.Conclusion => 8.Conclusion.rst} | 8 +-
.../{Changes => development-process/Changes.rst} | 226 +++---
.../CodingStyle.rst} | 384 ++++++----
.../{HOWTO => development-process/HOWTO.rst} | 73 +-
.../ManagementStyle.rst} | 152 ++--
.../SecurityBugs.rst} | 14 +-
.../SubmittingDrivers.rst} | 51 +-
.../SubmittingPatches.rst} | 244 ++++---
.../applying-patches.rst} | 312 ++++----
Documentation/development-process/conf.py | 10 +
.../development-process/development-process.rst | 27 +
Documentation/development-process/index.rst | 22 +
Documentation/development-process/kernel-docs.rst | 791 +++++++++++++++++++++
.../stable_api_nonsense.rst} | 35 +-
.../stable_kernel_rules.rst} | 107 ++-
.../devicetree/bindings/submitting-patches.txt | 2 +-
Documentation/filesystems/locks.txt | 2 +-
Documentation/hwmon/submitting-patches | 6 +-
Documentation/index.rst | 1 +
Documentation/isdn/README | 2 +-
Documentation/ja_JP/HOWTO | 28 +-
Documentation/ja_JP/SubmitChecklist | 2 +-
Documentation/ja_JP/SubmittingPatches | 14 +-
Documentation/ja_JP/stable_api_nonsense.txt | 4 +-
Documentation/ja_JP/stable_kernel_rules.txt | 6 +-
Documentation/kernel-docs.txt | 731 -------------------
Documentation/ko_KR/HOWTO | 28 +-
Documentation/ko_KR/stable_api_nonsense.txt | 4 +-
Documentation/networking/PLIP.txt | 2 +-
Documentation/networking/netdev-FAQ.txt | 8 +-
Documentation/scsi/scsi_mid_low_api.txt | 2 +-
Documentation/virtual/kvm/review-checklist.txt | 4 +-
.../watchdog/convert_drivers_to_kernel_api.txt | 2 +-
Documentation/zh_CN/CodingStyle | 4 +-
Documentation/zh_CN/HOWTO | 28 +-
Documentation/zh_CN/SecurityBugs | 4 +-
Documentation/zh_CN/SubmittingDrivers | 8 +-
Documentation/zh_CN/SubmittingPatches | 10 +-
Documentation/zh_CN/stable_api_nonsense.txt | 4 +-
Documentation/zh_CN/stable_kernel_rules.txt | 6 +-
MAINTAINERS | 2 +-
README | 4 +-
REPORTING-BUGS | 2 +-
drivers/net/ppp/Kconfig | 2 +-
drivers/pcmcia/Kconfig | 2 +-
fs/Kconfig.binfmt | 2 +-
fs/fuse/Kconfig | 2 +-
net/Kconfig | 4 +-
scripts/ver_linux | 2 +-
tools/testing/selftests/futex/README | 2 +-
63 files changed, 2120 insertions(+), 1524 deletions(-)
rename Documentation/development-process/{1.Intro => 1.Intro.rst} (87%)
rename Documentation/development-process/{2.Process => 2.Process.rst} (96%)
rename Documentation/development-process/{3.Early-stage => 3.Early-stage.rst} (97%)
rename Documentation/development-process/{4.Coding => 4.Coding.rst} (97%)
rename Documentation/development-process/{5.Posting => 5.Posting.rst} (96%)
rename Documentation/development-process/{6.Followthrough => 6.Followthrough.rst} (98%)
rename Documentation/development-process/{7.AdvancedTopics => 7.AdvancedTopics.rst} (98%)
rename Documentation/development-process/{8.Conclusion => 8.Conclusion.rst} (96%)
rename Documentation/{Changes => development-process/Changes.rst} (56%)
rename Documentation/{CodingStyle => development-process/CodingStyle.rst} (78%)
rename Documentation/{HOWTO => development-process/HOWTO.rst} (96%)
rename Documentation/{ManagementStyle => development-process/ManagementStyle.rst} (76%)
rename Documentation/{SecurityBugs => development-process/SecurityBugs.rst} (92%)
rename Documentation/{SubmittingDrivers => development-process/SubmittingDrivers.rst} (83%)
rename Documentation/{SubmittingPatches => development-process/SubmittingPatches.rst} (85%)
rename Documentation/{applying-patches.txt => development-process/applying-patches.rst} (68%)
create mode 100644 Documentation/development-process/conf.py
create mode 100644 Documentation/development-process/development-process.rst
create mode 100644 Documentation/development-process/index.rst
create mode 100644 Documentation/development-process/kernel-docs.rst
rename Documentation/{stable_api_nonsense.txt => development-process/stable_api_nonsense.rst} (92%)
rename Documentation/{stable_kernel_rules.txt => development-process/stable_kernel_rules.rst} (65%)
delete mode 100644 Documentation/kernel-docs.txt
--
2.7.4
[toc] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-14 13:20 +0200 |
| Subject | [PATCH v3 03/21] docs-rst: create a book for the development process |
| Message-ID | <shgoq-ao-45@gated-at.bofh.it> |
| In reply to | #1483201 |
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 <mchehab@s-opensource.com>
---
Documentation/conf.py | 2 ++
Documentation/development-process/conf.py | 10 ++++++++++
Documentation/development-process/index.rst | 9 +++++++++
Documentation/index.rst | 1 +
4 files changed, 22 insertions(+)
create mode 100644 Documentation/development-process/conf.py
create mode 100644 Documentation/development-process/index.rst
diff --git a/Documentation/conf.py b/Documentation/conf.py
index c25e95d46272..bf6f310e5170 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -338,6 +338,8 @@ latex_elements = {
latex_documents = [
('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation',
'The kernel development community', 'manual'),
+ ('development-process/index', 'development-process.tex', 'Linux Kernel Development Documentation',
+ 'The kernel development community', 'manual'),
('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide',
'The kernel development community', 'manual'),
('media/index', 'media.tex', 'Linux Media Subsystem Documentation',
diff --git a/Documentation/development-process/conf.py b/Documentation/development-process/conf.py
new file mode 100644
index 000000000000..4b4a12dace02
--- /dev/null
+++ b/Documentation/development-process/conf.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = 'Linux Kernel Development Documentation'
+
+tags.add("subproject")
+
+latex_documents = [
+ ('index', 'development-process.tex', 'Linux Kernel Development Documentation',
+ 'The kernel development community', 'manual'),
+]
diff --git a/Documentation/development-process/index.rst b/Documentation/development-process/index.rst
new file mode 100644
index 000000000000..c37475d91090
--- /dev/null
+++ b/Documentation/development-process/index.rst
@@ -0,0 +1,9 @@
+Linux Kernel Development Documentation
+======================================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ development-process
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 05eded59820e..c6cf3971788d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -12,6 +12,7 @@ Contents:
:maxdepth: 2
kernel-documentation
+ development-process/index
dev-tools/tools
media/index
gpu/index
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-14 13:20 +0200 |
| Subject | [PATCH v3 12/21] Documentation/ManagementStyle: convert it to ReST markup |
| Message-ID | <shgoq-ao-47@gated-at.bofh.it> |
| In reply to | #1483201 |
- 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 <mchehab@s-opensource.com>
---
Documentation/ManagementStyle | 152 ++++++++++++++++++++++--------------------
1 file changed, 80 insertions(+), 72 deletions(-)
diff --git a/Documentation/ManagementStyle b/Documentation/ManagementStyle
index a211ee8d8b44..86c5a19e08f3 100644
--- a/Documentation/ManagementStyle
+++ b/Documentation/ManagementStyle
@@ -1,10 +1,10 @@
-
- Linux kernel management style
+Linux kernel management style
+=============================
This is a short document describing the preferred (or made up, depending
on who you ask) management style for the linux kernel. It's meant to
mirror the CodingStyle document to some degree, and mainly written to
-avoid answering (*) the same (or similar) questions over and over again.
+avoid answering [#f1]_ the same (or similar) questions over and over again.
Management style is very personal and much harder to quantify than
simple coding style rules, so this document may or may not have anything
@@ -14,50 +14,52 @@ might not actually be true. You'll have to decide for yourself.
Btw, when talking about "kernel manager", it's all about the technical
lead persons, not the people who do traditional management inside
companies. If you sign purchase orders or you have any clue about the
-budget of your group, you're almost certainly not a kernel manager.
-These suggestions may or may not apply to you.
+budget of your group, you're almost certainly not a kernel manager.
+These suggestions may or may not apply to you.
First off, I'd suggest buying "Seven Habits of Highly Effective
-People", and NOT read it. Burn it, it's a great symbolic gesture.
+People", and NOT read it. Burn it, it's a great symbolic gesture.
-(*) This document does so not so much by answering the question, but by
-making it painfully obvious to the questioner that we don't have a clue
-to what the answer is.
+.. [#f1] This document does so not so much by answering the question, but by
+ making it painfully obvious to the questioner that we don't have a clue
+ to what the answer is.
Anyway, here goes:
+.. _decisions:
- Chapter 1: Decisions
+Decisions
+---------
Everybody thinks managers make decisions, and that decision-making is
important. The bigger and more painful the decision, the bigger the
manager must be to make it. That's very deep and obvious, but it's not
-actually true.
+actually true.
-The name of the game is to _avoid_ having to make a decision. In
+The name of the game is to **avoid** having to make a decision. In
particular, if somebody tells you "choose (a) or (b), we really need you
to decide on this", you're in trouble as a manager. The people you
manage had better know the details better than you, so if they come to
you for a technical decision, you're screwed. You're clearly not
-competent to make that decision for them.
+competent to make that decision for them.
(Corollary:if the people you manage don't know the details better than
-you, you're also screwed, although for a totally different reason.
-Namely that you are in the wrong job, and that _they_ should be managing
-your brilliance instead).
+you, you're also screwed, although for a totally different reason.
+Namely that you are in the wrong job, and that **they** should be managing
+your brilliance instead).
-So the name of the game is to _avoid_ decisions, at least the big and
+So the name of the game is to **avoid** decisions, at least the big and
painful ones. Making small and non-consequential decisions is fine, and
makes you look like you know what you're doing, so what a kernel manager
needs to do is to turn the big and painful ones into small things where
-nobody really cares.
+nobody really cares.
It helps to realize that the key difference between a big decision and a
small one is whether you can fix your decision afterwards. Any decision
can be made small by just always making sure that if you were wrong (and
-you _will_ be wrong), you can always undo the damage later by
+you **will** be wrong), you can always undo the damage later by
backtracking. Suddenly, you get to be doubly managerial for making
-_two_ inconsequential decisions - the wrong one _and_ the right one.
+**two** inconsequential decisions - the wrong one **and** the right one.
And people will even see that as true leadership (*cough* bullshit
*cough*).
@@ -65,10 +67,10 @@ And people will even see that as true leadership (*cough* bullshit
Thus the key to avoiding big decisions becomes to just avoiding to do
things that can't be undone. Don't get ushered into a corner from which
you cannot escape. A cornered rat may be dangerous - a cornered manager
-is just pitiful.
+is just pitiful.
It turns out that since nobody would be stupid enough to ever really let
-a kernel manager have huge fiscal responsibility _anyway_, it's usually
+a kernel manager have huge fiscal responsibility **anyway**, it's usually
fairly easy to backtrack. Since you're not going to be able to waste
huge amounts of money that you might not be able to repay, the only
thing you can backtrack on is a technical decision, and there
@@ -76,113 +78,116 @@ back-tracking is very easy: just tell everybody that you were an
incompetent nincompoop, say you're sorry, and undo all the worthless
work you had people work on for the last year. Suddenly the decision
you made a year ago wasn't a big decision after all, since it could be
-easily undone.
+easily undone.
It turns out that some people have trouble with this approach, for two
reasons:
+
- admitting you were an idiot is harder than it looks. We all like to
maintain appearances, and coming out in public to say that you were
- wrong is sometimes very hard indeed.
+ wrong is sometimes very hard indeed.
- having somebody tell you that what you worked on for the last year
wasn't worthwhile after all can be hard on the poor lowly engineers
- too, and while the actual _work_ was easy enough to undo by just
+ too, and while the actual **work** was easy enough to undo by just
deleting it, you may have irrevocably lost the trust of that
engineer. And remember: "irrevocable" was what we tried to avoid in
the first place, and your decision ended up being a big one after
- all.
+ all.
Happily, both of these reasons can be mitigated effectively by just
admitting up-front that you don't have a friggin' clue, and telling
people ahead of the fact that your decision is purely preliminary, and
might be the wrong thing. You should always reserve the right to change
-your mind, and make people very _aware_ of that. And it's much easier
-to admit that you are stupid when you haven't _yet_ done the really
+your mind, and make people very **aware** of that. And it's much easier
+to admit that you are stupid when you haven't **yet** done the really
stupid thing.
Then, when it really does turn out to be stupid, people just roll their
-eyes and say "Oops, he did it again".
+eyes and say "Oops, he did it again".
This preemptive admission of incompetence might also make the people who
actually do the work also think twice about whether it's worth doing or
-not. After all, if _they_ aren't certain whether it's a good idea, you
+not. After all, if **they** aren't certain whether it's a good idea, you
sure as hell shouldn't encourage them by promising them that what they
work on will be included. Make them at least think twice before they
-embark on a big endeavor.
+embark on a big endeavor.
Remember: they'd better know more about the details than you do, and
they usually already think they have the answer to everything. The best
thing you can do as a manager is not to instill confidence, but rather a
-healthy dose of critical thinking on what they do.
+healthy dose of critical thinking on what they do.
Btw, another way to avoid a decision is to plaintively just whine "can't
we just do both?" and look pitiful. Trust me, it works. If it's not
clear which approach is better, they'll eventually figure it out. The
answer may end up being that both teams get so frustrated by the
-situation that they just give up.
+situation that they just give up.
That may sound like a failure, but it's usually a sign that there was
something wrong with both projects, and the reason the people involved
couldn't decide was that they were both wrong. You end up coming up
smelling like roses, and you avoided yet another decision that you could
-have screwed up on.
+have screwed up on.
- Chapter 2: People
+People
+------
Most people are idiots, and being a manager means you'll have to deal
-with it, and perhaps more importantly, that _they_ have to deal with
-_you_.
+with it, and perhaps more importantly, that **they** have to deal with
+**you**.
It turns out that while it's easy to undo technical mistakes, it's not
as easy to undo personality disorders. You just have to live with
-theirs - and yours.
+theirs - and yours.
However, in order to prepare yourself as a kernel manager, it's best to
remember not to burn any bridges, bomb any innocent villagers, or
alienate too many kernel developers. It turns out that alienating people
is fairly easy, and un-alienating them is hard. Thus "alienating"
immediately falls under the heading of "not reversible", and becomes a
-no-no according to Chapter 1.
+no-no according to :ref:`decisions`.
There's just a few simple rules here:
(1) don't call people d*ckheads (at least not in public)
(2) learn how to apologize when you forgot rule (1)
The problem with #1 is that it's very easy to do, since you can say
-"you're a d*ckhead" in millions of different ways (*), sometimes without
+"you're a d*ckhead" in millions of different ways [#f2]_, sometimes without
even realizing it, and almost always with a white-hot conviction that
-you are right.
+you are right.
And the more convinced you are that you are right (and let's face it,
-you can call just about _anybody_ a d*ckhead, and you often _will_ be
-right), the harder it ends up being to apologize afterwards.
+you can call just about **anybody** a d*ckhead, and you often **will** be
+right), the harder it ends up being to apologize afterwards.
To solve this problem, you really only have two options:
- get really good at apologies
- spread the "love" out so evenly that nobody really ends up feeling
like they get unfairly targeted. Make it inventive enough, and they
- might even be amused.
+ might even be amused.
The option of being unfailingly polite really doesn't exist. Nobody will
trust somebody who is so clearly hiding his true character.
-(*) Paul Simon sang "Fifty Ways to Leave Your Lover", because quite
-frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't
-scan nearly as well. But I'm sure he thought about it.
+.. [#f2] Paul Simon sang "Fifty Ways to Leave Your Lover", because quite
+ frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't
+ scan nearly as well. But I'm sure he thought about it.
- Chapter 3: People II - the Good Kind
+People II - the Good Kind
+-------------------------
While it turns out that most people are idiots, the corollary to that is
sadly that you are one too, and that while we can all bask in the secure
knowledge that we're better than the average person (let's face it,
nobody ever believes that they're average or below-average), we should
also admit that we're not the sharpest knife around, and there will be
-other people that are less of an idiot than you are.
+other people that are less of an idiot than you are.
-Some people react badly to smart people. Others take advantage of them.
+Some people react badly to smart people. Others take advantage of them.
-Make sure that you, as a kernel maintainer, are in the second group.
+Make sure that you, as a kernel maintainer, are in the second group.
Suck up to them, because they are the people who will make your job
easier. In particular, they'll be able to make your decisions for you,
which is what the game is all about.
@@ -191,7 +196,7 @@ So when you find somebody smarter than you are, just coast along. Your
management responsibilities largely become ones of saying "Sounds like a
good idea - go wild", or "That sounds good, but what about xxx?". The
second version in particular is a great way to either learn something
-new about "xxx" or seem _extra_ managerial by pointing out something the
+new about "xxx" or seem **extra** managerial by pointing out something the
smarter person hadn't thought about. In either case, you win.
One thing to look out for is to realize that greatness in one area does
@@ -199,47 +204,49 @@ not necessarily translate to other areas. So you might prod people in
specific directions, but let's face it, they might be good at what they
do, and suck at everything else. The good news is that people tend to
naturally gravitate back to what they are good at, so it's not like you
-are doing something irreversible when you _do_ prod them in some
+are doing something irreversible when you **do** prod them in some
direction, just don't push too hard.
- Chapter 4: Placing blame
+Placing blame
+-------------
Things will go wrong, and people want somebody to blame. Tag, you're it.
It's not actually that hard to accept the blame, especially if people
-kind of realize that it wasn't _all_ your fault. Which brings us to the
+kind of realize that it wasn't **all** your fault. Which brings us to the
best way of taking the blame: do it for another guy. You'll feel good
for taking the fall, he'll feel good about not getting blamed, and the
guy who lost his whole 36GB porn-collection because of your incompetence
will grudgingly admit that you at least didn't try to weasel out of it.
Then make the developer who really screwed up (if you can find him) know
-_in_private_ that he screwed up. Not just so he can avoid it in the
+**in_private** that he screwed up. Not just so he can avoid it in the
future, but so that he knows he owes you one. And, perhaps even more
importantly, he's also likely the person who can fix it. Because, let's
-face it, it sure ain't you.
+face it, it sure ain't you.
-Taking the blame is also why you get to be manager in the first place.
+Taking the blame is also why you get to be manager in the first place.
It's part of what makes people trust you, and allow you the potential
glory, because you're the one who gets to say "I screwed up". And if
you've followed the previous rules, you'll be pretty good at saying that
-by now.
+by now.
- Chapter 5: Things to avoid
+Things to avoid
+---------------
There's one thing people hate even more than being called "d*ckhead",
and that is being called a "d*ckhead" in a sanctimonious voice. The
first you can apologize for, the second one you won't really get the
chance. They likely will no longer be listening even if you otherwise
-do a good job.
+do a good job.
We all think we're better than anybody else, which means that when
-somebody else puts on airs, it _really_ rubs us the wrong way. You may
+somebody else puts on airs, it **really** rubs us the wrong way. You may
be morally and intellectually superior to everybody around you, but
-don't try to make it too obvious unless you really _intend_ to irritate
-somebody (*).
+don't try to make it too obvious unless you really **intend** to irritate
+somebody [#f3]_.
Similarly, don't be too polite or subtle about things. Politeness easily
ends up going overboard and hiding the problem, and as they say, "On the
@@ -251,15 +258,16 @@ Some humor can help pad both the bluntness and the moralizing. Going
overboard to the point of being ridiculous can drive a point home
without making it painful to the recipient, who just thinks you're being
silly. It can thus help get through the personal mental block we all
-have about criticism.
+have about criticism.
-(*) Hint: internet newsgroups that are not directly related to your work
-are great ways to take out your frustrations at other people. Write
-insulting posts with a sneer just to get into a good flame every once in
-a while, and you'll feel cleansed. Just don't crap too close to home.
+.. [#f3] Hint: internet newsgroups that are not directly related to your work
+ are great ways to take out your frustrations at other people. Write
+ insulting posts with a sneer just to get into a good flame every once in
+ a while, and you'll feel cleansed. Just don't crap too close to home.
- Chapter 6: Why me?
+Why me?
+-------
Since your main responsibility seems to be to take the blame for other
peoples mistakes, and make it painfully obvious to everybody else that
@@ -268,9 +276,9 @@ first place?
First off, while you may or may not get screaming teenage girls (or
boys, let's not be judgmental or sexist here) knocking on your dressing
-room door, you _will_ get an immense feeling of personal accomplishment
+room door, you **will** get an immense feeling of personal accomplishment
for being "in charge". Never mind the fact that you're really leading
by trying to keep up with everybody else and running after them as fast
-as you can. Everybody will still think you're the person in charge.
+as you can. Everybody will still think you're the person in charge.
It's a great job if you can hack it.
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-14 13:20 +0200 |
| Subject | [PATCH v3 07/21] Documentation/CodingStyle: Convert to ReST markup |
| Message-ID | <shgoq-ao-49@gated-at.bofh.it> |
| In reply to | #1483201 |
- Fix all chapter identation;
- add c blocks where needed;
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/CodingStyle | 253 ++++++++++++++++++++++++++++++++++------------
1 file changed, 187 insertions(+), 66 deletions(-)
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index 0f1dbd87eb48..4e65f1eaedca 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -1,5 +1,6 @@
- Linux kernel coding style
+Linux kernel coding style
+=========================
This is a short document describing the preferred coding style for the
linux kernel. Coding style is very personal, and I won't _force_ my
@@ -13,7 +14,8 @@ and NOT read it. Burn them, it's a great symbolic gesture.
Anyway, here goes:
- Chapter 1: Indentation
+Indentation
+-----------
Tabs are 8 characters, and thus indentations are also 8 characters.
There are heretic movements that try to make indentations 4 (or even 2!)
@@ -39,6 +41,8 @@ The preferred way to ease multiple indentation levels in a switch statement is
to align the "switch" and its subordinate "case" labels in the same column
instead of "double-indenting" the "case" labels. E.g.:
+.. code-block:: c
+
switch (suffix) {
case 'G':
case 'g':
@@ -59,6 +63,8 @@ instead of "double-indenting" the "case" labels. E.g.:
Don't put multiple statements on a single line unless you have
something to hide:
+.. code-block:: c
+
if (condition) do_this;
do_something_everytime;
@@ -71,7 +77,8 @@ used for indentation, and the above example is deliberately broken.
Get a decent editor and don't leave whitespace at the end of lines.
- Chapter 2: Breaking long lines and strings
+Breaking long lines and strings
+-------------------------------
Coding style is all about readability and maintainability using commonly
available tools.
@@ -87,7 +94,8 @@ with a long argument list. However, never break user-visible strings such as
printk messages, because that breaks the ability to grep for them.
- Chapter 3: Placing Braces and Spaces
+Placing Braces and Spaces
+-------------------------
The other issue that always comes up in C styling is the placement of
braces. Unlike the indent size, there are few technical reasons to
@@ -95,6 +103,8 @@ choose one placement strategy over the other, but the preferred way, as
shown to us by the prophets Kernighan and Ritchie, is to put the opening
brace last on the line, and put the closing brace first, thusly:
+.. code-block:: c
+
if (x is true) {
we do y
}
@@ -102,6 +112,8 @@ brace last on the line, and put the closing brace first, thusly:
This applies to all non-function statement blocks (if, switch, for,
while, do). E.g.:
+.. code-block:: c
+
switch (action) {
case KOBJ_ADD:
return "add";
@@ -116,6 +128,8 @@ while, do). E.g.:
However, there is one special case, namely functions: they have the
opening brace at the beginning of the next line, thus:
+.. code-block:: c
+
int function(int x)
{
body of function
@@ -131,12 +145,16 @@ the cases where it is followed by a continuation of the same statement,
ie a "while" in a do-statement or an "else" in an if-statement, like
this:
+.. code-block:: c
+
do {
body of do-loop
} while (condition);
and
+.. code-block:: c
+
if (x == y) {
..
} else if (x > y) {
@@ -155,11 +173,15 @@ comments on.
Do not unnecessarily use braces where a single statement will do.
+.. code-block:: c
+
if (condition)
action();
and
+.. code-block:: none
+
if (condition)
do_this();
else
@@ -168,6 +190,8 @@ and
This does not apply if only one branch of a conditional statement is a single
statement; in the latter case use braces in both branches:
+.. code-block:: c
+
if (condition) {
do_this();
do_that();
@@ -175,32 +199,44 @@ statement; in the latter case use braces in both branches:
otherwise();
}
- 3.1: Spaces
+Spaces
+******
Linux kernel style for use of spaces depends (mostly) on
function-versus-keyword usage. Use a space after (most) keywords. The
notable exceptions are sizeof, typeof, alignof, and __attribute__, which look
somewhat like functions (and are usually used with parentheses in Linux,
-although they are not required in the language, as in: "sizeof info" after
-"struct fileinfo info;" is declared).
+although they are not required in the language, as in: ``sizeof info`` after
+``struct fileinfo info;`` is declared).
So use a space after these keywords:
+::
+
if, switch, case, for, do, while
but not with sizeof, typeof, alignof, or __attribute__. E.g.,
+.. code-block:: c
+
+
s = sizeof(struct file);
Do not add spaces around (inside) parenthesized expressions. This example is
-*bad*:
+**bad**:
+
+.. code-block:: c
+
s = sizeof( struct file );
When declaring pointer data or a function that returns a pointer type, the
-preferred use of '*' is adjacent to the data name or function name and not
+preferred use of '\*' is adjacent to the data name or function name and not
adjacent to the type name. Examples:
+.. code-block:: c
+
+
char *linux_banner;
unsigned long long memparse(char *ptr, char **retptr);
char *match_strdup(substring_t *s);
@@ -208,18 +244,26 @@ adjacent to the type name. Examples:
Use one space around (on each side of) most binary and ternary operators,
such as any of these:
+::
+
= + - < > * / % | & ^ <= >= == != ? :
but no space after unary operators:
+::
+
& * + - ~ ! sizeof typeof alignof __attribute__ defined
no space before the postfix increment & decrement unary operators:
+::
+
++ --
no space after the prefix increment & decrement unary operators:
+::
+
++ --
and no space around the '.' and "->" structure member operators.
@@ -237,7 +281,8 @@ of patches, this may make later patches in the series fail by changing their
context lines.
- Chapter 4: Naming
+Naming
+------
C is a Spartan language, and so should your naming be. Unlike Modula-2
and Pascal programmers, C programmers do not use cute names like
@@ -270,16 +315,22 @@ problem, which is called the function-growth-hormone-imbalance syndrome.
See chapter 6 (Functions).
- Chapter 5: Typedefs
+Typedefs
+--------
Please don't use things like "vps_t".
It's a _mistake_ to use typedef for structures and pointers. When you see a
+.. code-block:: c
+
+
vps_t a;
in the source, what does it mean?
In contrast, if it says
+.. code-block:: c
+
struct virtual_container *a;
you can actually tell what "a" is.
@@ -344,7 +395,8 @@ In general, a pointer, or a struct that has elements that can reasonably
be directly accessed should _never_ be a typedef.
- Chapter 6: Functions
+Functions
+---------
Functions should be short and sweet, and do just one thing. They should
fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
@@ -372,8 +424,10 @@ and it gets confused. You know you're brilliant, but maybe you'd like
to understand what you did 2 weeks from now.
In source files, separate functions with one blank line. If the function is
-exported, the EXPORT* macro for it should follow immediately after the closing
-function brace line. E.g.:
+exported, the **EXPORT** macro for it should follow immediately after the
+closing function brace line. E.g.:
+
+.. code-block:: c
int system_is_up(void)
{
@@ -386,7 +440,8 @@ Although this is not required by the C language, it is preferred in Linux
because it is a simple way to add valuable information for the reader.
- Chapter 7: Centralized exiting of functions
+Centralized exiting of functions
+--------------------------------
Albeit deprecated by some people, the equivalent of the goto statement is
used frequently by compilers in form of the unconditional jump instruction.
@@ -409,9 +464,11 @@ The rationale for using gotos is:
- unconditional statements are easier to understand and follow
- nesting is reduced
- errors by not updating individual exit points when making
- modifications are prevented
+ modifications are prevented
- saves the compiler work to optimize redundant code away ;)
+.. code-block:: c
+
int fun(int a)
{
int result = 0;
@@ -436,6 +493,8 @@ The rationale for using gotos is:
A common type of bug to be aware of is "one err bugs" which look like this:
+.. code-block:: c
+
err:
kfree(foo->bar);
kfree(foo);
@@ -445,6 +504,8 @@ The bug in this code is that on some exit paths "foo" is NULL. Normally the
fix for this is to split it up into two error labels "err_free_bar:" and
"err_free_foo:":
+.. code-block:: c
+
err_free_bar:
kfree(foo->bar);
err_free_foo:
@@ -454,7 +515,8 @@ fix for this is to split it up into two error labels "err_free_bar:" and
Ideally you should simulate errors to test all exit paths.
- Chapter 8: Commenting
+Commenting
+----------
Comments are good, but there is also a danger of over-commenting. NEVER
try to explain HOW your code works in a comment: it's much better to
@@ -476,6 +538,8 @@ for details.
The preferred style for long (multi-line) comments is:
+.. code-block:: c
+
/*
* This is the preferred style for multi-line
* comments in the Linux kernel source code.
@@ -488,6 +552,8 @@ The preferred style for long (multi-line) comments is:
For files in net/ and drivers/net/ the preferred style for long (multi-line)
comments is a little different.
+.. code-block:: c
+
/* The preferred comment style for files in net/ and drivers/net
* looks like this.
*
@@ -501,7 +567,8 @@ multiple data declarations). This leaves you room for a small comment on each
item, explaining its use.
- Chapter 9: You've made a mess of it
+You've made a mess of it
+------------------------
That's OK, we all do. You've probably been told by your long-time Unix
user helper that "GNU emacs" automatically formats the C sources for
@@ -513,38 +580,40 @@ make a good program).
So, you can either get rid of GNU emacs, or change it to use saner
values. To do the latter, you can stick the following in your .emacs file:
-(defun c-lineup-arglist-tabs-only (ignored)
- "Line up argument lists by tabs, not spaces"
- (let* ((anchor (c-langelem-pos c-syntactic-element))
- (column (c-langelem-2nd-pos c-syntactic-element))
- (offset (- (1+ column) anchor))
- (steps (floor offset c-basic-offset)))
- (* (max steps 1)
- c-basic-offset)))
+.. code-block:: none
-(add-hook 'c-mode-common-hook
- (lambda ()
- ;; Add kernel style
- (c-add-style
- "linux-tabs-only"
- '("linux" (c-offsets-alist
- (arglist-cont-nonempty
- c-lineup-gcc-asm-reg
- c-lineup-arglist-tabs-only))))))
+ (defun c-lineup-arglist-tabs-only (ignored)
+ "Line up argument lists by tabs, not spaces"
+ (let* ((anchor (c-langelem-pos c-syntactic-element))
+ (column (c-langelem-2nd-pos c-syntactic-element))
+ (offset (- (1+ column) anchor))
+ (steps (floor offset c-basic-offset)))
+ (* (max steps 1)
+ c-basic-offset)))
-(add-hook 'c-mode-hook
- (lambda ()
- (let ((filename (buffer-file-name)))
- ;; Enable kernel mode for the appropriate files
- (when (and filename
- (string-match (expand-file-name "~/src/linux-trees")
- filename))
- (setq indent-tabs-mode t)
- (setq show-trailing-whitespace t)
- (c-set-style "linux-tabs-only")))))
+ (add-hook 'c-mode-common-hook
+ (lambda ()
+ ;; Add kernel style
+ (c-add-style
+ "linux-tabs-only"
+ '("linux" (c-offsets-alist
+ (arglist-cont-nonempty
+ c-lineup-gcc-asm-reg
+ c-lineup-arglist-tabs-only))))))
+
+ (add-hook 'c-mode-hook
+ (lambda ()
+ (let ((filename (buffer-file-name)))
+ ;; Enable kernel mode for the appropriate files
+ (when (and filename
+ (string-match (expand-file-name "~/src/linux-trees")
+ filename))
+ (setq indent-tabs-mode t)
+ (setq show-trailing-whitespace t)
+ (c-set-style "linux-tabs-only")))))
This will make emacs go better with the kernel coding style for C
-files below ~/src/linux-trees.
+files below ``~/src/linux-trees``.
But even if you fail in getting emacs to do sane formatting, not
everything is lost: use "indent".
@@ -562,14 +631,17 @@ re-formatting you may want to take a look at the man page. But
remember: "indent" is not a fix for bad programming.
- Chapter 10: Kconfig configuration files
+Kconfig configuration files
+---------------------------
For all of the Kconfig* configuration files throughout the source tree,
the indentation is somewhat different. Lines under a "config" definition
are indented with one tab, while help text is indented an additional two
spaces. Example:
-config AUDIT
+::
+
+ config AUDIT
bool "Auditing support"
depends on NET
help
@@ -581,7 +653,9 @@ config AUDIT
Seriously dangerous features (such as write support for certain
filesystems) should advertise this prominently in their prompt string:
-config ADFS_FS_RW
+::
+
+ config ADFS_FS_RW
bool "ADFS write support (DANGEROUS)"
depends on ADFS_FS
...
@@ -590,7 +664,8 @@ For full documentation on the configuration files, see the file
Documentation/kbuild/kconfig-language.txt.
- Chapter 11: Data structures
+Data structures
+---------------
Data structures that have visibility outside the single-threaded
environment they are created and destroyed in should always have
@@ -621,10 +696,13 @@ Remember: if another thread can find your data structure, and you don't
have a reference count on it, you almost certainly have a bug.
- Chapter 12: Macros, Enums and RTL
+Macros, Enums and RTL
+---------------------
Names of macros defining constants and labels in enums are capitalized.
+.. code-block:: c
+
#define CONSTANT 0x12345
Enums are preferred when defining several related constants.
@@ -636,6 +714,8 @@ Generally, inline functions are preferable to macros resembling functions.
Macros with multiple statements should be enclosed in a do - while block:
+.. code-block:: c
+
#define macrofun(a, b, c) \
do { \
if (a == 5) \
@@ -646,6 +726,8 @@ Things to avoid when using macros:
1) macros that affect control flow:
+.. code-block:: c
+
#define FOO(x) \
do { \
if (blah(x) < 0) \
@@ -657,6 +739,8 @@ function; don't break the internal parsers of those who will read the code.
2) macros that depend on having a local variable with a magic name:
+.. code-block:: c
+
#define FOO(val) bar(index, val)
might look like a good thing, but it's confusing as hell when one reads the
@@ -669,18 +753,22 @@ bite you if somebody e.g. turns FOO into an inline function.
must enclose the expression in parentheses. Beware of similar issues with
macros using parameters.
+.. code-block:: c
+
#define CONSTANT 0x4000
#define CONSTEXP (CONSTANT | 3)
5) namespace collisions when defining local variables in macros resembling
functions:
-#define FOO(x) \
-({ \
- typeof(x) ret; \
- ret = calc_ret(x); \
- (ret); \
-})
+.. code-block:: c
+
+ #define FOO(x) \
+ ({ \
+ typeof(x) ret; \
+ ret = calc_ret(x); \
+ (ret); \
+ })
ret is a common name for a local variable - __foo_ret is less likely
to collide with an existing variable.
@@ -689,7 +777,8 @@ The cpp manual deals with macros exhaustively. The gcc internals manual also
covers RTL which is used frequently with assembly language in the kernel.
- Chapter 13: Printing kernel messages
+Printing kernel messages
+------------------------
Kernel developers like to be seen as literate. Do mind the spelling
of kernel messages to make a good impression. Do not use crippled
@@ -723,7 +812,8 @@ already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be
used.
- Chapter 14: Allocating memory
+Allocating memory
+------------------
The kernel provides the following general purpose memory allocators:
kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
@@ -732,6 +822,8 @@ about them.
The preferred form for passing a size of a struct is the following:
+.. code-block:: c
+
p = kmalloc(sizeof(*p), ...);
The alternative form where struct name is spelled out hurts readability and
@@ -744,17 +836,22 @@ language.
The preferred form for allocating an array is the following:
+.. code-block:: c
+
p = kmalloc_array(n, sizeof(...), ...);
The preferred form for allocating a zeroed array is the following:
+.. code-block:: c
+
p = kcalloc(n, sizeof(...), ...);
Both forms check for overflow on the allocation size n * sizeof(...),
and return NULL if that occurred.
- Chapter 15: The inline disease
+The inline disease
+------------------
There appears to be a common misperception that gcc has a magic "make me
faster" speedup option called "inline". While the use of inlines can be
@@ -781,7 +878,8 @@ appears outweighs the potential value of the hint that tells gcc to do
something it would have done anyway.
- Chapter 16: Function return values and names
+Function return values and names
+--------------------------------
Functions can return values of many different kinds, and one of the
most common is a value indicating whether the function succeeded or
@@ -795,6 +893,8 @@ between integers and booleans then the compiler would find these mistakes
for us... but it doesn't. To help prevent such bugs, always follow this
convention:
+::
+
If the name of a function is an action or an imperative command,
the function should return an error-code integer. If the name
is a predicate, the function should return a "succeeded" boolean.
@@ -815,17 +915,22 @@ result. Typical examples would be functions that return pointers; they use
NULL or the ERR_PTR mechanism to report failure.
- Chapter 17: Don't re-invent the kernel macros
+Don't re-invent the kernel macros
+---------------------------------
The header file include/linux/kernel.h contains a number of macros that
you should use, rather than explicitly coding some variant of them yourself.
For example, if you need to calculate the length of an array, take advantage
of the macro
+.. code-block:: c
+
#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
Similarly, if you need to calculate the size of some structure member, use
+.. code-block:: c
+
#define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
There are also min() and max() macros that do strict type checking if you
@@ -833,16 +938,21 @@ need them. Feel free to peruse that header file to see what else is already
defined that you shouldn't reproduce in your code.
- Chapter 18: Editor modelines and other cruft
+Editor modelines and other cruft
+--------------------------------
Some editors can interpret configuration information embedded in source files,
indicated with special markers. For example, emacs interprets lines marked
like this:
+.. code-block:: c
+
-*- mode: c -*-
Or like this:
+.. code-block:: c
+
/*
Local Variables:
compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
@@ -851,6 +961,8 @@ Or like this:
Vim interprets markers that look like this:
+.. code-block:: c
+
/* vim:set sw=8 noet */
Do not include any of these in source files. People have their own personal
@@ -860,7 +972,8 @@ own custom mode, or may have some other magic method for making indentation
work correctly.
- Chapter 19: Inline assembly
+Inline assembly
+---------------
In architecture-specific code, you may need to use inline assembly to interface
with CPU or platform functionality. Don't hesitate to do so when necessary.
@@ -884,12 +997,15 @@ instructions, put each instruction on a separate line in a separate quoted
string, and end each string except the last with \n\t to properly indent the
next instruction in the assembly output:
+.. code-block:: c
+
asm ("magic %reg1, #42\n\t"
"more_magic %reg2, %reg3"
: /* outputs */ : /* inputs */ : /* clobbers */);
- Chapter 20: Conditional Compilation
+Conditional Compilation
+-----------------------
Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
files; doing so makes code harder to read and logic harder to follow. Instead,
@@ -913,6 +1029,8 @@ unused, delete it.)
Within code, where possible, use the IS_ENABLED macro to convert a Kconfig
symbol into a C boolean expression, and use it in a normal C conditional:
+.. code-block:: c
+
if (IS_ENABLED(CONFIG_SOMETHING)) {
...
}
@@ -928,12 +1046,15 @@ At the end of any non-trivial #if or #ifdef block (more than a few lines),
place a comment after the #endif on the same line, noting the conditional
expression used. For instance:
+.. code-block:: c
+
#ifdef CONFIG_SOMETHING
...
#endif /* CONFIG_SOMETHING */
- Appendix I: References
+Appendix I: References
+----------------------
The C Programming Language, Second Edition
by Brian W. Kernighan and Dennis M. Ritchie.
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Jonathan Corbet <corbet@lwn.net> |
|---|---|
| Date | 2016-09-16 19:20 +0200 |
| Subject | Re: [PATCH v3 07/21] Documentation/CodingStyle: Convert to ReST markup |
| Message-ID | <si4XU-7Hc-33@gated-at.bofh.it> |
| In reply to | #1483204 |
On Wed, 14 Sep 2016 08:06:36 -0300 Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > - Fix all chapter identation; > - add c blocks where needed; Here is where I think we need a bit of a philosophical discussion... > - Chapter 1: Indentation > +Indentation > +----------- You're a fan of having sphinx do the numbering, and I have no problem understanding why. But this will defeat people who say "look in chapter 3 of Documentation/CodingStyle". We're removing a bit of information from the plain-text file and reserving it for the formatted version. If we're really going to do that, we should do it consciously, with the knowledge that there is a cost involved. We'll see this even more with SubmittingPatches, where it is quite common for people to cite the number of the section they think is being violated in any given situation. jon
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-16 22:40 +0200 |
| Subject | Re: [PATCH v3 07/21] Documentation/CodingStyle: Convert to ReST markup |
| Message-ID | <si85r-1i1-15@gated-at.bofh.it> |
| In reply to | #1485192 |
Em Fri, 16 Sep 2016 11:13:14 -0600 Jonathan Corbet <corbet@lwn.net> escreveu: > On Wed, 14 Sep 2016 08:06:36 -0300 > Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > > > - Fix all chapter identation; > > - add c blocks where needed; > > Here is where I think we need a bit of a philosophical discussion... > > > - Chapter 1: Indentation > > +Indentation > > +----------- > > You're a fan of having sphinx do the numbering, and I have no problem > understanding why. But this will defeat people who say "look in chapter 3 > of Documentation/CodingStyle". We're removing a bit of information from > the plain-text file and reserving it for the formatted version. If we're > really going to do that, we should do it consciously, with the knowledge > that there is a cost involved. > > We'll see this even more with SubmittingPatches, where it is quite common > for people to cite the number of the section they think is being violated > in any given situation. I see your point. However, AFAICT, there's no way to disable automatic numbering for LaTeX and PDF formats: it will always generate an index. It is actually worse than that: the numbering for the LaTeX and PDF versions of the document don't match with the numbering for html and ePub, and Sphinx restricts to just one numbered TOC index for the entire document. Currently, I don't know any way to fix it. So, keeping the current numeration there will produce a very messy PDF output, with the two numerations altogether. Thanks, Mauro
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-17 12:00 +0200 |
| Subject | Re: [PATCH v3 07/21] Documentation/CodingStyle: Convert to ReST markup |
| Message-ID | <sikzD-Uw-11@gated-at.bofh.it> |
| In reply to | #1485357 |
Em Fri, 16 Sep 2016 17:34:26 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> escreveu:
> Em Fri, 16 Sep 2016 11:13:14 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
>
> > On Wed, 14 Sep 2016 08:06:36 -0300
> > Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> >
> > > - Fix all chapter identation;
> > > - add c blocks where needed;
> >
> > Here is where I think we need a bit of a philosophical discussion...
> >
> > > - Chapter 1: Indentation
> > > +Indentation
> > > +-----------
> >
> > You're a fan of having sphinx do the numbering, and I have no problem
> > understanding why. But this will defeat people who say "look in chapter 3
> > of Documentation/CodingStyle". We're removing a bit of information from
> > the plain-text file and reserving it for the formatted version. If we're
> > really going to do that, we should do it consciously, with the knowledge
> > that there is a cost involved.
> >
> > We'll see this even more with SubmittingPatches, where it is quite common
> > for people to cite the number of the section they think is being violated
> > in any given situation.
>
> I see your point. However, AFAICT, there's no way to disable automatic
> numbering for LaTeX and PDF formats: it will always generate an index.
>
> It is actually worse than that: the numbering for the LaTeX and PDF
> versions of the document don't match with the numbering for html and ePub,
> and Sphinx restricts to just one numbered TOC index for the entire document.
>
> Currently, I don't know any way to fix it.
>
> So, keeping the current numeration there will produce a very messy
> PDF output, with the two numerations altogether.
I found a way to trick Sphinx LaTeX output... not an elegant one, though.
We can add a tag at development-process/index.rst like:
.. raw:: latex
\renewcommand\thesection{\fnsymbol{section}}
\renewcommand\thesubsection{\thesection.\fnsymbol{subsection}}
To use symbols instead of numbers for chapter numbering, or something
like:
.. raw:: latex
\renewcommand\thesection*
\renewcommand\thesubsection*
To use "*" for both sections and subsections.
That makes it to hide the numbers on the LaTeX output. There's an issue,
though: it will internally keep numbering it.
So, the page feet will still be numbering the chapters/sections like:
Chapter 12. Email clients info for Linux
*. Some email client (MUA) hints
And the chapter will still be numbered like:
CHAPTER
TWELVE
--------------------------------------
EMAIL CLIENTS INFO FOR LINUX
Maybe we could get better results if we do something at the LaTex
preamble, but the preamble is global to *ALL* books that use the same
conf.py.
As we chose to have just one global conf.py for the "normal" output,
IMHO, we should not put book-specific stuff at the latex_elements
preamble.
Also, please notice that this will also affect numeration at the
documents of the development-process.rst sub-book.
One alternative would be:
1) remove the :numbered: from the TOC tree. This will disable
numbering for HTML/ePub outputs;
2) use a \renewcommand just for \thesubsection (as doing it for the
chapter doesn't really work fine);
3) keep the already existing numeration for CodingStyle/SubmitPatches/...
Maybe we could find a way to change the top-level "chapter" numeration
to "part", but, I suspect that such change would need to be done via
LaTeX preamble.
Comments?
PoC patch enclosed.
Thanks,
Mauro
diff --git a/Documentation/development-process/index.rst b/Documentation/development-process/index.rst
index e38f44729a21..92055353a598 100644
--- a/Documentation/development-process/index.rst
+++ b/Documentation/development-process/index.rst
@@ -1,10 +1,17 @@
+.. raw:: latex
+
+ \renewcommand\thesection*
+.. \renewcommand\thesubsection*
+.. \renewcommand\thesection{\fnsymbol{section}}
+.. \renewcommand\thesubsection{\thesection.\fnsymbol{subsection}}
+
+
Linux Kernel Development Documentation
======================================
Contents:
.. toctree::
- :numbered:
:maxdepth: 2
HOWTO
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-14 13:20 +0200 |
| Subject | [PATCH v3 14/21] Documentation/stable_api_nonsense.txt: convert it to ReST markup |
| Message-ID | <shgoq-ao-51@gated-at.bofh.it> |
| In reply to | #1483201 |
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 <mchehab@s-opensource.com>
---
Documentation/stable_api_nonsense.txt | 33 +++++++++++++++++++++++----------
1 file changed, 23 insertions(+), 10 deletions(-)
diff --git a/Documentation/stable_api_nonsense.txt b/Documentation/stable_api_nonsense.txt
index db3be892afb2..0d375c115b0c 100644
--- a/Documentation/stable_api_nonsense.txt
+++ b/Documentation/stable_api_nonsense.txt
@@ -1,17 +1,24 @@
The Linux Kernel Driver Interface
+==================================
+
(all of your questions answered and then some)
Greg Kroah-Hartman <greg@kroah.com>
-This is being written to try to explain why Linux does not have a binary
-kernel interface, nor does it have a stable kernel interface. Please
-realize that this article describes the _in kernel_ interfaces, not the
-kernel to userspace interfaces. The kernel to userspace interface is
-the one that application programs use, the syscall interface. That
-interface is _very_ stable over time, and will not break. I have old
-programs that were built on a pre 0.9something kernel that still work
-just fine on the latest 2.6 kernel release. That interface is the one
-that users and application programmers can count on being stable.
+This is being written to try to explain why Linux **does not have a binary
+kernel interface, nor does it have a stable kernel interface**.
+
+.. note::
+
+ Please realize that this article describes the **in kernel** interfaces, not
+ the kernel to userspace interfaces.
+
+ The kernel to userspace interface is the one that application programs use,
+ the syscall interface. That interface is **very** stable over time, and
+ will not break. I have old programs that were built on a pre 0.9something
+ kernel that still work just fine on the latest 2.6 kernel release.
+ That interface is the one that users and application programmers can count
+ on being stable.
Executive Summary
@@ -51,19 +58,23 @@ Binary Kernel Interface
Assuming that we had a stable kernel source interface for the kernel, a
binary interface would naturally happen too, right? Wrong. Please
consider the following facts about the Linux kernel:
+
- Depending on the version of the C compiler you use, different kernel
data structures will contain different alignment of structures, and
possibly include different functions in different ways (putting
functions inline or not.) The individual function organization
isn't that important, but the different data structure padding is
very important.
+
- Depending on what kernel build options you select, a wide range of
different things can be assumed by the kernel:
+
- different structures can contain different fields
- Some functions may not be implemented at all, (i.e. some locks
compile away to nothing for non-SMP builds.)
- Memory within the kernel can be aligned in different ways,
depending on the build options.
+
- Linux runs on a wide range of different processor architectures.
There is no way that binary drivers from one architecture will run
on another architecture properly.
@@ -105,6 +116,7 @@ As a specific examples of this, the in-kernel USB interfaces have
undergone at least three different reworks over the lifetime of this
subsystem. These reworks were done to address a number of different
issues:
+
- A change from a synchronous model of data streams to an asynchronous
one. This reduced the complexity of a number of drivers and
increased the throughput of all USB drivers such that we are now
@@ -166,6 +178,7 @@ very little effort on your part.
The very good side effects of having your driver in the main kernel tree
are:
+
- The quality of the driver will rise as the maintenance costs (to the
original developer) will decrease.
- Other developers will add features to your driver.
@@ -175,7 +188,7 @@ are:
changes require it.
- The driver automatically gets shipped in all Linux distributions
without having to ask the distros to add it.
-
+
As Linux supports a larger number of different devices "out of the box"
than any other operating system, and it supports these devices on more
different processor architectures than any other operating system, this
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-14 13:20 +0200 |
| Subject | [PATCH v3 06/21] Documentation/Changes: convert it to ReST markup |
| Message-ID | <shgoq-ao-55@gated-at.bofh.it> |
| In reply to | #1483201 |
- 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 happy Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/Changes | 224 ++++++++++++++++++++++++++++++-------------------- 1 file changed, 134 insertions(+), 90 deletions(-) diff --git a/Documentation/Changes b/Documentation/Changes index ec97b77c8b00..a9f365d864c7 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -1,3 +1,6 @@ +Minimal requerements to compile the Kernel +++++++++++++++++++++++++++++++++++++++++++ + Intro ===== @@ -10,9 +13,9 @@ Axel Boldt, Alessandro Sigala, and countless other users all over the 'net). Current Minimal Requirements -============================ +**************************** -Upgrade to at *least* these software revisions before thinking you've +Upgrade to at **least** these software revisions before thinking you've encountered a bug! If you're unsure what version you're currently running, the suggested command should tell you. @@ -21,34 +24,38 @@ running a Linux kernel. Also, not all tools are necessary on all systems; obviously, if you don't have any ISDN hardware, for example, you probably needn't concern yourself with isdn4k-utils. -o GNU C 3.2 # gcc --version -o GNU make 3.80 # make --version -o binutils 2.12 # ld -v -o util-linux 2.10o # fdformat --version -o module-init-tools 0.9.10 # depmod -V -o e2fsprogs 1.41.4 # e2fsck -V -o jfsutils 1.1.3 # fsck.jfs -V -o reiserfsprogs 3.6.3 # reiserfsck -V -o xfsprogs 2.6.0 # xfs_db -V -o squashfs-tools 4.0 # mksquashfs -version -o btrfs-progs 0.18 # btrfsck -o pcmciautils 004 # pccardctl -V -o quota-tools 3.09 # quota -V -o PPP 2.4.0 # pppd --version -o isdn4k-utils 3.1pre1 # isdnctrl 2>&1|grep version -o nfs-utils 1.0.5 # showmount --version -o procps 3.2.0 # ps --version -o oprofile 0.9 # oprofiled --version -o udev 081 # udevd --version -o grub 0.93 # grub --version || grub-install --version -o mcelog 0.6 # mcelog --version -o iptables 1.4.2 # iptables -V -o openssl & libcrypto 1.0.0 # openssl version -o bc 1.06.95 # bc --version +====================== =============== ======================================== + Program Minimal version Command to check the version +====================== =============== ======================================== +GNU C 3.2 gcc --version +GNU make 3.80 make --version +binutils 2.12 ld -v +util-linux 2.10o fdformat --version +module-init-tools 0.9.10 depmod -V +e2fsprogs 1.41.4 e2fsck -V +jfsutils 1.1.3 fsck.jfs -V +reiserfsprogs 3.6.3 reiserfsck -V +xfsprogs 2.6.0 xfs_db -V +squashfs-tools 4.0 mksquashfs -version +btrfs-progs 0.18 btrfsck +pcmciautils 004 pccardctl -V +quota-tools 3.09 quota -V +PPP 2.4.0 pppd --version +isdn4k-utils 3.1pre1 isdnctrl 2>&1|grep version +nfs-utils 1.0.5 showmount --version +procps 3.2.0 ps --version +oprofile 0.9 oprofiled --version +udev 081 udevd --version +grub 0.93 grub --version || grub-install --version +mcelog 0.6 mcelog --version +iptables 1.4.2 iptables -V +openssl & libcrypto 1.0.0 openssl version +bc 1.06.95 bc --version +====================== =============== ======================================== Kernel compilation -================== +****************** GCC --- @@ -64,16 +71,16 @@ You will need GNU make 3.80 or later to build the kernel. Binutils -------- -Linux on IA-32 has recently switched from using as86 to using gas for -assembling the 16-bit boot code, removing the need for as86 to compile +Linux on IA-32 has recently switched from using ``as86`` to using ``gas`` for +assembling the 16-bit boot code, removing the need for ``as86`` to compile your kernel. This change does, however, mean that you need a recent release of binutils. Perl ---- -You will need perl 5 and the following modules: Getopt::Long, Getopt::Std, -File::Basename, and File::Find to build the kernel. +You will need perl 5 and the following modules: ``Getopt::Long``, +``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel. BC -- @@ -93,7 +100,7 @@ and higher. System utilities -================ +**************** Architectural changes --------------------- @@ -115,7 +122,7 @@ well as the desired DocBook stylesheets. Util-linux ---------- -New versions of util-linux provide *fdisk support for larger disks, +New versions of util-linux provide ``fdisk`` support for larger disks, support new options to mount, recognize more supported partition types, have a fdformat which works with 2.4 kernels, and similar goodies. You'll probably want to upgrade. @@ -125,54 +132,57 @@ Ksymoops If the unthinkable happens and your kernel oopses, you may need the ksymoops tool to decode it, but in most cases you don't. -It is generally preferred to build the kernel with CONFIG_KALLSYMS so +It is generally preferred to build the kernel with ``CONFIG_KALLSYMS`` so that it produces readable dumps that can be used as-is (this also produces better output than ksymoops). If for some reason your kernel -is not build with CONFIG_KALLSYMS and you have no way to rebuild and +is not build with ``CONFIG_KALLSYMS`` and you have no way to rebuild and reproduce the Oops with that option, then you can still decode that Oops with ksymoops. Module-Init-Tools ----------------- -A new module loader is now in the kernel that requires module-init-tools +A new module loader is now in the kernel that requires ``module-init-tools`` to use. It is backward compatible with the 2.4.x series kernels. Mkinitrd -------- -These changes to the /lib/modules file tree layout also require that +These changes to the ``/lib/modules`` file tree layout also require that mkinitrd be upgraded. E2fsprogs --------- -The latest version of e2fsprogs fixes several bugs in fsck and +The latest version of ``e2fsprogs`` fixes several bugs in fsck and debugfs. Obviously, it's a good idea to upgrade. JFSutils -------- -The jfsutils package contains the utilities for the file system. +The ``jfsutils`` package contains the utilities for the file system. The following utilities are available: -o fsck.jfs - initiate replay of the transaction log, and check + +- ``fsck.jfs`` - initiate replay of the transaction log, and check and repair a JFS formatted partition. -o mkfs.jfs - create a JFS formatted partition. -o other file system utilities are also available in this package. + +- ``mkfs.jfs`` - create a JFS formatted partition. + +- other file system utilities are also available in this package. Reiserfsprogs ------------- The reiserfsprogs package should be used for reiserfs-3.6.x (Linux kernels 2.4.x). It is a combined package and contains working -versions of mkreiserfs, resize_reiserfs, debugreiserfs and -reiserfsck. These utils work on both i386 and alpha platforms. +versions of ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` and +``reiserfsck``. These utils work on both i386 and alpha platforms. Xfsprogs -------- -The latest version of xfsprogs contains mkfs.xfs, xfs_db, and the -xfs_repair utilities, among others, for the XFS filesystem. It is +The latest version of ``xfsprogs`` contains ``mkfs.xfs``, ``xfs_db``, and the +``xfs_repair`` utilities, among others, for the XFS filesystem. It is architecture independent and any version from 2.0.0 onward should work correctly with this version of the XFS kernel code (2.6.0 or later is recommended, due to some significant improvements). @@ -180,7 +190,7 @@ later is recommended, due to some significant improvements). PCMCIAutils ----------- -PCMCIAutils replaces pcmcia-cs. It properly sets up +PCMCIAutils replaces ``pcmcia-cs``. It properly sets up PCMCIA sockets at system startup and loads the appropriate modules for 16-bit PCMCIA devices if the kernel is modularized and the hotplug subsystem is used. @@ -200,17 +210,20 @@ A driver has been added to allow updating of Intel IA32 microcode, accessible as a normal (misc) character device. If you are not using udev you may need to: -mkdir /dev/cpu -mknod /dev/cpu/microcode c 10 184 -chmod 0644 /dev/cpu/microcode +:: + + mkdir /dev/cpu + mknod /dev/cpu/microcode c 10 184 + chmod 0644 /dev/cpu/microcode as root before you can use this. You'll probably also want to get the user-space microcode_ctl utility to use with this. udev ---- -udev is a userspace application for populating /dev dynamically with -only entries for devices actually present. udev replaces the basic + +``udev`` is a userspace application for populating ``/dev`` dynamically with +only entries for devices actually present. ``udev`` replaces the basic functionality of devfs, while allowing persistent device naming for devices. @@ -218,10 +231,10 @@ FUSE ---- Needs libfuse 2.4.0 or later. Absolute minimum is 2.3.0 but mount -options 'direct_io' and 'kernel_cache' won't work. +options ``direct_io`` and ``kernel_cache`` won't work. Networking -========== +********** General changes --------------- @@ -245,7 +258,9 @@ upgrade pppd to at least 2.4.0. If you are not using udev, you must have the device file /dev/ppp which can be made by: -mknod /dev/ppp c 108 0 +:: + + mknod /dev/ppp c 108 0 as root. @@ -260,23 +275,25 @@ NFS-utils In ancient (2.4 and earlier) kernels, the nfs server needed to know about any client that expected to be able to access files via NFS. This -information would be given to the kernel by "mountd" when the client -mounted the filesystem, or by "exportfs" at system startup. exportfs -would take information about active clients from /var/lib/nfs/rmtab. +information would be given to the kernel by ``mountd`` when the client +mounted the filesystem, or by ``exportfs`` at system startup. exportfs +would take information about active clients from ``/var/lib/nfs/rmtab``. This approach is quite fragile as it depends on rmtab being correct which is not always easy, particularly when trying to implement -fail-over. Even when the system is working well, rmtab suffers from +fail-over. Even when the system is working well, ``rmtab`` suffers from getting lots of old entries that never get removed. With modern kernels we have the option of having the kernel tell mountd when it gets a request from an unknown host, and mountd can give appropriate export information to the kernel. This removes the -dependency on rmtab and means that the kernel only needs to know about +dependency on ``rmtab`` and means that the kernel only needs to know about currently active clients. To enable this new functionality, you need to: +:: + mount -t nfsd nfsd /proc/fs/nfsd before running exportfs or mountd. It is recommended that all NFS @@ -287,8 +304,8 @@ mcelog ------ On x86 kernels the mcelog utility is needed to process and log machine check -events when CONFIG_X86_MCE is enabled. Machine check events are errors reported -by the CPU. Processing them is strongly encouraged. +events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors +reported by the CPU. Processing them is strongly encouraged. Getting updated software ======================== @@ -298,114 +315,141 @@ Kernel compilation gcc --- -o <ftp://ftp.gnu.org/gnu/gcc/> + +- <ftp://ftp.gnu.org/gnu/gcc/> Make ---- -o <ftp://ftp.gnu.org/gnu/make/> + +- <ftp://ftp.gnu.org/gnu/make/> Binutils -------- -o <ftp://ftp.kernel.org/pub/linux/devel/binutils/> + +- <ftp://ftp.kernel.org/pub/linux/devel/binutils/> OpenSSL ------- -o <https://www.openssl.org/> + +- <https://www.openssl.org/> System utilities **************** Util-linux ---------- -o <ftp://ftp.kernel.org/pub/linux/utils/util-linux/> + +- <ftp://ftp.kernel.org/pub/linux/utils/util-linux/> Ksymoops -------- -o <ftp://ftp.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/> + +- <ftp://ftp.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/> Module-Init-Tools ----------------- -o <ftp://ftp.kernel.org/pub/linux/kernel/people/rusty/modules/> + +- <ftp://ftp.kernel.org/pub/linux/kernel/people/rusty/modules/> Mkinitrd -------- -o <https://code.launchpad.net/initrd-tools/main> + +- <https://code.launchpad.net/initrd-tools/main> E2fsprogs --------- -o <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz> + +- <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz> JFSutils -------- -o <http://jfs.sourceforge.net/> + +- <http://jfs.sourceforge.net/> Reiserfsprogs ------------- -o <http://www.kernel.org/pub/linux/utils/fs/reiserfs/> + +- <http://www.kernel.org/pub/linux/utils/fs/reiserfs/> Xfsprogs -------- -o <ftp://oss.sgi.com/projects/xfs/> + +- <ftp://oss.sgi.com/projects/xfs/> Pcmciautils ----------- -o <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/> + +- <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/> Quota-tools ----------- -o <http://sourceforge.net/projects/linuxquota/> +----------- + +- <http://sourceforge.net/projects/linuxquota/> DocBook Stylesheets ------------------- -o <http://sourceforge.net/projects/docbook/files/docbook-dsssl/> + +- <http://sourceforge.net/projects/docbook/files/docbook-dsssl/> XMLTO XSLT Frontend ------------------- -o <http://cyberelk.net/tim/xmlto/> + +- <http://cyberelk.net/tim/xmlto/> Intel P6 microcode ------------------ -o <https://downloadcenter.intel.com/> + +- <https://downloadcenter.intel.com/> udev ---- -o <http://www.freedesktop.org/software/systemd/man/udev.html> + +- <http://www.freedesktop.org/software/systemd/man/udev.html> FUSE ---- -o <http://sourceforge.net/projects/fuse> + +- <http://sourceforge.net/projects/fuse> mcelog ------ -o <http://www.mcelog.org/> + +- <http://www.mcelog.org/> Networking ********** PPP --- -o <ftp://ftp.samba.org/pub/ppp/> + +- <ftp://ftp.samba.org/pub/ppp/> Isdn4k-utils ------------ -o <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/> + +- <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/> NFS-utils --------- -o <http://sourceforge.net/project/showfiles.php?group_id=14> + +- <http://sourceforge.net/project/showfiles.php?group_id=14> Iptables -------- -o <http://www.iptables.org/downloads.html> + +- <http://www.iptables.org/downloads.html> Ip-route2 --------- -o <https://www.kernel.org/pub/linux/utils/net/iproute2/> + +- <https://www.kernel.org/pub/linux/utils/net/iproute2/> OProfile -------- -o <http://oprofile.sf.net/download/> + +- <http://oprofile.sf.net/download/> NFS-Utils --------- -o <http://nfs.sourceforge.net/> + +- <http://nfs.sourceforge.net/> -- 2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Jonathan Corbet <corbet@lwn.net> |
|---|---|
| Date | 2016-09-16 19:20 +0200 |
| Subject | Re: [PATCH v3 11/21] Documentation/kernel-docs.txt: convert it to ReST markup |
| Message-ID | <si4XU-7Hc-13@gated-at.bofh.it> |
| In reply to | #1483201 |
On Wed, 14 Sep 2016 08:06:40 -0300 Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > This one required lots of manual work, for it to be properly > displayed. And, honestly, I wonder if it was worth it. This document contains no entries for any recent documents, many of the links in it are long since dead, and I honestly doubt it has been helpful to anybody. If we keep it should definitely be marked as historical cruft, but I wonder if it's worth even that much effort? Thanks, jon
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-16 22:50 +0200 |
| Subject | Re: [PATCH v3 11/21] Documentation/kernel-docs.txt: convert it to ReST markup |
| Message-ID | <si8f8-1lB-7@gated-at.bofh.it> |
| In reply to | #1485189 |
Em Fri, 16 Sep 2016 11:15:31 -0600 Jonathan Corbet <corbet@lwn.net> escreveu: > On Wed, 14 Sep 2016 08:06:40 -0300 > Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > > > This one required lots of manual work, for it to be properly > > displayed. > > And, honestly, I wonder if it was worth it. This document contains no > entries for any recent documents, Not sure about that. There are a number of patches from 2016 made by Luis de Bethencourt updating several stuff. > many of the links in it are long since > dead, and I honestly doubt it has been helpful to anybody. I tested: all links there point to an existing documentation. Yet, it lacks pointers to more recent printed Kernel books. > If we keep it > should definitely be marked as historical cruft, but I wonder if it's > worth even that much effort? That's a good question. I don't know the answer. At the media book, we keep a bibliography updated as we add new stuff there. I found it to be useful, specially since it mentions some ITU-T specs that the media framework needs, but this is somewhat different than what's there. Maybe we could keep it there for a while and see if people update it. If not, move it to an "historical" archive or remove it as a hole. Thanks, Mauro
[toc] | [prev] | [next] | [standalone]
| From | Jonathan Corbet <corbet@lwn.net> |
|---|---|
| Date | 2016-09-16 23:10 +0200 |
| Subject | Re: [PATCH v3 11/21] Documentation/kernel-docs.txt: convert it to ReST markup |
| Message-ID | <si8yt-1HA-19@gated-at.bofh.it> |
| In reply to | #1485364 |
On Fri, 16 Sep 2016 17:42:19 -0300 Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > > many of the links in it are long since > > dead, and I honestly doubt it has been helpful to anybody. > > I tested: all links there point to an existing documentation. Really? URL: http://plg.uwaterloo.ca/ URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html URL: ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/pcip.ps.gz URL: ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/drivers.ps.gz URL: ftp://ftp.uk.linux.org/pub/linux/sct/fs/jfs/journal-design.ps.gz URL: http://usb.in.tum.de/usbdoc/ URL: http://www.linux-mag.com/1999-05/gear_01.html URL: http://www.moses.uklinux.net/patches/lki.html URL: http://www.edn.com/article/CA46968.html URL: http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/nfsd.html URL: http://kt.earth.li/kernel-traffic/index.html URL: http://edge.kernelnotes.org /* linkspam site */ URL: http://www.tux.org/lkml/ URL: http://slencyclopedia.berlios.de/index.html URL: http://marc.theaimsgroup.com/?l=linux-kernel URL: http://www.cs.helsinki.fi/linux/linux-kernel/ URL: http://www.lib.uaa.alaska.edu/linux-kernel/ Do any of those links work for you? jon
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-16 23:30 +0200 |
| Subject | Re: [PATCH v3 11/21] Documentation/kernel-docs.txt: convert it to ReST markup |
| Message-ID | <si8RP-1P5-3@gated-at.bofh.it> |
| In reply to | #1485374 |
Em Fri, 16 Sep 2016 15:00:09 -0600 Jonathan Corbet <corbet@lwn.net> escreveu: > On Fri, 16 Sep 2016 17:42:19 -0300 > Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > > > > many of the links in it are long since > > > dead, and I honestly doubt it has been helpful to anybody. > > > > I tested: all links there point to an existing documentation. > > Really? > > URL: http://plg.uwaterloo.ca/ > URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html Those worked. > URL: ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/pcip.ps.gz > URL: ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/drivers.ps.gz > URL: ftp://ftp.uk.linux.org/pub/linux/sct/fs/jfs/journal-design.ps.gz > URL: http://usb.in.tum.de/usbdoc/ > URL: http://www.linux-mag.com/1999-05/gear_01.html > URL: http://www.moses.uklinux.net/patches/lki.html > URL: http://www.edn.com/article/CA46968.html > URL: http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/nfsd.html > URL: http://kt.earth.li/kernel-traffic/index.html > URL: http://edge.kernelnotes.org /* linkspam site */ > URL: http://www.tux.org/lkml/ > URL: http://slencyclopedia.berlios.de/index.html > URL: http://marc.theaimsgroup.com/?l=linux-kernel > URL: http://www.cs.helsinki.fi/linux/linux-kernel/ > URL: http://www.lib.uaa.alaska.edu/linux-kernel/ The above didn't. > Do any of those links work for you? Yeah, I looked on my browser history... I didn't checked all links here, just a bunch of them. Sorry for the mess. Feel free to just ignore patch 11, or if you prefer, we can just remove the broken entries. > > jon Thanks, Mauro
[toc] | [prev] | [standalone]
Back to top | Article view | linux.kernel
csiph-web