Em Tue, 23 Apr 2019 11:53:49 -0600 Jonathan Corbet corbet@lwn.net escreveu:
On Tue, 23 Apr 2019 19:11:58 +0200 Peter Zijlstra peterz@infradead.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