Em Mon, 8 Jan 2024 14:18:55 +0100
Vegard Nossum <vegard.nossum@xxxxxxxxxx> escreveu:
> On 05/01/2024 21:07, Mauro Carvalho Chehab wrote:
> > Em Thu, 4 Jan 2024 17:09:45 +0100
> > Vegard Nossum <vegard.nossum@xxxxxxxxxx> 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
