Em Tue, 23 Apr 2019 11:53:49 -0600 Jonathan Corbet <corbet@xxxxxxx> escreveu: > On Tue, 23 Apr 2019 19:11:58 +0200 > Peter Zijlstra <peterz@xxxxxxxxxxxxx> 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 -- dm-devel mailing list dm-devel@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/dm-devel
