doc: convert printk-formats.txt to rst
Subsystems (3)
PATCH v2 1/1 doc: convert printk-formats.txt to rst
Documentation/printk-formats.txt is a candidate for conversion to ReStructuredText format. Some effort has already been made to do this conversion even thought the suffix is currently .txt
Changes required to complete conversion
- Move printk-formats.txt to core-api/printk-formats.rst
- Add entry to Documentation/core-api/index.rst
- Remove entry from Documentation/00-INDEX
- Fix minor grammatical errors.
- Order heading adornments as suggested by rst docs.
- Use 'Passed by reference' uniformly.
- Update pointer documentation around %px specifier.
- Fix erroneous double backticks (to commas).
- Simplify documentation for kobject.
- Convert lib/vsnprintf.c function docs to use kernel-docs and include in Documentation/printk-formats.rst
---
v2:
- Revert to use ASCII table.
- Implement (or revert) changes as suggested by Randy Dunlap.
- Change file location to core-api/ (inc required index changes)
- Remove some of the double back ticks.
Last two suggested by Jonathan Corbet.
This patch is quite a bit bigger because of removing the extra double back ticks. It has been already (lightheartedly) observed that I may be making more changes than necessary. The back ticks stuff may incur the same reaction :)
Documentation/00-INDEX | 2 -
Documentation/core-api/index.rst | 1 +
.../printk-formats.rst} | 268 +++++++++++----------
lib/vsprintf.c | 155 +++++-------
4 files changed, 196 insertions(+), 230 deletions(-)
rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (59%)Documentation/00-INDEX +0 -2
@@ -346,8 +346,6 @@ prctl/ - directory with info on the priveledge control subsystem preempt-locking.txt - info on locking under a preemptive kernel. -printk-formats.txt - - how to get printk format specifiers right process/ - how to work with the mainline kernel development process. pps/
Documentation/core-api/index.rst +1 -0
@@ -21,6 +21,7 @@ Core utilities flexible-arrays librs genalloc + printk-formats Interfaces for kernel debugging ===============================
Documentation/core-api/printk-formats.rst renamed from Documentation/printk-formats.txt +141 -127
512 lines not on this page · raw message
lib/vsprintf.c +54 -101
169 lines not on this page · raw message
Signature · 1 line
2.7.4
Quoted 7 lines
Am 07.12.2017 um 06:49 schrieb Tobin C. Harding <[email protected]>:
Documentation/printk-formats.txtis a candidate for conversion to ReStructuredText format. Some effort has already been made to do this conversion even thought the suffix is currently .txt
[...]
Quoted 4 lines
Signed-off-by Tobin C. Harding <[email protected]>---
Quoted 8 lines
v2:
- Revert to use ASCII table.
- Implement (or revert) changes as suggested by Randy Dunlap.
- Change file location to core-api/ (inc required index changes)
- Remove some of the double back ticks.Last two suggested by Jonathan Corbet.
Hm, can't apply v2 on Jon's docs-next .. is the v2 patch on top of your v1?
If so, please take a look at our fabulously ;) documentation ..
https://www.kernel.org/doc/html/latest/process/submitting-patches.html
"""
When you submit or resubmit a patch or patch series, include the complete patch description and justification for it. Don’t just say that this is version N of the patch (series). Don’t expect the subsystem maintainer to refer back to earlier patch versions or referenced URLs to find the patch description and put that into the patch. I.e., the patch (series) and its description should be self-contained. This benefits both the maintainers and reviewers. Some reviewers probably didn’t even receive earlier versions of the patch.
"""
-- Markus --
Quoted 18 lines · Markus Heiser
Quoted 7 lines
Am 07.12.2017 um 06:49 schrieb Tobin C. Harding <[email protected]>:
Documentation/printk-formats.txtis a candidate for conversion to ReStructuredText format. Some effort has already been made to do this conversion even thought the suffix is currently .txt[...]
Quoted 10 lines
Signed-off-by Tobin C. Harding <[email protected]>---
v2:
- Revert to use ASCII table.
- Implement (or revert) changes as suggested by Randy Dunlap.
- Change file location to core-api/ (inc required index changes)
- Remove some of the double back ticks.
Quoted 4 lines
Quoted 2 lines
Last two suggested by Jonathan Corbet.
Hm, can't apply v2 on Jon's docs-next .. is the v2 patch on top of your v1?
My mistake, it applies on top of the mainline
commit: "ae64f9bd1d36 Linux 4.15-rc2""
Where is Jon's tree hosted please, I don't see it on kernel.org
thanks,
Tobin.
Jonathan Corbet
maintainerQuoted 3 lines · On Fri, 8 Dec 2017 07:44:34 +1100 "Tobin C. Harding" <[email protected]> wrote:
Where is Jon's tree hosted please, I don't see it on kernel.org
From the
MAINTAINERSfile:
T: git git://git.lwn.net/linux.git docs-next
jon
Quoted 10 lines · Jonathan Corbet
Quoted 1 line · On Fri, 8 Dec 2017 07:44:34 +1100 "Tobin C. Harding" <[email protected]> wrote:
Where is Jon's tree hosted please, I don't see it on kernel.org
From the
MAINTAINERSfile:T: git
git://git.lwn.net/linux.gitdocs-nextjon
Amateur hour at my house.
thanks Jon,
Tobin
Quoted 8 lines · Jonathan Corbet
Quoted 1 line · On Fri, 8 Dec 2017 07:44:34 +1100 "Tobin C. Harding" <[email protected]> wrote:
Where is Jon's tree hosted please, I don't see it on kernel.org
From the
MAINTAINERSfile:T: git
git://git.lwn.net/linux.gitdocs-next
Unless I'm a proper wombat that entry is not in the mainline MAINTAINERS file.
You have two entries
CAFE CMOS INTEGRATED CAMERA CONTROLLER DRIVER
OMNIVISION OV7670 SENSOR DRIVER
but none for docs?
thanks,
Tobin.
Jonathan Corbet
maintainerQuoted 2 lines · On Fri, 8 Dec 2017 08:21:09 +1100 "Tobin C. Harding" <[email protected]> wrote:
Unless I'm a proper wombat that entry is not in the mainline
MAINTAINERSfile.
Um...from current git...
DOCUMENTATION
M: Jonathan Corbet <[email protected]>
L: [email protected]
S: Maintained
F: Documentation/
F: scripts/kernel-doc
X: Documentation/ABI/
X: Documentation/devicetree/
X: Documentation/acpi
X: Documentation/power
X: Documentation/spi
X: Documentation/media
T: git git://git.lwn.net/linux.git docs-next
I've never called anybody a "wombat" before and don't plan to start now, but...you might want to take another look?
Quoted 9 lines
Adding a remote using the above URL
# Jon's docs tree
[remote "corbet"]
url =git://git.lwn.net/linux.git
fetch = +refs/heads/*:refs/remotes/corbet/* pushurl =no_push
Quoted 5 lines
fails to git fetch, but ping showed me
git://git3.lwn.net/linux.gitUsing that URL, fetched just fine.
$ host git.lwn.net git.lwn.net is an alias for git3.lwn.net.
Either should work just fine (except that git3 will almost certainly break someday). Not sure why you're having trouble there.
jon
Quoted 7 lines · Jonathan Corbet
Quoted 2 lines · On Fri, 8 Dec 2017 08:21:09 +1100 "Tobin C. Harding" <[email protected]> wrote:
Unless I'm a proper wombat that entry is not in the mainline
MAINTAINERSfile.Um...from current git...
Foiled by me automatic Emacs buffer syncing (maggit), who knows what version of MAINTAINERS I was looking at.
Please accept my apologies.
Quoted 14 lines
DOCUMENTATION
M: Jonathan Corbet <[email protected]>
L: [email protected]
S: Maintained
F:Documentation/
F:scripts/kernel-doc
X:Documentation/ABI/
X:Documentation/devicetree/
X:Documentation/acpi
X:Documentation/power
X:Documentation/spi
X:Documentation/media
T: gitgit://git.lwn.net/linux.gitdocs-next
Quoted 2 lines
I've never called anybody a "wombat" before and don't plan to start now, but...you might want to take another look?
It's a totally acceptable term in the Australian vernacular, similar to calling someone a 'goose'. A perfectly pleasant form of abuse :)
thanks,
Tobin.
Quoted 11 lines · Tobin C. Harding
Quoted 8 lines · Jonathan Corbet
Quoted 1 line · On Fri, 8 Dec 2017 07:44:34 +1100 "Tobin C. Harding" <[email protected]> wrote:
Where is Jon's tree hosted please, I don't see it on kernel.org
From the
MAINTAINERSfile:T: git
git://git.lwn.net/linux.gitdocs-nextUnless I'm a proper wombat
You are not proper until you have the cosplay attire.
Quoted 1 line
that entry is not in the mainline
MAINTAINERSfile.
$ ./scripts/get_maintainer.pl --sections -f Documentation/ DOCUMENTATION M: Jonathan Corbet <[email protected]> L: [email protected] S: Maintained F: Documentation/ F: scripts/kernel-doc X: Documentation/ABI/ X: Documentation/devicetree/ X: Documentation/acpi/ X: Documentation/power/ X: Documentation/spi/ X: Documentation/media/ T: git git://git.lwn.net/linux.git docs-next
THE REST
M: Linus Torvalds <[email protected]>
L: [email protected]
Q: http://patchwork.kernel.org/project/LKML/list/
T: git git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
S: Buried alive in reporters
F: *
F: */
Quoted 8 lines · Jonathan Corbet
Quoted 1 line · On Fri, 8 Dec 2017 07:44:34 +1100 "Tobin C. Harding" <[email protected]> wrote:
Where is Jon's tree hosted please, I don't see it on kernel.org
From the
MAINTAINERSfile:T: git
git://git.lwn.net/linux.gitdocs-next
Just in case it is of any use to you Jon
Adding a remote using the above URL
# Jon's docs tree
[remote "corbet"]
url = git://git.lwn.net/linux.git
fetch = +refs/heads/*:refs/remotes/corbet/* pushurl = no_push
fails to git fetch, but ping showed me
git://git3.lwn.net/linux.git
Using that URL, fetched just fine.
thanks,
Tobin.
Quoted 18 lines · Markus Heiser
Quoted 7 lines
Am 07.12.2017 um 06:49 schrieb Tobin C. Harding <[email protected]>:
Documentation/printk-formats.txtis a candidate for conversion to ReStructuredText format. Some effort has already been made to do this conversion even thought the suffix is currently .txt[...]
Quoted 10 lines
Signed-off-by Tobin C. Harding <[email protected]>---
v2:
- Revert to use ASCII table.
- Implement (or revert) changes as suggested by Randy Dunlap.
- Change file location to core-api/ (inc required index changes)
- Remove some of the double back ticks.
Quoted 4 lines
Quoted 2 lines
Last two suggested by Jonathan Corbet.
Hm, can't apply v2 on Jon's docs-next .. is the v2 patch on top of your v1?
Ok, this doesn't apply because of a commit Linus did to lib/vsprintf.c
Not that that matters because it has been pointed out in another thread that the kptr_restrict documentation is incomplete.
Please drop, will amend and re-spin.
thanks,
Tobin.