Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

Mauro Carvalho Chehab
2019-04-23T20:19:44Z

Em Tue, 23 Apr 2019 11:53:49 -0600
Jonathan Corbet <corbet-T1hC0tSOHrs@public.gmane.org> escreveu:

> On Tue, 23 Apr 2019 19:11:58 +0200
> Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:
>

> > Look at crap like this:
> >
> > "The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`,
> > :c:func:`kmem_cache_alloc` and"
> >
> > That should've been written like:
> >
> > "The memory allocations via kmalloc(), vmalloc(), kmem_cache_alloc()
> > and"
>
> Yeah, I get it. That markup generates cross-references, which can be
> seriously useful for readers - we want that. But I do wonder if we
> couldn't do it automatically with just a little bit of scripting work.
> It's not to hard to recognize this_is_a_function(), after all. I'll look
> into that, it would definitely help to remove some gunk from the source
> docs.

While on it, one thing that I noticed on several documents is that
they reference other documents by their names. On this conversion,
I avoided replacing that by a :ref:`` tag or a :doc:`` tag. I only
added cross references on two cases:

- a latex file that got converted to ReST and had such
cross-references already;

- one of the document sets that seemed to be using some other
markup language very close to ReST, but with a different
cross-reference markup. So, I just converted it to use
the syntax that Sphinx would recognize.

Anyway, one of the things that occurred to me is that maybe
some scripting work or a ReST extension could do something to parse
"Documentation/foo" as :doc:`Documentation/foo` without needing to
explicitly use any ReST specific tags.

Thanks,
Mauro