| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Date: Mon, 19 Sep 2016 08:07:34 -0300
From: Mauro Carvalho Chehab <mchehab@...pensource.com>
To: Linux Doc Mailing List <linux-doc@...r.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab@...pensource.com>,
Mauro Carvalho Chehab <mchehab@...radead.org>,
Markus Heiser <markus.heiser@...marit.de>,
Jonathan Corbet <corbet@....net>,
Jani Nikula <jani.nikula@...ux.intel.com>,
LKML <linux-kernel@...r.kernel.org>, Greg KH <greg@...ah.com>
Subject: [PATCH v4 00/29] Create a book for Kernel development
That's the 4th version of this series. It also contains a second patch series
with more ReST conversions and documentation improvements.
This patchset merges the content of a second patch series:
[PATCH 00/17] Improve documentation for the development-process
I opted to keep the patch changing the kernel-docs.txt changes
(patch 21/29). The patch is already written and another patch
(patch 22/29) depends on it, because there are references to
this file at Documentation/HOWTO.
It shouldn't be hard to get rid of it, but I'm not sure if worths
the effort. As I commented, people might find useful to update
it to point to more modern documents. If people won't do it,
it can still be removed from the Kernel a the next Kernel version.
Yet, if you prefer, feel free to drop patch 21/29 and replace
by a patch removing kernel-docs.txt, adding my ack.
I also folded all renaming stuff to a single patch (29/29).
Jon,
Please don't merge patch 29/29 as-is, as it requires more discussion.
I opted to not rename development-process there, nor to split it into
per-subsystem changes, as we need to first agree about the approach to
be taken. I opted to keep this at the series to allow people to test the
book generation, on both pdf and html formats.
IMHO, patches 1 to 28 should be OK to merge, as they don't do any
renames. We need to discuss more about patch 29, until we solve
this question:
"Should we rename those well-known documents?"
If the answer is "no":
- should we use symlinks instead?
- can't Sphinx be tricked to build them with their existing names?
If the answer is "yes":
- shoud we create files to replace CheckPatch/SubmitPatches/SubmitDrivers
that would point to the newer location?
Also, as you pointed, some of those files (like SecurityBugs) may fit better
on a "users manual" book.
For such book, we'll likely want to group most of the information at
the /README file, and add other stuff there too, like:
Documentation/kernel-parameters.txt
(perhaps splitting its content per-subystem?)
Also, as SecurityBooks is mentioned at HOWTO, if we put it on a separate
book, we'll need to enable interSphinx extension, in order to generate
cross-references between different documents. This is needed for the PDF
output.
Also, "development-process" is a very big name for a dir. We should likely
shorten it to just "process" or "devel". (and "Documentation/" is another
big name too). Those two big names makes several cross-references to
be bigger than the 80-cols limit, like:
:ref:`Documentation/development-process/SubmittingDrivers.rst <submittingdrivers>`
--
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 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 4 changes:
- Keep chapter numeration on the Documentation/* files (CodingStyle
& friends);
- Use :: on the same line, to improve document reading in plain text;
- Added the contents of a separate patch series:
[PATCH 00/17] Improve documentation for the development-process
Several patches from such series were folded on the ReST conversion
patches.
Ok, this makes this one big, but it helped to keep some sanity, as
all renames could be folded into a single patch at the end of this
series.
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 (29):
doc-rst: add CSS styles for :kbd: and :menuselection:
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/applying-patches.txt: Update the information there
Documentation/Changes: convert it to ReST markup
Documentation/Changes: add minimal requirements for documentation
build
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/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/SubmittingPatches: enrich the Sphinx output
Documentation/kernel-docs.txt: convert it to ReST markup
Documentation/HOWTO: add cross-references to other documents
Documentation/HOWTO: update information about generating documentation
Documentation/HOWTO: improve some markups to make it visually better
Documentation/HOWTO: adjust external link references
Documentation/SubmitChecklist: update kernel-doc task
Documentation/SubmitChecklist: convert it to ReST markup
Documentation/email-clients.txt: convert it to ReST markup
docs-rst: move HOWTO and mentioned documents to development-process/
Documentation/ABI/README | 2 +-
Documentation/BUG-HUNTING | 2 +-
Documentation/DocBook/kernel-hacking.tmpl | 4 +-
Documentation/SubmitChecklist | 109 ---
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} | 32 +-
.../{6.Followthrough => 6.Followthrough.rst} | 14 +-
.../{7.AdvancedTopics => 7.AdvancedTopics.rst} | 13 +-
.../{8.Conclusion => 8.Conclusion.rst} | 8 +-
.../{Changes => development-process/Changes.rst} | 262 ++++---
.../CodingStyle.rst} | 387 ++++++----
.../{HOWTO => development-process/HOWTO.rst} | 156 ++--
.../ManagementStyle.rst} | 154 ++--
.../SecurityBugs.rst} | 8 +
.../development-process/SubmitChecklist.rst | 120 ++++
.../SubmittingDrivers.rst} | 56 +-
.../SubmittingPatches.rst} | 314 ++++----
.../applying-patches.rst} | 427 ++++++-----
Documentation/development-process/conf.py | 10 +
.../development-process/development-process.rst | 29 +
.../email-clients.rst} | 216 +++---
Documentation/development-process/index.rst | 29 +
Documentation/development-process/kernel-docs.rst | 791 +++++++++++++++++++++
.../stable_api_nonsense.rst} | 37 +-
.../stable_kernel_rules.rst} | 110 ++-
.../devicetree/bindings/submitting-patches.txt | 2 +-
Documentation/filesystems/locks.txt | 2 +-
Documentation/hwmon/submitting-patches | 8 +-
Documentation/index.rst | 1 +
Documentation/isdn/README | 2 +-
Documentation/ja_JP/HOWTO | 28 +-
Documentation/ja_JP/SubmitChecklist | 6 +-
Documentation/ja_JP/SubmittingPatches | 18 +-
Documentation/ja_JP/stable_api_nonsense.txt | 4 +-
Documentation/ja_JP/stable_kernel_rules.txt | 6 +-
Documentation/kernel-docs.txt | 731 -------------------
Documentation/kernel-documentation.rst | 2 +
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/sphinx-static/theme_overrides.css | 15 +-
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 | 12 +-
Documentation/zh_CN/email-clients.txt | 4 +-
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 +-
68 files changed, 2544 insertions(+), 1898 deletions(-)
delete mode 100644 Documentation/SubmitChecklist
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} (51%)
rename Documentation/{CodingStyle => development-process/CodingStyle.rst} (78%)
rename Documentation/{HOWTO => development-process/HOWTO.rst} (88%)
rename Documentation/{ManagementStyle => development-process/ManagementStyle.rst} (75%)
rename Documentation/{SecurityBugs => development-process/SecurityBugs.rst} (94%)
create mode 100644 Documentation/development-process/SubmitChecklist.rst
rename Documentation/{SubmittingDrivers => development-process/SubmittingDrivers.rst} (82%)
rename Documentation/{SubmittingPatches => development-process/SubmittingPatches.rst} (78%)
rename Documentation/{applying-patches.txt => development-process/applying-patches.rst} (52%)
create mode 100644 Documentation/development-process/conf.py
create mode 100644 Documentation/development-process/development-process.rst
rename Documentation/{email-clients.txt => development-process/email-clients.rst} (56%)
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} (91%)
rename Documentation/{stable_kernel_rules.txt => development-process/stable_kernel_rules.rst} (64%)
delete mode 100644 Documentation/kernel-docs.txt
--
2.7.4
Powered by blists - more mailing lists