Date:	Wed, 15 Jul 2015 14:11:19 -0300
From:	Danilo Cesar Lemes de Paula <danilo.cesar@...labora.co.uk>
To:	linux-kernel@...r.kernel.org, intel-gfx@...ts.freedesktop.org,
	dri-devel@...ts.freedesktop.org, linux-doc@...r.kernel.org
CC:	Randy Dunlap <rdunlap@...radead.org>, daniel.vetter@...ll.ch,
	Jonathan Corbet <corbet@....net>, daniels@...labora.com
Subject: kernel-doc markdown support

Hey there,

I've been discussing with Daniel Vetter about adding Markdown support to kernel-doc.
There were some discussions about improving documentation flexibility and although there were no
consensus at the time I believe (and I think others might agree) that Markdown is best suit for this job.

First of all, it's already there, it's being used by md-files everywhere and it can add the flexibility we're looking for.
Second, I believe it's a important point, it keeps the current in-source-documentation readable.

I started that by writing my own markdown regex rules to be executed by dohighlight in kernel-doc. They started simple, but they get really complex over time and there's no good
reason to create a yet-another-markdown-parser.

So, my proposal here is to use an external tool to do this job, and my suggestion is pandoc [1], and use it inside kernel-doc.
I know there's some perl libs (pandoc-elements-perl and pandoc-perl) around, but I couldn't get the same results using the first lib and
the second one is not packaged by the main distros. pandoc is almost everywhere.

My plan is to make it optional in the Makefile (if pandoc is installed, use it. Otherwise, you're going to get a lovelly warning and receive a simple documentation without fancy features).
I'm also planning to split the Docbooks between those who are "markdown-ready" and those who aren't. I'm working mostly with the DRM docbook but it works with a good part of the current docbooks without changes (xmlto complains about tags in a few of them)

I do have a few examples for the DRM Documentation:
 - Fixed-width / code examples: [1] with markdown support and without [2] markdown support.
 - bold/string style. [3] "*must*" with markdown support and without [4].
 - List example: [5] a list with markdown support and without [6]
Those examples almost didn't require any change on the current source code (it did require one: A fixed-width text in markdown requires four indent-spaces instead of two).
With this approach we're also getting tables and other elements for free, I did test a few and they work, but there's no source-code example using them to show.

Would like to know the opinion regarding this approach to continue this work.

----------
About the execution approach [7] (still a wip. Only the pandoc call is implemented).

I'm basically using perl's IPC::open3 to call pandoc, sending each kernel-doc comment as the input and getting an output for it.
I'm not a perl expert and not sure if that's the best way to do it so I'm taking suggestions.

Thanks,
Danilo Cesar Lemes de Paula


[1] https://people.collabora.com/~danilo/intel/Documentation.MarkDown/DocBook/drm/API-drm-vma-offset-lock-lookup.html
[2] https://people.collabora.com/~danilo/intel/Documentation.new/DocBook/drm/API-drm-vma-offset-lock-lookup.html

[3] https://people.collabora.com/~danilo/intel/Documentation.MarkDown/DocBook/drm/API-drm-dev-ref.html
[4] https://people.collabora.com/~danilo/intel/Documentation.new/DocBook/drm/API-drm-dev-ref.html

[5] https://people.collabora.com/~danilo/intel/Documentation.MarkDown/DocBook/drm/drm-memory-management.html#idp65510432
[6] https://people.collabora.com/~danilo/intel/Documentation.new/DocBook/drm/drm-memory-management.html#idp64227024

[7] https://people.collabora.com/~danilo/intel/wip.patch

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

Powered by blists - more mailing lists