[PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc
On 08/13/2015 08:20 PM, Jonathan Corbet wrote: > On Thu, 13 Aug 2015 20:09:35 -0300 > Danilo Cesar Lemes de Paula wrote: > >> Did you find time to take a look on this? > > No. Just when I thought things couldn't get crazier, my laptop died. > > https://plus.google.com/+JonathanCorbet/posts/FBHp48dPb95 > > What spare time I had has been dedicated to recovering from that in time > to give my talk next week. Those evil machines... =) > >> I understand that there's some discussion behind the curtains regarding >> the markdown support, but the cross-reference-hyperlink patch is also in >> the same patch series. It doesn't change any text in the docbook unless >> there's really a cross-reference link to it. Different from the markdown >> support (when people start to use markdown to write docs it will be hard >> to go back), the cross-link stuff doesn't require/create any change to >> current documentation, it is pretty safe to use. >> >> Would you mind to share your plans about this? > > No behind-the-curtains discussions happening, or, let's say, if there > are, I've not been invited either. I meant the Kernel summit mailing list, but looks like that thread died even before my patches. > > I'd like to get back to the cross-reference stuff. Last I tried, it > failed while building the media docs; have you been able to look at > that? I did, and I didn't find anything. Media API already spits lots of warnings without my patch. I did send those warnings to a file and count them. My patch produces the same amount of warnings as the original branch. I did, however, use a clean build to test that. Daniel Vetter complained that the Documentation was being rebuilt all the time, something wrong with the dependencies. I did fix that in v2. Maybe the errors you got were related to it? > > Longer term, as you may know from the kernel summit discussions, I'd > really like to get rid of a lot of the XML gunk and put in something more > straightforward, be it based on Markdown or something else. Doing that, > however, requires that I find the time to implement something that's > convincingly better. It may happen soon, but I sure can't guarantee it. > > Meanwhile, I think it would be a horrible mistake to delay useful work > because I have a gleam in my eye to do something different one of these > years, so I'll not do that. I fully expect to merge all of the stuff > you've done, I just need to have a good look at it and test it out a > bit. As I said before, I can't promise that for the 4.3 merge window, > but I'll try. > > Apologies, No need to apologize, just wanted to know what was going on. Danilo Cesar
[PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc
On 07/23/2015 05:29 PM, Jonathan Corbet wrote: > On Thu, 23 Jul 2015 15:16:23 -0300 > Danilo Cesar Lemes de Paula wrote: > >> This series add supports for hyperlink cross-references on Docbooks and >> an optional markup syntax for in-source Documentation. > > I like the idea; just be warned that it's likely to be a week or two and > one more ocean crossing before I can take a serious look at this... > > Thanks, Hey, Did you find time to take a look on this? I understand that there's some discussion behind the curtains regarding the markdown support, but the cross-reference-hyperlink patch is also in the same patch series. It doesn't change any text in the docbook unless there's really a cross-reference link to it. Different from the markdown support (when people start to use markdown to write docs it will be hard to go back), the cross-link stuff doesn't require/create any change to current documentation, it is pretty safe to use. Would you mind to share your plans about this? Thanks, Danilo Cesar
[PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc
On Thu, 13 Aug 2015 20:09:35 -0300 Danilo Cesar Lemes de Paula wrote: > Did you find time to take a look on this? No. Just when I thought things couldn't get crazier, my laptop died. https://plus.google.com/+JonathanCorbet/posts/FBHp48dPb95 What spare time I had has been dedicated to recovering from that in time to give my talk next week. > I understand that there's some discussion behind the curtains regarding > the markdown support, but the cross-reference-hyperlink patch is also in > the same patch series. It doesn't change any text in the docbook unless > there's really a cross-reference link to it. Different from the markdown > support (when people start to use markdown to write docs it will be hard > to go back), the cross-link stuff doesn't require/create any change to > current documentation, it is pretty safe to use. > > Would you mind to share your plans about this? No behind-the-curtains discussions happening, or, let's say, if there are, I've not been invited either. I'd like to get back to the cross-reference stuff. Last I tried, it failed while building the media docs; have you been able to look at that? Longer term, as you may know from the kernel summit discussions, I'd really like to get rid of a lot of the XML gunk and put in something more straightforward, be it based on Markdown or something else. Doing that, however, requires that I find the time to implement something that's convincingly better. It may happen soon, but I sure can't guarantee it. Meanwhile, I think it would be a horrible mistake to delay useful work because I have a gleam in my eye to do something different one of these years, so I'll not do that. I fully expect to merge all of the stuff you've done, I just need to have a good look at it and test it out a bit. As I said before, I can't promise that for the 4.3 merge window, but I'll try. Apologies, jon
[PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc
On 07/25/2015 07:20 AM, Stephan Mueller wrote: > Am Donnerstag, 23. Juli 2015, 15:16:23 schrieb Danilo Cesar Lemes de Paula: > > Hi Danilo, > >> This series add supports for hyperlink cross-references on Docbooks and >> an optional markup syntax for in-source Documentation. > > Can you please give an example what you mean with the latter? Sure, take a look on https://people.collabora.com/~danilo/intel/Documentation.MarkDown/DocBook/drm/API-drm-dev-ref.html The words "must" and "any" are emphasised, it's different from the original https://people.collabora.com/~danilo/intel/Documentation.old/DocBook/drm/API-drm-dev-ref.html That page is created from drivers/gpu/drm/drm_drv.c, part of drm_dev_ref Documentation, where the text is "You *must* already own". This is a ridiculous simple example but there are some bullet lists, numbered lists and code example in my patch 4/4. It can also do asciiart and tables. I'm sending a v2 of this patch series later as I have some fixes for it. Danilo Cesar
[PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc
Am Donnerstag, 23. Juli 2015, 15:16:23 schrieb Danilo Cesar Lemes de Paula: Hi Danilo, >This series add supports for hyperlink cross-references on Docbooks and >an optional markup syntax for in-source Documentation. Can you please give an example what you mean with the latter? Thanks for updating the documentation generation. Ciao Stephan
[PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc
On Thu, 23 Jul 2015 15:16:23 -0300 Danilo Cesar Lemes de Paula wrote: > This series add supports for hyperlink cross-references on Docbooks and > an optional markup syntax for in-source Documentation. I like the idea; just be warned that it's likely to be a week or two and one more ocean crossing before I can take a serious look at this... Thanks, jon
[PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc
This series add supports for hyperlink cross-references on Docbooks and an optional markup syntax for in-source Documentation. Danilo Cesar Lemes de Paula (4): scripts/kernel-doc: Adding cross-reference links to html documentation. scripts/kernel-doc: Replacing highlights hash by an array scripts/kernel-doc: Adding infrastructure for markdown support drm/doc: Convert to markdown Documentation/DocBook/Makefile | 68 + Documentation/DocBook/drm.tmpl | 86 drivers/gpu/drm/drm_modeset_lock.c | 14 ++- drivers/gpu/drm/drm_prime.c| 16 ++- drivers/gpu/drm/i915/i915_reg.h| 48 - include/drm/drm_vma_manager.h | 10 +- scripts/docproc.c | 49 ++--- scripts/kernel-doc | 170 ++- scripts/kernel-doc-xml-ref | 198 + 9 files changed, 444 insertions(+), 215 deletions(-) create mode 100755 scripts/kernel-doc-xml-ref -- 2.1.4
