Highlighting inline code improves text readability.
Signed-off-by: Federico Vaga <[email protected]>
---
V1 -> V2 use the kernel-doc mecanism to link functions in documents
Documentation/process/botching-up-ioctls.rst | 24 ++++++++++----------
1 file changed, 12 insertions(+), 12 deletions(-)
diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/process/botching-up-ioctls.rst
index 9739b88463a5..088d372ecc3c 100644
--- a/Documentation/process/botching-up-ioctls.rst
+++ b/Documentation/process/botching-up-ioctls.rst
@@ -28,7 +28,7 @@ First the prerequisites. Without these you have already failed, because you
will need to add a 32-bit compat layer:
* Only use fixed sized integers. To avoid conflicts with typedefs in userspace
- the kernel has special types like __u32, __s64. Use them.
+ the kernel has special types like ``__u32``, ``__s64``. Use them.
* Align everything to the natural size and use explicit padding. 32-bit
platforms don't necessarily align 64-bit values to 64-bit boundaries, but
@@ -41,12 +41,12 @@ will need to add a 32-bit compat layer:
structures to the kernel, or if the kernel checks the structure size, which
e.g. the drm core does.
- * Pointers are __u64, cast from/to a uintptr_t on the userspace side and
- from/to a void __user * in the kernel. Try really hard not to delay this
- conversion or worse, fiddle the raw __u64 through your code since that
- diminishes the checking tools like sparse can provide. The macro
- u64_to_user_ptr can be used in the kernel to avoid warnings about integers
- and pointers of different sizes.
+ * Pointers are ``__u64``, cast from/to a ``uintptr_t`` on the userspace side
+ and from/to a ``void __user *`` in the kernel. Try really hard not to delay
+ this conversion or worse, fiddle the raw ``__u64`` through your code since
+ that diminishes the checking tools like sparse can provide. The macro
+ u64_to_user_ptr() can be used in the kernel to avoid warnings about
+ integers and pointers of different sizes.
Basics
@@ -132,8 +132,8 @@ wait for outstanding ones. This is really tricky business; at the moment none of
the ioctls supported by the drm/i915 get this fully right, which means there's
still tons more lessons to learn here.
- * Use CLOCK_MONOTONIC as your reference time, always. It's what alsa, drm and
- v4l use by default nowadays. But let userspace know which timestamps are
+ * Use ``CLOCK_MONOTONIC`` as your reference time, always. It's what alsa, drm
+ and v4l use by default nowadays. But let userspace know which timestamps are
derived from different clock domains like your main system clock (provided
by the kernel) or some independent hardware counter somewhere else. Clocks
will mismatch if you look close enough, but if performance measuring tools
@@ -141,8 +141,8 @@ still tons more lessons to learn here.
get at the raw values of some clocks (e.g. through in-command-stream
performance counter sampling instructions) consider exposing those also.
- * Use __s64 seconds plus __u64 nanoseconds to specify time. It's not the most
- convenient time specification, but it's mostly the standard.
+ * Use ``__s64`` seconds plus ``__u64`` nanoseconds to specify time. It's not
+ the most convenient time specification, but it's mostly the standard.
* Check that input time values are normalized and reject them if not. Note
that the kernel native struct ktime has a signed integer for both seconds
@@ -178,7 +178,7 @@ entails its own little set of pitfalls:
needs to be shared across processes - fd-passing over unix domain sockets
also simplifies lifetime management for userspace.
- * Always have O_CLOEXEC support.
+ * Always have ``O_CLOEXEC`` support.
* Ensure that you have sufficient insulation between different clients. By
default pick a private per-fd namespace which forces any sharing to be done
--
2.30.2
Federico Vaga <[email protected]> writes:
> Highlighting inline code improves text readability.
>
> Signed-off-by: Federico Vaga <[email protected]>
It improves *HTML* text readability; the results for plain text are
... less clear. I think it's better to avoid this kind of extra markup
when we can.
Thanks,
jon
On Wed, Jan 11, 2023 at 03:59:57PM -0700, Jonathan Corbet wrote:
>Federico Vaga <[email protected]> writes:
>
>> Highlighting inline code improves text readability.
>>
>> Signed-off-by: Federico Vaga <[email protected]>
>
>It improves *HTML* text readability; the results for plain text are
>... less clear. I think it's better to avoid this kind of extra markup
>when we can.
Shouldn't we consider higher priority the HTML text? Perhaps I've a biased
opinion. Do you think that plain-text is the favorite way of reading the kernel
documentation?
Let me profit from this point and ask. Are there statistics about the usage of
https://www.kernel.org/doc/html/latest/?
>Thanks,
>
>jon
--
Federico Vaga
Federico Vaga <[email protected]> writes:
> On Wed, Jan 11, 2023 at 03:59:57PM -0700, Jonathan Corbet wrote:
>>Federico Vaga <[email protected]> writes:
>>
>>> Highlighting inline code improves text readability.
>>>
>>> Signed-off-by: Federico Vaga <[email protected]>
>>
>>It improves *HTML* text readability; the results for plain text are
>>... less clear. I think it's better to avoid this kind of extra markup
>>when we can.
>
> Shouldn't we consider higher priority the HTML text? Perhaps I've a biased
> opinion. Do you think that plain-text is the favorite way of reading the kernel
> documentation?
The policy all along has been that we need to prioritize the plain-text
docs. A lot of people do use them, and it is easy to wreck their
readability with markup if sufficient attention isn't paid. HTML output
is great, and we want it to be as good as it can be, but it can't be at
the cost of plain-text readability.
> Let me profit from this point and ask. Are there statistics about the usage of
> https://www.kernel.org/doc/html/latest/?
None that I know of.
Thanks,
jon