From: Mauro Carvalho Chehab <mchehab@kernel.org>
To: Vegard Nossum <vegard.nossum@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>,
Randy Dunlap <rdunlap@infradead.org>,
Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
Jani Nikula <jani.nikula@linux.intel.com>,
linux-doc@vger.kernel.org, linux-api@vger.kernel.org
Subject: Re: [PATCH 4/5] Documentation/ABI/README: convert to ReST
Date: Wed, 31 Jan 2024 06:42:24 +0100 [thread overview]
Message-ID: <20240131064224.2b7d946d@coco.lan> (raw)
In-Reply-To: <c77c1875-5e32-491a-8abf-502ebe371eb5@oracle.com>
Em Mon, 8 Jan 2024 14:18:55 +0100
Vegard Nossum <vegard.nossum@oracle.com> escreveu:
> On 05/01/2024 21:07, Mauro Carvalho Chehab wrote:
> > Em Thu, 4 Jan 2024 17:09:45 +0100
> > Vegard Nossum <vegard.nossum@oracle.com> escreveu:
> >> +Every file in these directories will contain the following information::
> >> +
> >> + What: Short description of the interface
> >> + Date: Date created
> >> + KernelVersion: Kernel version this feature first showed up in.
> >> + Contact: Primary contact for this interface (may be a mailing list)
> >> + Description: Long description of the interface and how to use it.
> >> + Users: All users of this interface who wish to be notified when
> >> + it changes. This is very important for interfaces in
> >> + the "testing" stage, so that kernel developers can work
> >> + with userspace developers to ensure that things do not
> >> + break in ways that are unacceptable. It is also
> >> + important to get feedback for these interfaces to make
> >> + sure they are working in a proper way and do not need to
> >> + be changed further.
> >
> > My personal preference would be to use:
> >
> > :What:
> >
> > as this produces a better markup.
>
> I would prefer to alter this as little as possible, since it describes
> the literal format of those ABI files, keeping it readable and
> understandable in plain text as well as HTML -- with a single leading
> space this whole block shows up as a code block in the HTML, which I
> think is appropriate when giving an example of a literal file.
Well, you're still not being strict by adding a single space after
the field. That's OK for ReST, but if one uses it as a template, the
extra space will cause problems.
Btw, in the specific case of this code block, there is one alternative
approach: keep it untouched and create a new ReST file on a similar
approach to what it was done at Documentation/core-api/wrappers/, e. g.:
.. SPDX-License-Identifier: GPL-2.0
This is a simple wrapper to bring ABI/README into the RST world.
<snip>
===============================
Linux userspace ABI description
===============================
.. raw:: latex
\footnotesize
.. include:: ../../ABI/README
:literal:
.. raw:: latex
\normalsize
</snip>
While I don't like very much this approach, in this very specific
case, it is justified, at least for the field description.
(Note: the latex part to change the font size may not be needed - it will
depend on how this file will appear at the pdf version)
> >> diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst
> >> index b1bc2d37bd0a..7e6198ab368d 100644
> >> --- a/Documentation/process/submit-checklist.rst
> >> +++ b/Documentation/process/submit-checklist.rst
> >> @@ -85,7 +85,7 @@ and elsewhere regarding submitting Linux kernel patches.
> >> 17) All new module parameters are documented with ``MODULE_PARM_DESC()``
> >>
> >> 18) All new userspace interfaces are documented in ``Documentation/ABI/``.
> >> - See ``Documentation/ABI/README`` for more information.
> >> + See ``Documentation/ABI/README.rst`` for more information.
> >
> > If you're willing to convert to ReST, please remove ``, as this will
> > let automarkup.py to create cross-reference links. Same note for the
> > translations too.
>
> Good point -- Jon, do you want me to resubmit this or can you fix it up?
>
> We could also just run a "treewide" fix for this as a separate patch:
>
> git grep -l '``Documentation/.*\.rst``' 'Documentation/**.rst' \
> | xargs sed -i 's|``\(Documentation[^`*]*\.rst\)``|\1|g'
Doing it globally won't work, as there are a few cases where `` is needed:
- when there are wildcards at the file name, like:
Documentation/driver-api/usb/power-management.rst:covered to some extent (see ``Documentation/power/*.rst`` for more
- when they don't point to the actual docs, like:
Documentation/doc-guide/sphinx.rst:documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
- on some cases, it may require a different approach, or may not
make sense, like here:
Documentation/doc-guide/sphinx.rst:2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``.
(the `Toc tree`_ is already an cross-reference link. So, it OK to keep
``Documentation/index.rst`` to help people reading at the sources)
- when it points, for instance, to ./tools/*/Documentation, as those
are currently outside the scope of the ReST docs. Not sure if we
still have this at the docs
Thanks,
Mauro
next prev parent reply other threads:[~2024-01-31 5:42 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-01-04 16:09 [PATCH 1/5] docs: move admin-guide/sysfs-rules.rst to userspace-api/ Vegard Nossum
2024-01-04 16:09 ` [PATCH 2/5] docs: move admin-guide/abi*.rst " Vegard Nossum
2024-01-04 16:09 ` [PATCH 3/5] docs: userspace-api: use single toctree level Vegard Nossum
2024-01-04 16:09 ` [PATCH 4/5] Documentation/ABI/README: convert to ReST Vegard Nossum
2024-01-05 20:07 ` Mauro Carvalho Chehab
2024-01-08 13:18 ` Vegard Nossum
2024-01-31 5:42 ` Mauro Carvalho Chehab [this message]
2024-01-04 16:09 ` [PATCH 5/5] docs: userspace-api/api: include ABI/README.rst Vegard Nossum
2024-01-05 20:25 ` [PATCH 1/5] docs: move admin-guide/sysfs-rules.rst to userspace-api/ Mauro Carvalho Chehab
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240131064224.2b7d946d@coco.lan \
--to=mchehab@kernel.org \
--cc=corbet@lwn.net \
--cc=gregkh@linuxfoundation.org \
--cc=jani.nikula@linux.intel.com \
--cc=linux-api@vger.kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=rdunlap@infradead.org \
--cc=vegard.nossum@oracle.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).