Skip to contentSkip to conversation

doc: convert printk-formats.txt to rst

PATCH In review Tobin C. Harding 4 participants 11 messages Dec 7, 2017

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

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
index 3bec49c33bbb..7023bfaec21c 100644
@@ -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
index d5bbe035316d..2f9df634a726 100644
@@ -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
#1 lore raw
Quoted 7 lines

Am 07.12.2017 um 06:49 schrieb Tobin C. Harding <[email protected]>:

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

[...]

Quoted 4 lines

---

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 --

#2 lore raw
Quoted 18 lines · Markus Heiser
Quoted 7 lines

Am 07.12.2017 um 06:49 schrieb Tobin C. Harding <[email protected]>:

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

[...]

Quoted 10 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.

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.

maintainer
#3 lore raw
Quoted 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 MAINTAINERS file:

T: git git://git.lwn.net/linux.git docs-next

jon

#4 lore raw
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 MAINTAINERS file:

T: git git://git.lwn.net/linux.git docs-next

jon

Amateur hour at my house.

thanks Jon,
Tobin

#5 lore raw
In reply to Jonathan Corbet
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 MAINTAINERS file:

T: git git://git.lwn.net/linux.git docs-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.

maintainer
#6 lore raw
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 MAINTAINERS file.

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.git

Using 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

#7 lore raw
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 MAINTAINERS file.

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: git git://git.lwn.net/linux.git docs-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.

#8 lore raw
In reply to Tobin C. Harding
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 MAINTAINERS file:

T: git git://git.lwn.net/linux.git docs-next

Unless 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 MAINTAINERS file.

$ ./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: */

#9 lore raw
In reply to Jonathan Corbet
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 MAINTAINERS file:

T: git git://git.lwn.net/linux.git docs-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.

#10 lore raw
In reply to Markus Heiser
Quoted 18 lines · Markus Heiser
Quoted 7 lines

Am 07.12.2017 um 06:49 schrieb Tobin C. Harding <[email protected]>:

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

[...]

Quoted 10 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.

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.