[PATCH] docs: Remove literal markup from Documentation/ paths

[Jonathan Corbet]

Jonathan Cameron <Jonathan.Cameron at huawei.com> writes:

> On Fri, 04 Apr 2025 11:37:28 -0400
> Nícolas F. R. A. Prado <nfraprado at collabora.com> wrote:
>
>> Given that the automarkup Sphinx plugin cross-references
>> "Documentation/*.rst" strings in the text to the corresponding
>> documents, surrounding those strings with the literal markup (``) not
>> only adds unnecessary markup in the source files, but actually prevents
>> the automatic cross-referencing to happen (as it doesn't happen in
>> literal blocks).
>> 
>> Remove all the occurrences of the literal markup in
>> "Documentation/*.rst" paths, except when the actual source file is being
>> referred. Also change the surrounding text when needed so it reads well
>> both in the source and the web page (eg. 'see file Doc...' -> 'see
>> Doc...').
>> 
>> Signed-off-by: Nícolas F. R. A. Prado <nfraprado at collabora.com>
>> ---
>>  Documentation/admin-guide/mm/numa_memory_policy.rst       | 2 +-
>>  Documentation/admin-guide/serial-console.rst              | 2 +-
>>  Documentation/driver-api/dmaengine/client.rst             | 2 +-
>>  Documentation/driver-api/nvdimm/security.rst              | 2 +-
>>  Documentation/filesystems/fscrypt.rst                     | 4 ++--
>>  Documentation/iio/adis16475.rst                           | 4 ++--
>>  Documentation/iio/adis16480.rst                           | 4 ++--
>>  Documentation/iio/adis16550.rst                           | 4 ++--
>>  Documentation/iio/adxl380.rst                             | 4 ++--
>
> Split patch up by subsystem would be a good thing here as we may
> get other changes to these docs during the cycle and resulting
> merge conflicts if this all goes in as one patch.

That seems like a way to add a significant amount of pain to a basic
(but indeed useful) cleanup patch like this.  If the relevant
maintainers insist on it then that's how it has to be done, but I bet I
could just take the whole thing through docs with almost no trouble.

jon