Re: [PATCH 4/5] Documentation/ABI/README: convert to ReST

[Mauro Carvalho Chehab <mchehab@kernel.org>]

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