Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1208356 > unrolled thread

Re: [PATCH v2 1/4] scripts/kernel-doc: Adding cross-reference links to html documentation.

Back to article view | Back to linux.kernel

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  Re: [PATCH v2 1/4] scripts/kernel-doc: Adding cross-reference links  to html documentation. Jonathan Corbet <corbet@lwn.net> - 2015-08-17 06:20 +0200
    Re: [PATCH v2 1/4] scripts/kernel-doc: Adding cross-reference links  to html documentation. Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> - 2015-08-17 15:10 +0200

#1208356 — Re: [PATCH v2 1/4] scripts/kernel-doc: Adding cross-reference links to html documentation.

On Tue, 28 Jul 2015 16:45:15 -0300
Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> wrote:

> Functions, Structs and Parameters definitions on kernel documentation
> are pure cosmetic, it only highlights the element.
> 
> To ease the navigation in the documentation we should use <links> inside
> those tags so readers can easily jump between methods directly.
> 
> This was discussed in 2014[1] and is implemented by getting a list
> of <refentries> from the DocBook XML to generate a database. Then it looks
> for <function>,<structnames> and <paramdef> tags that matches the ones in
> the database. As it only links existent references, no broken links are
> added.

So I had some airplane time today and was able to mess with this some.  I
can't make it break anymore, and it clearly improves the resulting
documentation, so I've applied it to the docs tree for 4.3.

I want to look at the rest of the stuff a bit more and play with it, but
it's hard to imagine why we wouldn't want that as well.  I'm a bit more
leery just because it adds another dependency to the build, even if it's
an optional dependency.  My thinking at the moment is to apply it shortly
after the merge window so it can have a long soak in linux-next before a
4.4 merge; hope that sounds good.

Thanks for doing this work,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [next] | [standalone]

#1208577

On 08/17/2015 01:10 AM, Jonathan Corbet wrote:
> On Tue, 28 Jul 2015 16:45:15 -0300
> Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> wrote:
> 
>> Functions, Structs and Parameters definitions on kernel documentation
>> are pure cosmetic, it only highlights the element.
>>
>> To ease the navigation in the documentation we should use <links> inside
>> those tags so readers can easily jump between methods directly.
>>
>> This was discussed in 2014[1] and is implemented by getting a list
>> of <refentries> from the DocBook XML to generate a database. Then it looks
>> for <function>,<structnames> and <paramdef> tags that matches the ones in
>> the database. As it only links existent references, no broken links are
>> added.
> 
> So I had some airplane time today and was able to mess with this some.  I
> can't make it break anymore, and it clearly improves the resulting
> documentation, so I've applied it to the docs tree for 4.3.
> 
> I want to look at the rest of the stuff a bit more and play with it, but
> it's hard to imagine why we wouldn't want that as well.  I'm a bit more
> leery just because it adds another dependency to the build, even if it's
> an optional dependency.  My thinking at the moment is to apply it shortly

I totally agree about the dependency stuff. I even discussed it with
Daniel Vetter a bit. I started by writing my-very-own-markup-parser to
put alongside kernel-doc to avoid external dependencies, but it gets too
complex too quickly (specially when dealing with tables and multi-line
stuff). It would be a pain to maintain a something like that, and the
world probably doesn't need yet-another-markup-parser, so I decided to
use another tool.

> after the merge window so it can have a long soak in linux-next before a
> 4.4 merge; hope that sounds good.

It does sound good. Thanks!

> 
> Thanks for doing this work,

Glad I could help.


Danilo
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web