Re: [PATCH v2 2/4] scripts/kernel-doc: Replacing highlights hash by an array

[Danilo Cesar Lemes de Paula]

On 17-11-2015 13:29, Mauro Carvalho Chehab wrote:
> Em Tue, 17 Nov 2015 07:44:31 -0700
> Jonathan Corbet  escreveu:
> 
>> On Tue, 17 Nov 2015 08:40:46 -0200
>> Mauro Carvalho Chehab  wrote:
>>
>>> The above causes some versions of perl to fail, as keys expect a
>>> hash argument:
>>>
>>> Execution of .//scripts/kernel-doc aborted due to compilation errors.
>>> Type of arg 1 to keys must be hash (not private array) at 
>>> .//scripts/kernel-doc line 2714, near "@highlights) "
>>>
>>> This is happening at linuxtv.org server, with runs perl version 5.10.1.
>>
>> OK, that's not good.  But I'm not quite sure what to do about it.
>>
>> Perl 5.10.1 is a little over six years old.  Nobody else has complained
>> (yet) about this problem.  So it might be best to "fix" this with a
>> minimum version added to the Changes file.
>>
>> Or maybe we need to revert the patch.
>>
>> So I'm far from a Perl expert, so I have no clue what the minimum version
>> would be if we were to say "5.10.1 is too old."  I don't suppose anybody
>> out there knows?
> 
> I'm also not a Perl expert, and never saw before the usage of "keys" on
> an array. Yet, according with:
>   http://perldoc.perl.org/functions/keys.html
> 
> "in Perl 5.12 or later only, the indices of an array"
> 
> If so, then maybe we could replace:
>   foreach my $k (keys @highlights)
> 
> by a more C style variant, with all versions of perl 5:
>   for (my $k = 0; $k < @highlights; $k++) {
> 
> The enclosed patch should do the trick. I tested it with perl 5.10 and 
> perl 5.22 it worked fine with both versions.

I'm Not a perl guru myself either =/.

But thanks for fixing it Mauro!

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

Re: [PATCH v2 2/4] scripts/kernel-doc: Replacing highlights hash by an array

[Danilo Cesar Lemes de Paula]

On 17-11-2015 13:29, Mauro Carvalho Chehab wrote:
> Em Tue, 17 Nov 2015 07:44:31 -0700
> Jonathan Corbet  escreveu:
> 
>> On Tue, 17 Nov 2015 08:40:46 -0200
>> Mauro Carvalho Chehab  wrote:
>>
>>> The above causes some versions of perl to fail, as keys expect a
>>> hash argument:
>>>
>>> Execution of .//scripts/kernel-doc aborted due to compilation errors.
>>> Type of arg 1 to keys must be hash (not private array) at 
>>> .//scripts/kernel-doc line 2714, near "@highlights) "
>>>
>>> This is happening at linuxtv.org server, with runs perl version 5.10.1.
>>
>> OK, that's not good.  But I'm not quite sure what to do about it.
>>
>> Perl 5.10.1 is a little over six years old.  Nobody else has complained
>> (yet) about this problem.  So it might be best to "fix" this with a
>> minimum version added to the Changes file.
>>
>> Or maybe we need to revert the patch.
>>
>> So I'm far from a Perl expert, so I have no clue what the minimum version
>> would be if we were to say "5.10.1 is too old."  I don't suppose anybody
>> out there knows?
> 
> I'm also not a Perl expert, and never saw before the usage of "keys" on
> an array. Yet, according with:
>   http://perldoc.perl.org/functions/keys.html
> 
> "in Perl 5.12 or later only, the indices of an array"
> 
> If so, then maybe we could replace:
>   foreach my $k (keys @highlights)
> 
> by a more C style variant, with all versions of perl 5:
>   for (my $k = 0; $k < @highlights; $k++) {
> 
> The enclosed patch should do the trick. I tested it with perl 5.10 and 
> perl 5.22 it worked fine with both versions.

I'm Not a perl guru myself either =/.

But thanks for fixing it Mauro!

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

Re: [PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements

[Danilo Cesar Lemes de Paula]

On 09/13/2015 05:58 PM, Daniel Vetter wrote:
> On Sun, Sep 13, 2015 at 9:13 PM, Jonathan Corbet  wrote:
>> On Sun, 13 Sep 2015 12:36:07 +0200
>> Daniel Vetter  wrote:
>>
>>> Personally I don't care which kind of text markup we pick and wich
>>> converter, as long as the project looks reasonable far away from
>>> immeninent death (way too many one-person projects on github in this
>>> area).

I wouldn't care either. I choose pandoc as it's old, kind of stable and
has a decent community around it, so it won't probably die due the lack
of interested developers.

That said, cmark is not a option (at least for now). With the current
approach we need a tool capable of reading markdown text and output
DocBook tags, as we're actually still using docbook to spit all kinds of
Documentation formats (html, man, pdf). Looks like cmark can only do
markdown->html.

I did look into other options though, but they were all mostly one-man
job. But yeah, basically any tool capable of converting
markdown->docbook will work. I'm always listening to suggestions =)


>>>
>>> But if we have this discussion I'd like to decouple it from the other
>>> kerneldoc improvemnts in this series (patches 1, 5 and 6). If we cant
>>> agree on the text markup then drm docs will simply look a bit funny for
>>> everyone else. But if the inline struct stuff won't happen 0-day will
>>> scream around (and there's already patches which use the new layout).
>>
>> Those patches are:
>>
>> 1)  scripts/kernel-doc: Replacing highlights hash by an array
>> 5)  scripts/kernel-doc: Improve Markdown results
>> 6)  scripts/kernel-doc: Processing -nofunc for functions only
>>
>> #1 is fine, I'll merge that today.  #6 is already merged.  #5 is a markdown
>> patch, though, and doesn't make sense without the others?  Are you thinking
>> about #3 (drm/doc: Convert to markdown)?  That one would almost work (it
>> depends on #2 currently) and it nicely shows *why* I'd like to get away from
>> XML...

#5 is the DRM markdown conversion, which depends on #2 and #4. So if a
decision about this is going during KS, we need to hold those three patches.

> 
> Sorry I mixed things up, #5 is ok to leave out. I thought about
> "scripts/kernel-doc Allow struct arguments documentation in struct
> body" but you already merged that one for 4.2. Which I missed, but
> which is great since that's the one that would cause the big
> conflicts.
> 
 2 We're constructing an increasingly complicated document-processing
   mechanism with a lot of independently moving parts.  What if we
   converted the whole document to markdown and dispensed with the XML
   part altogether?  Making the source files simpler and dispensing with
   the xmlto requirement would be a big win, IMO.
>>>
>>> Who's going to convert the almost 30kloc of xml template (which often have
>>> large amounts of texts) and the over 60k kerneldoc comments that we have
>>> already?
>>
>> I thought you'd do that :)
>>
>> Seriously, though, a change would be a big job.  There's a reason I've said
>> several times that it would make no sense to delay the work at hand in the
>> hopes of somebody doing this whole job instead.  But we can certainly
>> ponder what might be better.
>>
>> Getting rid of the XML stuff may well simplify the whole process and make
>> the documentation much more accessible for those who would change it; that
>> could be a goal worth going for.  Oh, and anything requiring changes to the
>> kerneldoc comments is going nowhere, that was never something I'd
>> contemplated.  Those comments are fine.
> 
> Well my goal is to be able to have all the programmer docs in the
> code, including any high-level overview sections to tie everything
> together (hence hyperlinks and better formatting). But then you still
> need some skeleton to make a coherent whole out of all the parts, and
> I think the docbook xml templates we have serve rather fine for that
> role. Writing text in xml is indeed horrid, but if we can create
> in-line DOC: sections with decent formatting there's really no need
> for that. From that angle this work here already has the goal to get
> rid of the xml - I plane to move all the existing text in the drm.tmpl
> xml into inline DOC: kerneldoc commets.
> 
> And at least gtkdoc (which we use extensively for the userpace
> test/tools repo) relies on some xml thing to tie different topics
> together too. So that seems pretty standard.
> 
>> But any such change needs a lot of thought and a reasonable proof of
>> concept.  Meanwhile we have work that can make the docs better now, and I
>> want to merge it.  But we should choose the tools we use carefully, and I
>> anticipate a lot of opposition to one that has to drag in 70 Haskell
>> packages with it.
> 
> Well personally I don't care about the exact tooling, as long as:
> - it's a reasonable alive project
> - packages available on distros (works for me on both debian and fedora)
> - we can muck around with how things are integrated 

Re: [PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements

[Danilo Cesar Lemes de Paula]

On 09/13/2015 05:58 PM, Daniel Vetter wrote:
> On Sun, Sep 13, 2015 at 9:13 PM, Jonathan Corbet  wrote:
>> On Sun, 13 Sep 2015 12:36:07 +0200
>> Daniel Vetter  wrote:
>>
>>> Personally I don't care which kind of text markup we pick and wich
>>> converter, as long as the project looks reasonable far away from
>>> immeninent death (way too many one-person projects on github in this
>>> area).

I wouldn't care either. I choose pandoc as it's old, kind of stable and
has a decent community around it, so it won't probably die due the lack
of interested developers.

That said, cmark is not a option (at least for now). With the current
approach we need a tool capable of reading markdown text and output
DocBook tags, as we're actually still using docbook to spit all kinds of
Documentation formats (html, man, pdf). Looks like cmark can only do
markdown->html.

I did look into other options though, but they were all mostly one-man
job. But yeah, basically any tool capable of converting
markdown->docbook will work. I'm always listening to suggestions =)


>>>
>>> But if we have this discussion I'd like to decouple it from the other
>>> kerneldoc improvemnts in this series (patches 1, 5 and 6). If we cant
>>> agree on the text markup then drm docs will simply look a bit funny for
>>> everyone else. But if the inline struct stuff won't happen 0-day will
>>> scream around (and there's already patches which use the new layout).
>>
>> Those patches are:
>>
>> 1)  scripts/kernel-doc: Replacing highlights hash by an array
>> 5)  scripts/kernel-doc: Improve Markdown results
>> 6)  scripts/kernel-doc: Processing -nofunc for functions only
>>
>> #1 is fine, I'll merge that today.  #6 is already merged.  #5 is a markdown
>> patch, though, and doesn't make sense without the others?  Are you thinking
>> about #3 (drm/doc: Convert to markdown)?  That one would almost work (it
>> depends on #2 currently) and it nicely shows *why* I'd like to get away from
>> XML...

#5 is the DRM markdown conversion, which depends on #2 and #4. So if a
decision about this is going during KS, we need to hold those three patches.

> 
> Sorry I mixed things up, #5 is ok to leave out. I thought about
> "scripts/kernel-doc Allow struct arguments documentation in struct
> body" but you already merged that one for 4.2. Which I missed, but
> which is great since that's the one that would cause the big
> conflicts.
> 
 2 We're constructing an increasingly complicated document-processing
   mechanism with a lot of independently moving parts.  What if we
   converted the whole document to markdown and dispensed with the XML
   part altogether?  Making the source files simpler and dispensing with
   the xmlto requirement would be a big win, IMO.
>>>
>>> Who's going to convert the almost 30kloc of xml template (which often have
>>> large amounts of texts) and the over 60k kerneldoc comments that we have
>>> already?
>>
>> I thought you'd do that :)
>>
>> Seriously, though, a change would be a big job.  There's a reason I've said
>> several times that it would make no sense to delay the work at hand in the
>> hopes of somebody doing this whole job instead.  But we can certainly
>> ponder what might be better.
>>
>> Getting rid of the XML stuff may well simplify the whole process and make
>> the documentation much more accessible for those who would change it; that
>> could be a goal worth going for.  Oh, and anything requiring changes to the
>> kerneldoc comments is going nowhere, that was never something I'd
>> contemplated.  Those comments are fine.
> 
> Well my goal is to be able to have all the programmer docs in the
> code, including any high-level overview sections to tie everything
> together (hence hyperlinks and better formatting). But then you still
> need some skeleton to make a coherent whole out of all the parts, and
> I think the docbook xml templates we have serve rather fine for that
> role. Writing text in xml is indeed horrid, but if we can create
> in-line DOC: sections with decent formatting there's really no need
> for that. From that angle this work here already has the goal to get
> rid of the xml - I plane to move all the existing text in the drm.tmpl
> xml into inline DOC: kerneldoc commets.
> 
> And at least gtkdoc (which we use extensively for the userpace
> test/tools repo) relies on some xml thing to tie different topics
> together too. So that seems pretty standard.
> 
>> But any such change needs a lot of thought and a reasonable proof of
>> concept.  Meanwhile we have work that can make the docs better now, and I
>> want to merge it.  But we should choose the tools we use carefully, and I
>> anticipate a lot of opposition to one that has to drag in 70 Haskell
>> packages with it.
> 
> Well personally I don't care about the exact tooling, as long as:
> - it's a reasonable alive project
> - packages available on distros (works for me on both debian and fedora)
> - we can muck 

Re: [PATCH] scripts/kernel-doc: Improve Markdown results

[Danilo Cesar Lemes de Paula]

On 09/04/2015 05:39 PM, Jonathan Corbet wrote:
> On Fri, 4 Sep 2015 14:53:34 -0300
> Danilo Cesar Lemes de Paula  wrote:
> 
>> In the last few days I sent three features:
>> Markdown support (patch series 1)
>> Cross-reference hyperlink support (patch series 1)
>> in-struct-body documentation (series 2)
>>
>> I assume you want a new patch series for the series 1, containing the
>> feature itself and the fixes that I sent later, correct?
> 
> The cross-reference patch was merged, so there's no need to send that
> again.  Anything else that isn't in mainline now should be resent as a
> new series.

I did send a new set, named "[PATCH 0/6] scripts/kernel-doc: Kernel-doc
improvements"
I did include all the patches I didn't find in mainline.
Is it enough?

Thanks,

Danilo


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

[PATCH 5/6] scripts/kernel-doc: Improve Markdown results

[Danilo Cesar Lemes de Paula]

Using pandoc as the Markdown engine cause some minor side effects as
pandoc includes  main  tags for almost everything.
Original Markdown support approach removes those main tags, but it caused
some inconsistencies when that tag is not the main one, like:
..
...

As kernel-doc was already including a  tag, it causes the presence
of double  tags (), which is not supported by DocBook
spec.

Html target gets away with it, so it causes no harm, although other
targets might not be so lucky (pdf as example).

We're now delegating the inclusion of the main  tag to pandoc
only, as it knows when it's necessary or not.

That behavior causes a corner case, the only situation where we're
certainly that  is not needed, which is the  content.
For those cases, we're using a $output_markdown_nopara = 1 control var.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
Cc: Graham Whaley 
---
 scripts/kernel-doc | 48 ++--
 1 file changed, 34 insertions(+), 14 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 5fe572a..d6129e7 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -288,6 +288,7 @@ my $use_markdown = 0;
 my $verbose = 0;
 my $output_mode = "man";
 my $output_preformatted = 0;
+my $output_markdown_nopara = 0;
 my $no_doc_sections = 0;
 my @highlights = @highlights_man;
 my $blankline = $blankline_man;
@@ -538,8 +539,11 @@ sub markdown_to_docbook {
close(CHLD_OUT);
close(CHLD_ERR);
 
-   # pandoc insists in adding Main , we should remove them.
-   $content =~ s:\A\s*\s*\n(.*)\n\Z$:$1:egsm;
+   if ($output_markdown_nopara) {
+   # pandoc insists in adding Main , sometimes we
+   # want to remove them.
+   $content =~ s:\A\s*\s*\n(.*)\n\Z$:$1:egsm;
+   }
 
return $content;
 }
@@ -614,7 +618,7 @@ sub output_highlight {
$line =~ s/^\s*//;
}
if ($line eq ""){
-   if (! $output_preformatted) {
+   if (! $output_preformatted && ! $use_markdown) {
print $lineprefix, local_unescape($blankline);
}
} else {
@@ -1035,7 +1039,7 @@ sub output_section_xml(%) {
# programlisting is already included by pandoc
print "\n" unless $use_markdown;
$output_preformatted = 1;
-   } else {
+   } elsif (! $use_markdown) {
print "\n";
}
output_highlight($args{'sections'}{$section});
@@ -1043,7 +1047,7 @@ sub output_section_xml(%) {
if ($section =~ m/EXAMPLE/i) {
print "\n" unless $use_markdown;
print "\n";
-   } else {
+   } elsif (! $use_markdown) {
print "\n";
}
print "\n";
@@ -1075,7 +1079,9 @@ sub output_function_xml(%) {
 print " " . $args{'function'} . "\n";
 print " \n";
 print "  ";
+$output_markdown_nopara = 1;
 output_highlight ($args{'purpose'});
+$output_markdown_nopara = 0;
 print " \n";
 print "\n";
 
@@ -1113,10 +1119,12 @@ sub output_function_xml(%) {
$parameter_name =~ s/\[.*//;
 
print "  \n   
$parameter\n";
-   print "   \n\n";
+   print "   \n";
+   print "\n" unless $use_markdown;
$lineprefix=" ";
output_highlight($args{'parameterdescs'}{$parameter_name});
-   print "\n   \n  \n";
+   print "\n" unless $use_markdown;
+   print "   \n  \n";
}
print " \n";
 } else {
@@ -1152,7 +1160,9 @@ sub output_struct_xml(%) {
 print " " . $args{'type'} . " " . $args{'struct'} . 
"\n";
 print " \n";
 print "  ";
+$output_markdown_nopara = 1;
 output_highlight ($args{'purpose'});
+$output_markdown_nopara = 0;
 print " \n";
 print "\n";
 
@@ -1205,9 +1215,11 @@ sub output_struct_xml(%) {
   ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
   print "";
   print "  $parameter\n";
-  print "  \n";
+  print "  \n";
+  print " \n" unless $use_markdown;
   output_highlight($args{'parameterdescs'}{$parameter_name});
-  print "  \n";
+  print " \n" unless $use_markdown;
+  print "  \n";
   print "\n";
 }
 print "  \n";
@@ -1246,7 +1258,9 @@ sub output_

[PATCH 3/6] drm/doc: Convert to markdown

[Danilo Cesar Lemes de Paula]

DRM Docbook is now Markdown ready. This means its doc is able to
use markdown text on it.

* Documentation/DocBook/drm.tmpl: Contains a table duplicated from
  drivers/gpu/drm/i915/i915_reg.h. This is not needed anymore

* drivers/gpu/drm/drm_modeset_lock.c: had a code example that used
  to look pretty bad on html. Fixed by using proper code markup.

* drivers/gpu/drm/drm_prime.c: Remove spaces between lines to make
  a proper markup list.

* drivers/gpu/drm/i915/i915_reg.h: Altought pandoc supports tables,
  it doesn't support table cell spanning. But we can use fixed-width
  for those special cases.

* include/drm/drm_vma_manager.h: Another code example that should be
  proper indented with four spaces.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 Documentation/DocBook/Makefile |  2 +-
 Documentation/DocBook/drm.tmpl | 86 --
 drivers/gpu/drm/drm_modes.c| 12 +++---
 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 ++---
 7 files changed, 48 insertions(+), 140 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index c1ff834..75b7d9b 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -17,7 +17,7 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
tracepoint.xml drm.xml media_api.xml w1.xml \
writing_musb_glue_layer.xml crypto-API.xml iio.xml
 
-MARKDOWNREADY := 
+MARKDOWNREADY := drm.xml
 
 include Documentation/DocBook/media/Makefile
 
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 9ddf8c6..4111902 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -4076,92 +4076,6 @@ int num_ioctls;
   
 DPIO
 !Pdrivers/gpu/drm/i915/i915_reg.h DPIO
-   
- Dual channel PHY (VLV/CHV/BXT)
- 
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
- 
-   CH0
-   CH1
- 
-   
-   
- 
-   CMN/PLL/REF
-   CMN/PLL/REF
- 
- 
-   PCS01
-   PCS23
-   PCS01
-   PCS23
- 
- 
-   TX0
-   TX1
-   TX2
-   TX3
-   TX0
-   TX1
-   TX2
-   TX3
- 
- 
-   DDI0
-   DDI1
- 
-   
- 
-   
-   
- Single channel PHY (CHV/BXT)
- 
-   
-   
-   
-   
-   
-   
-   
-   
- 
-   CH0
- 
-   
-   
- 
-   CMN/PLL/REF
- 
- 
-   PCS01
-   PCS23
- 
- 
-   TX0
-   TX1
-   TX2
-   TX3
- 
- 
-   DDI2
- 
-   
- 
-   
   
 
   
diff --git a/drivers/gpu/drm/drm_modes.c b/drivers/gpu/drm/drm_modes.c
index cd74a09..9480464 100644
--- a/drivers/gpu/drm/drm_modes.c
+++ b/drivers/gpu/drm/drm_modes.c
@@ -553,10 +553,10 @@ EXPORT_SYMBOL(drm_gtf_mode_complex);
  * drivers/video/fbmon.c
  *
  * Standard GTF parameters:
- * M = 600
- * C = 40
- * K = 128
- * J = 20
+ * M = 600
+ * C = 40
+ * K = 128
+ * J = 20
  *
  * Returns:
  * The modeline based on the GTF algorithm stored in a drm_display_mode object.
@@ -1212,7 +1212,7 @@ EXPORT_SYMBOL(drm_mode_connector_list_update);
  * This uses the same parameters as the fb modedb.c, except for an extra
  * force-enable, force-enable-digital and force-disable bit at the end:
  *
- * x[M][R][-][@][i][m][eDd]
+ * x[M][R][-][@][i][m][eDd]
  *
  * The intermediate drm_cmdline_mode structure is required to store additional
  * options from the command line modline like the force-enable/disable flag.
@@ -1491,4 +1491,4 @@ int drm_mode_convert_umode(struct drm_display_mode *out,
 
 out:
return ret;
-}
\ No newline at end of file
+}
diff --git a/drivers/gpu/drm/drm_modeset_lock.c 
b/drivers/gpu/drm/drm_modeset_lock.c
index fba321c..9abee87 100644
--- a/drivers/gpu/drm/drm_modeset_lock.c
+++ b/drivers/gpu/drm/drm_modeset_lock.c
@@ -40,17 +40,15 @@
  * The basic usage pattern is to:
  *
  * drm_modeset_acquire_init()
- *   retry

[PATCH 2/6] scripts/kernel-doc: Adding infrastructure for markdown support

[Danilo Cesar Lemes de Paula]

Markdown support is given by calling an external tool, pandoc, for all
highlighted text on kernel-doc.

Pandoc converts Markdown text to proper Docbook tags, which will be
later translated to pdf, html or other targets.

This adds the capability of adding human-readle text highlight (bold,
underline, etc), bullet and numbered lists, simple tables, fixed-width
text (including asciiart), requiring minimal changes to current
documentation.

At this moment, pandoc is totally optional. Docbooks ready for markdown
should be added to the MARKDOWNREADY variable inside the Makefile. In
case the developer doesn't have pandoc installed, Make will throw a
warning and the documentation build will continue, generating
simple Documentation without the features brought by pandoc.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 Documentation/DocBook/Makefile | 25 +++-
 scripts/docproc.c  | 54 --
 scripts/kernel-doc | 66 --
 3 files changed, 119 insertions(+), 26 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 93eff64..c1ff834 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -17,6 +17,8 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
tracepoint.xml drm.xml media_api.xml w1.xml \
writing_musb_glue_layer.xml crypto-API.xml iio.xml
 
+MARKDOWNREADY := 
+
 include Documentation/DocBook/media/Makefile
 
 ###
@@ -81,18 +83,23 @@ XMLTOFLAGS += --skip-validation
 # The following rules are used to generate the .xml documentation
 # required to generate the final targets. (ps, pdf, html).
 quiet_cmd_docproc = DOCPROC $@
-  cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@
+  cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $<
 define rule_docproc
-   set -e; \
-$(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';)\
-$(cmd_$(1));   \
-(  \
-  echo 'cmd_$@ := $(cmd_$(1))';\
-  echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`;  \
+   set -e; 
\
+   USEMARKDOWN=""; 
\
+   FILE=`basename $@`; 
\
+   [[ "$(MARKDOWNREADY)" =~ "$${FILE}" ]] && USEMARKDOWN="-use-markdown";  
\
+$(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';)
\
+$(cmd_$(1)) $$USEMARKDOWN >$@; 
\
+(  
\
+  echo 'cmd_$@ := $(cmd_$(1))';
\
+  echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`;  
\
 ) > $(dir $@).$(notdir $@).cmd
 endef
 
 %.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
+   @(which pandoc > /dev/null 2>&1) || \
+   (echo "*** To get propper documentation you need to install pandoc 
***";)
$(call if_changed_rule,docproc)
 
 # Tell kbuild to always build the programs
@@ -103,6 +110,10 @@ notfoundtemplate = echo "*** You have to install 
docbook-utils or xmlto ***"; \
 db2xtemplate = db2TYPE -o $(dir $@) $<
 xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
 
+ifneq ($(shell which pandoc >/dev/null 2>&1 && echo found),found)
+   MARKDOWNREADY := "";
+endif
+
 # determine which methods are available
 ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
use-db2x = db2x
diff --git a/scripts/docproc.c b/scripts/docproc.c
index e267e621..7c6b225 100644
--- a/scripts/docproc.c
+++ b/scripts/docproc.c
@@ -73,12 +73,15 @@ FILELINE * docsection;
 #define NOFUNCTION"-nofunction"
 #define NODOCSECTIONS "-no-doc-sections"
 #define SHOWNOTFOUND  "-show-not-found"
+#define USEMARKDOWN   "-use-markdown"
 
 static char *srctree, *kernsrctree;
 
 static char **all_list = NULL;
 static int all_list_len = 0;
 
+static int use_markdown = 0;
+
 static void consume_symbol(const char *sym)
 {
int i;
@@ -95,10 +98,11 @@ static void consume_symbol(const char *sym)
 
 static void usage (void)
 {
-   fprintf(stderr, "Usage: docproc {doc|depend} file\n");
+   fprintf(stderr, &

[PATCH 6/6] scripts/kernel-doc: Processing -nofunc for functions only

[Danilo Cesar Lemes de Paula]

Docproc process EXPORT_SYMBOL(f1) macro and uses -nofunc f1 to
avoid duplicated documentation in the next call.
It works for most of the cases, but there are some specific situations
where a struct has the same name of an already-exported function.

Current kernel-doc behavior ignores those structs and do not add them
to the final documentation. This patch fixes it.

This is non-usual and the only case I've found is the drm_modeset_lock
(function and struct) defined in drm_modeset_lock.h and
drm_modeset_lock.c. Considering this, it should only affect the DRM
documentation by including struct drm_modeset_lock to the final Docbook.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Daniel Vetter 
Cc: Jonathan Corbet 
Cc: Andrew Morton 
Cc: Johannes Berg 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index d6129e7..a01b20ea 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1836,7 +1836,7 @@ sub output_declaration {
 my $func = "output_${functype}_$output_mode";
 if (($function_only==0) ||
( $function_only == 1 && defined($function_table{$name})) ||
-   ( $function_only == 2 && !defined($function_table{$name})))
+   ( $function_only == 2 && !($functype eq "function" && 
defined($function_table{$name}
 {
&$func(@_);
$section_counter++;
-- 
2.4.3

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

[PATCH 4/6] drm/doc: Fixing xml documentation warning

[Danilo Cesar Lemes de Paula]

"/**" should be used for kernel-doc documentation only.
It causes a warning with the new "in struct body" format.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
Cc: Graham Whaley 
---
 include/drm/drm_modeset_lock.h | 10 +-
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/include/drm/drm_modeset_lock.h b/include/drm/drm_modeset_lock.h
index 5dd18bf..94938d8 100644
--- a/include/drm/drm_modeset_lock.h
+++ b/include/drm/drm_modeset_lock.h
@@ -43,19 +43,19 @@ struct drm_modeset_acquire_ctx {
 
struct ww_acquire_ctx ww_ctx;
 
-   /**
+   /*
 * Contended lock: if a lock is contended you should only call
 * drm_modeset_backoff() which drops locks and slow-locks the
 * contended lock.
 */
struct drm_modeset_lock *contended;
 
-   /**
+   /*
 * list of held locks (drm_modeset_lock)
 */
struct list_head locked;
 
-   /**
+   /*
 * Trylock mode, use only for panic handlers!
 */
bool trylock_only;
@@ -70,12 +70,12 @@ struct drm_modeset_acquire_ctx {
  * Used for locking CRTCs and other modeset resources.
  */
 struct drm_modeset_lock {
-   /**
+   /*
 * modeset lock
 */
struct ww_mutex mutex;
 
-   /**
+   /*
 * Resources that are locked as part of an atomic update are added
 * to a list (so we know what to unlock at the end).
 */
-- 
2.4.3

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

[PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an array

[Danilo Cesar Lemes de Paula]

The "highlight" code is very sensible to the order of the hash keys,
but the order of the keys cannot be predicted. It generates
faulty DocBook entries like:
- @device_for_each_child

Sorting the result is not enough some times (as it's deterministic but
we can't control it).
We should use an array for that job, so we can guarantee that the order
of the regex execution on dohighlight is correct.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 scripts/kernel-doc | 104 ++---
 1 file changed, 60 insertions(+), 44 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9a08fb5..0affe4f 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -206,59 +206,73 @@ my $type_env = '(\$\w+)';
 #  One for each output format
 
 # these work fairly well
-my %highlights_html = ( $type_constant, "\$1",
-   $type_func, "\$1",
-   $type_struct_xml, "\$1",
-   $type_env, "\$1",
-   $type_param, "\$1" );
+my @highlights_html = (
+   [$type_constant, "\$1"],
+   [$type_func, "\$1"],
+   [$type_struct_xml, "\$1"],
+   [$type_env, "\$1"],
+   [$type_param, "\$1"]
+  );
 my $local_lt = "lt:";
 my $local_gt = "gt:";
 my $blankline_html = $local_lt . "p" . $local_gt;  # was ""
 
 # html version 5
-my %highlights_html5 = ( $type_constant, "\$1",
-   $type_func, "\$1",
-   $type_struct_xml, "\$1",
-   $type_env, "\$1",
-   $type_param, "\$1" );
+my @highlights_html5 = (
+[$type_constant, "\$1"],
+[$type_func, "\$1"],
+[$type_struct_xml, "\$1"],
+[$type_env, "\$1"],
+[$type_param, "\$1]"]
+  );
 my $blankline_html5 = $local_lt . "br /" . $local_gt;
 
 # XML, docbook format
-my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2",
-   $type_constant, "\$1",
-   $type_func, "\$1",
-   $type_struct_xml, "\$1",
-   $type_env, "\$1",
-   $type_param, "\$1" );
+my @highlights_xml = (
+  ["([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2"],
+  [$type_constant, "\$1"],
+  [$type_struct_xml, "\$1"],
+  [$type_param, "\$1"],
+  [$type_func, "\$1"],
+  [$type_env, "\$1"]
+);
 my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . 
$local_gt . "\n";
 
 # gnome, docbook format
-my %highlights_gnome = ( $type_constant, "\$1",
-$type_func, "\$1",
-$type_struct, "\$1",
-$type_env, "\$1",
-$type_param, "\$1" );
+my @highlights_gnome = (
+[$type_constant, "\$1"],
+[$type_func, "\$1"],
+[$type_struct, "\$1"],
+[$type_env, "\$1"],
+[$type_param, "\$1" ]
+  );
 my $blankline_gnome = "\n";
 
 # these are pretty rough
-my %highlights_man = ( $type_constant, "\$1",
-  $type_func, "fB\$1fP",
-  $type_struct, "fI\$1fP",
-  $type_param, "fI\$1fP" );
+my @highlights_man = (
+  [$type_constant, "\$1"],
+  [$type_func, "fB\$1fP"],
+  [$type_struct, "fI\$1fP"],
+  [$type_param, "fI\$1fP"]
+);
 my $blankline_man = "";
 
 # text-mode
-my %highlights_text = ( $type_constant, "\$1",
-   $type_func, "\$1",
-   $t

[PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements

[Danilo Cesar Lemes de Paula]

The following series contains:
 * kernel-doc: markdown support and improvements.
 * Fixing kernel-doc highlights.
 * Improve doc support for functions and structs with same name.
 * misc small fixes for drm docbook.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Daniel Vetter 
Cc: Jonathan Corbet 
Cc: Andrew Morton 
Cc: Johannes Berg 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 

Danilo Cesar Lemes de Paula (6):
  scripts/kernel-doc: Replacing highlights hash by an array
  scripts/kernel-doc: Adding infrastructure for markdown support
  drm/doc: Convert to markdown
  drm/doc: Fixing xml documentation warning
  scripts/kernel-doc: Improve Markdown results
  scripts/kernel-doc: Processing -nofunc for functions only

 Documentation/DocBook/Makefile |  25 +++--
 Documentation/DocBook/drm.tmpl |  86 ---
 drivers/gpu/drm/drm_modes.c|  12 +--
 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_modeset_lock.h |  10 +-
 include/drm/drm_vma_manager.h  |  10 +-
 scripts/docproc.c  |  54 +++---
 scripts/kernel-doc | 216 ++---
 10 files changed, 264 insertions(+), 227 deletions(-)

-- 
2.4.3

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

[PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements

[Danilo Cesar Lemes de Paula]

The following series contains:
 * kernel-doc: markdown support and improvements.
 * Fixing kernel-doc highlights.
 * Improve doc support for functions and structs with same name.
 * misc small fixes for drm docbook.

Signed-off-by: Danilo Cesar Lemes de Paula <danilo.ce...@collabora.co.uk>
Cc: Daniel Vetter <daniel.vet...@ffwll.ch>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Andrew Morton <a...@linux-foundation.org>
Cc: Johannes Berg <johannes.b...@intel.com>
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx <intel-...@lists.freedesktop.org>
Cc: dri-devel <dri-de...@lists.freedesktop.org>

Danilo Cesar Lemes de Paula (6):
  scripts/kernel-doc: Replacing highlights hash by an array
  scripts/kernel-doc: Adding infrastructure for markdown support
  drm/doc: Convert to markdown
  drm/doc: Fixing xml documentation warning
  scripts/kernel-doc: Improve Markdown results
  scripts/kernel-doc: Processing -nofunc for functions only

 Documentation/DocBook/Makefile |  25 +++--
 Documentation/DocBook/drm.tmpl |  86 ---
 drivers/gpu/drm/drm_modes.c|  12 +--
 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_modeset_lock.h |  10 +-
 include/drm/drm_vma_manager.h  |  10 +-
 scripts/docproc.c  |  54 +++---
 scripts/kernel-doc | 216 ++---
 10 files changed, 264 insertions(+), 227 deletions(-)

-- 
2.4.3

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

[PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an array

[Danilo Cesar Lemes de Paula]

The "highlight" code is very sensible to the order of the hash keys,
but the order of the keys cannot be predicted. It generates
faulty DocBook entries like:
- @device_for_each_child

Sorting the result is not enough some times (as it's deterministic but
we can't control it).
We should use an array for that job, so we can guarantee that the order
of the regex execution on dohighlight is correct.

Signed-off-by: Danilo Cesar Lemes de Paula <danilo.ce...@collabora.co.uk>
Cc: Randy Dunlap <rdun...@infradead.org>
Cc: Daniel Vetter <daniel.vet...@ffwll.ch>
Cc: Laurent Pinchart <laurent.pinch...@ideasonboard.com>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Herbert Xu <herb...@gondor.apana.org.au>
Cc: Stephan Mueller <smuel...@chronox.de>
Cc: Michal Marek <mma...@suse.cz>
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx <intel-...@lists.freedesktop.org>
Cc: dri-devel <dri-de...@lists.freedesktop.org>
---
 scripts/kernel-doc | 104 ++---
 1 file changed, 60 insertions(+), 44 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9a08fb5..0affe4f 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -206,59 +206,73 @@ my $type_env = '(\$\w+)';
 #  One for each output format
 
 # these work fairly well
-my %highlights_html = ( $type_constant, "\$1",
-   $type_func, "\$1",
-   $type_struct_xml, "\$1",
-   $type_env, "\$1",
-   $type_param, "\$1" );
+my @highlights_html = (
+   [$type_constant, "\$1"],
+   [$type_func, "\$1"],
+   [$type_struct_xml, "\$1"],
+   [$type_env, "\$1"],
+   [$type_param, "\$1"]
+  );
 my $local_lt = "lt:";
 my $local_gt = "gt:";
 my $blankline_html = $local_lt . "p" . $local_gt;  # was ""
 
 # html version 5
-my %highlights_html5 = ( $type_constant, "\$1",
-   $type_func, "\$1",
-   $type_struct_xml, "\$1",
-   $type_env, "\$1",
-   $type_param, "\$1" );
+my @highlights_html5 = (
+[$type_constant, "\$1"],
+[$type_func, "\$1"],
+[$type_struct_xml, "\$1"],
+[$type_env, "\$1"],
+[$type_param, "\$1]"]
+  );
 my $blankline_html5 = $local_lt . "br /" . $local_gt;
 
 # XML, docbook format
-my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2",
-   $type_constant, "\$1",
-   $type_func, "\$1",
-   $type_struct_xml, "\$1",
-   $type_env, "\$1",
-   $type_param, "\$1" );
+my @highlights_xml = (
+  ["([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2"],
+  [$type_constant, "\$1"],
+  [$type_struct_xml, "\$1"],
+  [$type_param, "\$1"],
+  [$type_func, "\$1"],
+  [$type_env, "\$1"]
+);
 my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . 
$local_gt . "\n";
 
 # gnome, docbook format
-my %highlights_gnome = ( $type_constant, "\$1",
-$type_func, "\$1",
-$type_struct, "\$1",
-$type_env, "\$1",
-$type_param, "\$1" );
+my @highlights_gnome = (
+[$type_constant, "\$1"],
+[$type_func, "\$1"],
+[$type_struct, "\$1"],
+[$type_env, "\$1"],
+[$type_param, "\$1" ]
+  );
 my $blankline_gnome = "\n";
 
 # these are pretty rough
-my %highlights_man = ( $type_constant, "\$1",
-  $type_func, "fB\$1fP",
-  $type_struct, "fI\$1fP",
-  $type_param, "fI\$1fP" );
+my @highlights_man = (
+  [$type_constant, "\$1"],
+  [$type_func, "fB\$1fP"],
+  [$type

[PATCH 6/6] scripts/kernel-doc: Processing -nofunc for functions only

[Danilo Cesar Lemes de Paula]

Docproc process EXPORT_SYMBOL(f1) macro and uses -nofunc f1 to
avoid duplicated documentation in the next call.
It works for most of the cases, but there are some specific situations
where a struct has the same name of an already-exported function.

Current kernel-doc behavior ignores those structs and do not add them
to the final documentation. This patch fixes it.

This is non-usual and the only case I've found is the drm_modeset_lock
(function and struct) defined in drm_modeset_lock.h and
drm_modeset_lock.c. Considering this, it should only affect the DRM
documentation by including struct drm_modeset_lock to the final Docbook.

Signed-off-by: Danilo Cesar Lemes de Paula <danilo.ce...@collabora.co.uk>
Cc: Daniel Vetter <daniel.vet...@ffwll.ch>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Andrew Morton <a...@linux-foundation.org>
Cc: Johannes Berg <johannes.b...@intel.com>
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx <intel-...@lists.freedesktop.org>
Cc: dri-devel <dri-de...@lists.freedesktop.org>
---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index d6129e7..a01b20ea 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1836,7 +1836,7 @@ sub output_declaration {
 my $func = "output_${functype}_$output_mode";
 if (($function_only==0) ||
( $function_only == 1 && defined($function_table{$name})) ||
-   ( $function_only == 2 && !defined($function_table{$name})))
+   ( $function_only == 2 && !($functype eq "function" && 
defined($function_table{$name}
 {
&$func(@_);
$section_counter++;
-- 
2.4.3

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

[PATCH 5/6] scripts/kernel-doc: Improve Markdown results

[Danilo Cesar Lemes de Paula]

Using pandoc as the Markdown engine cause some minor side effects as
pandoc includes  main  tags for almost everything.
Original Markdown support approach removes those main tags, but it caused
some inconsistencies when that tag is not the main one, like:
..
...

As kernel-doc was already including a  tag, it causes the presence
of double  tags (), which is not supported by DocBook
spec.

Html target gets away with it, so it causes no harm, although other
targets might not be so lucky (pdf as example).

We're now delegating the inclusion of the main  tag to pandoc
only, as it knows when it's necessary or not.

That behavior causes a corner case, the only situation where we're
certainly that  is not needed, which is the  content.
For those cases, we're using a $output_markdown_nopara = 1 control var.

Signed-off-by: Danilo Cesar Lemes de Paula <danilo.ce...@collabora.co.uk>
Cc: Randy Dunlap <rdun...@infradead.org>
Cc: Daniel Vetter <daniel.vet...@ffwll.ch>
Cc: Laurent Pinchart <laurent.pinch...@ideasonboard.com>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Herbert Xu <herb...@gondor.apana.org.au>
Cc: Stephan Mueller <smuel...@chronox.de>
Cc: Michal Marek <mma...@suse.cz>
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx <intel-...@lists.freedesktop.org>
Cc: dri-devel <dri-de...@lists.freedesktop.org>
Cc: Graham Whaley <graham.wha...@linux.intel.com>
---
 scripts/kernel-doc | 48 ++--
 1 file changed, 34 insertions(+), 14 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 5fe572a..d6129e7 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -288,6 +288,7 @@ my $use_markdown = 0;
 my $verbose = 0;
 my $output_mode = "man";
 my $output_preformatted = 0;
+my $output_markdown_nopara = 0;
 my $no_doc_sections = 0;
 my @highlights = @highlights_man;
 my $blankline = $blankline_man;
@@ -538,8 +539,11 @@ sub markdown_to_docbook {
close(CHLD_OUT);
close(CHLD_ERR);
 
-   # pandoc insists in adding Main , we should remove them.
-   $content =~ s:\A\s*\s*\n(.*)\n\Z$:$1:egsm;
+   if ($output_markdown_nopara) {
+   # pandoc insists in adding Main , sometimes we
+   # want to remove them.
+   $content =~ s:\A\s*\s*\n(.*)\n\Z$:$1:egsm;
+   }
 
return $content;
 }
@@ -614,7 +618,7 @@ sub output_highlight {
$line =~ s/^\s*//;
}
if ($line eq ""){
-   if (! $output_preformatted) {
+   if (! $output_preformatted && ! $use_markdown) {
print $lineprefix, local_unescape($blankline);
}
} else {
@@ -1035,7 +1039,7 @@ sub output_section_xml(%) {
# programlisting is already included by pandoc
print "\n" unless $use_markdown;
$output_preformatted = 1;
-   } else {
+   } elsif (! $use_markdown) {
print "\n";
}
output_highlight($args{'sections'}{$section});
@@ -1043,7 +1047,7 @@ sub output_section_xml(%) {
if ($section =~ m/EXAMPLE/i) {
print "\n" unless $use_markdown;
print "\n";
-   } else {
+   } elsif (! $use_markdown) {
print "\n";
}
print "\n";
@@ -1075,7 +1079,9 @@ sub output_function_xml(%) {
 print " " . $args{'function'} . "\n";
 print " \n";
 print "  ";
+$output_markdown_nopara = 1;
 output_highlight ($args{'purpose'});
+$output_markdown_nopara = 0;
 print " \n";
 print "\n";
 
@@ -1113,10 +1119,12 @@ sub output_function_xml(%) {
$parameter_name =~ s/\[.*//;
 
print "  \n   
$parameter\n";
-   print "   \n\n";
+   print "   \n";
+   print "\n" unless $use_markdown;
$lineprefix=" ";
output_highlight($args{'parameterdescs'}{$parameter_name});
-   print "\n   \n  \n";
+   print "\n" unless $use_markdown;
+   print "   \n  \n";
}
print " \n";
 } else {
@@ -1152,7 +1160,9 @@ sub output_struct_xml(%) {
 print " " . $args{'type'} . " " . $args{'struct'} . 
"\n";
 print " \n";
 print "  ";
+$output_markdown_nopara = 1;
 output_highlight ($args{'purpose'});
+$output_markdown_nopara = 0;
 print " \n";
 print "\n";
 
@@ -1205,9 +1215,11 @@ sub output_struct_xml(%) {
   ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
   print "";
   print "  $parameter\n";
-  print "  \n";
+  print "  \n";
+   

[PATCH 2/6] scripts/kernel-doc: Adding infrastructure for markdown support

[Danilo Cesar Lemes de Paula]

Markdown support is given by calling an external tool, pandoc, for all
highlighted text on kernel-doc.

Pandoc converts Markdown text to proper Docbook tags, which will be
later translated to pdf, html or other targets.

This adds the capability of adding human-readle text highlight (bold,
underline, etc), bullet and numbered lists, simple tables, fixed-width
text (including asciiart), requiring minimal changes to current
documentation.

At this moment, pandoc is totally optional. Docbooks ready for markdown
should be added to the MARKDOWNREADY variable inside the Makefile. In
case the developer doesn't have pandoc installed, Make will throw a
warning and the documentation build will continue, generating
simple Documentation without the features brought by pandoc.

Signed-off-by: Danilo Cesar Lemes de Paula <danilo.ce...@collabora.co.uk>
Cc: Randy Dunlap <rdun...@infradead.org>
Cc: Daniel Vetter <daniel.vet...@ffwll.ch>
Cc: Laurent Pinchart <laurent.pinch...@ideasonboard.com>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Herbert Xu <herb...@gondor.apana.org.au>
Cc: Stephan Mueller <smuel...@chronox.de>
Cc: Michal Marek <mma...@suse.cz>
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx <intel-...@lists.freedesktop.org>
Cc: dri-devel <dri-de...@lists.freedesktop.org>
---
 Documentation/DocBook/Makefile | 25 +++-
 scripts/docproc.c  | 54 --
 scripts/kernel-doc | 66 --
 3 files changed, 119 insertions(+), 26 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 93eff64..c1ff834 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -17,6 +17,8 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
tracepoint.xml drm.xml media_api.xml w1.xml \
writing_musb_glue_layer.xml crypto-API.xml iio.xml
 
+MARKDOWNREADY := 
+
 include Documentation/DocBook/media/Makefile
 
 ###
@@ -81,18 +83,23 @@ XMLTOFLAGS += --skip-validation
 # The following rules are used to generate the .xml documentation
 # required to generate the final targets. (ps, pdf, html).
 quiet_cmd_docproc = DOCPROC $@
-  cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@
+  cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $<
 define rule_docproc
-   set -e; \
-$(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';)\
-$(cmd_$(1));   \
-(  \
-  echo 'cmd_$@ := $(cmd_$(1))';\
-  echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`;  \
+   set -e; 
\
+   USEMARKDOWN=""; 
\
+   FILE=`basename $@`; 
\
+   [[ "$(MARKDOWNREADY)" =~ "$${FILE}" ]] && USEMARKDOWN="-use-markdown";  
\
+$(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';)
\
+$(cmd_$(1)) $$USEMARKDOWN >$@; 
\
+(  
\
+  echo 'cmd_$@ := $(cmd_$(1))';
\
+  echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`;  
\
 ) > $(dir $@).$(notdir $@).cmd
 endef
 
 %.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
+   @(which pandoc > /dev/null 2>&1) || \
+   (echo "*** To get propper documentation you need to install pandoc 
***";)
$(call if_changed_rule,docproc)
 
 # Tell kbuild to always build the programs
@@ -103,6 +110,10 @@ notfoundtemplate = echo "*** You have to install 
docbook-utils or xmlto ***"; \
 db2xtemplate = db2TYPE -o $(dir $@) $<
 xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
 
+ifneq ($(shell which pandoc >/dev/null 2>&1 && echo found),found)
+   MARKDOWNREADY := "";
+endif
+
 # determine which methods are available
 ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
use-db2x = db2x
diff --git a/scripts/docproc.c b/scripts/docproc.c
index e267e621..7c6b225 100644
--- a/scripts/docproc.c
+++ b/scripts/docproc.c
@@ -73,12 +73,15 @@ FILELINE * docsection;
 #define NOFUNCTION"-nofunction"
 #define NODOCSECTIONS "-no-doc-sections"
 #define SHOWNOTFOUND  "-show-not-found"
+#define USEMARKDOWN   "-use-markdown"
 
 static char *srctree, *kernsrctree;
 
 static char **all_list = NULL;
 

[PATCH 4/6] drm/doc: Fixing xml documentation warning

[Danilo Cesar Lemes de Paula]

"/**" should be used for kernel-doc documentation only.
It causes a warning with the new "in struct body" format.

Signed-off-by: Danilo Cesar Lemes de Paula <danilo.ce...@collabora.co.uk>
Cc: Randy Dunlap <rdun...@infradead.org>
Cc: Daniel Vetter <daniel.vet...@ffwll.ch>
Cc: Laurent Pinchart <laurent.pinch...@ideasonboard.com>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Herbert Xu <herb...@gondor.apana.org.au>
Cc: Stephan Mueller <smuel...@chronox.de>
Cc: Michal Marek <mma...@suse.cz>
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx <intel-...@lists.freedesktop.org>
Cc: dri-devel <dri-de...@lists.freedesktop.org>
Cc: Graham Whaley <graham.wha...@linux.intel.com>
---
 include/drm/drm_modeset_lock.h | 10 +-
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/include/drm/drm_modeset_lock.h b/include/drm/drm_modeset_lock.h
index 5dd18bf..94938d8 100644
--- a/include/drm/drm_modeset_lock.h
+++ b/include/drm/drm_modeset_lock.h
@@ -43,19 +43,19 @@ struct drm_modeset_acquire_ctx {
 
struct ww_acquire_ctx ww_ctx;
 
-   /**
+   /*
 * Contended lock: if a lock is contended you should only call
 * drm_modeset_backoff() which drops locks and slow-locks the
 * contended lock.
 */
struct drm_modeset_lock *contended;
 
-   /**
+   /*
 * list of held locks (drm_modeset_lock)
 */
struct list_head locked;
 
-   /**
+   /*
 * Trylock mode, use only for panic handlers!
 */
bool trylock_only;
@@ -70,12 +70,12 @@ struct drm_modeset_acquire_ctx {
  * Used for locking CRTCs and other modeset resources.
  */
 struct drm_modeset_lock {
-   /**
+   /*
 * modeset lock
 */
struct ww_mutex mutex;
 
-   /**
+   /*
 * Resources that are locked as part of an atomic update are added
 * to a list (so we know what to unlock at the end).
 */
-- 
2.4.3

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

[PATCH 3/6] drm/doc: Convert to markdown

[Danilo Cesar Lemes de Paula]

DRM Docbook is now Markdown ready. This means its doc is able to
use markdown text on it.

* Documentation/DocBook/drm.tmpl: Contains a table duplicated from
  drivers/gpu/drm/i915/i915_reg.h. This is not needed anymore

* drivers/gpu/drm/drm_modeset_lock.c: had a code example that used
  to look pretty bad on html. Fixed by using proper code markup.

* drivers/gpu/drm/drm_prime.c: Remove spaces between lines to make
  a proper markup list.

* drivers/gpu/drm/i915/i915_reg.h: Altought pandoc supports tables,
  it doesn't support table cell spanning. But we can use fixed-width
  for those special cases.

* include/drm/drm_vma_manager.h: Another code example that should be
  proper indented with four spaces.

Signed-off-by: Danilo Cesar Lemes de Paula <danilo.ce...@collabora.co.uk>
Cc: Randy Dunlap <rdun...@infradead.org>
Cc: Daniel Vetter <daniel.vet...@ffwll.ch>
Cc: Laurent Pinchart <laurent.pinch...@ideasonboard.com>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Herbert Xu <herb...@gondor.apana.org.au>
Cc: Stephan Mueller <smuel...@chronox.de>
Cc: Michal Marek <mma...@suse.cz>
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx <intel-...@lists.freedesktop.org>
Cc: dri-devel <dri-de...@lists.freedesktop.org>
---
 Documentation/DocBook/Makefile |  2 +-
 Documentation/DocBook/drm.tmpl | 86 --
 drivers/gpu/drm/drm_modes.c| 12 +++---
 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 ++---
 7 files changed, 48 insertions(+), 140 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index c1ff834..75b7d9b 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -17,7 +17,7 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
tracepoint.xml drm.xml media_api.xml w1.xml \
writing_musb_glue_layer.xml crypto-API.xml iio.xml
 
-MARKDOWNREADY := 
+MARKDOWNREADY := drm.xml
 
 include Documentation/DocBook/media/Makefile
 
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 9ddf8c6..4111902 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -4076,92 +4076,6 @@ int num_ioctls;
   
 DPIO
 !Pdrivers/gpu/drm/i915/i915_reg.h DPIO
-   
- Dual channel PHY (VLV/CHV/BXT)
- 
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
- 
-   CH0
-   CH1
- 
-   
-   
- 
-   CMN/PLL/REF
-   CMN/PLL/REF
- 
- 
-   PCS01
-   PCS23
-   PCS01
-   PCS23
- 
- 
-   TX0
-   TX1
-   TX2
-   TX3
-   TX0
-   TX1
-   TX2
-   TX3
- 
- 
-   DDI0
-   DDI1
- 
-   
- 
-   
-   
- Single channel PHY (CHV/BXT)
- 
-   
-   
-   
-   
-   
-   
-   
-   
- 
-   CH0
- 
-   
-   
- 
-   CMN/PLL/REF
- 
- 
-   PCS01
-   PCS23
- 
- 
-   TX0
-   TX1
-   TX2
-   TX3
- 
- 
-   DDI2
- 
-   
- 
-   
   
 
   
diff --git a/drivers/gpu/drm/drm_modes.c b/drivers/gpu/drm/drm_modes.c
index cd74a09..9480464 100644
--- a/drivers/gpu/drm/drm_modes.c
+++ b/drivers/gpu/drm/drm_modes.c
@@ -553,10 +553,10 @@ EXPORT_SYMBOL(drm_gtf_mode_complex);
  * drivers/video/fbmon.c
  *
  * Standard GTF parameters:
- * M = 600
- * C = 40
- * K = 128
- * J = 20
+ * M = 600
+ * C = 40
+ * K = 128
+ * J = 20
  *
  * Returns:
  * The modeline based on the GTF algorithm stored in a drm_display_mode object.
@@ -1212,7 +1212,7 @@ EXPORT_SYMBOL(drm_mode_connector_list_update);
  * This uses the same parameters as the fb modedb.c, except for an extra
  * force-enable, force-enable-digital and force-disable bit at the end:
  *
- * x[M][R][-][@][i][m][eDd]
+ * x[M][R][-][@][i][m][eDd]
  *
  * The intermediate drm_cmdline_mode structure is required to store additional
  * options from the command line modline like the force-enable/disable flag.
@@ -1491,4 +1491,4 @@ int drm_mode_convert_umode(struct drm_display_mode *out,
 
 out:
return ret;
-}
\ No newline at end o

Re: [PATCH] scripts/kernel-doc: Improve Markdown results

[Danilo Cesar Lemes de Paula]

On 09/04/2015 05:39 PM, Jonathan Corbet wrote:
> On Fri, 4 Sep 2015 14:53:34 -0300
> Danilo Cesar Lemes de Paula <danilo.ce...@collabora.co.uk> wrote:
> 
>> In the last few days I sent three features:
>> Markdown support (patch series 1)
>> Cross-reference hyperlink support (patch series 1)
>> in-struct-body documentation (series 2)
>>
>> I assume you want a new patch series for the series 1, containing the
>> feature itself and the fixes that I sent later, correct?
> 
> The cross-reference patch was merged, so there's no need to send that
> again.  Anything else that isn't in mainline now should be resent as a
> new series.

I did send a new set, named "[PATCH 0/6] scripts/kernel-doc: Kernel-doc
improvements"
I did include all the patches I didn't find in mainline.
Is it enough?

Thanks,

Danilo


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

Re: [PATCH] scripts/kernel-doc: Improve Markdown results

[Danilo Cesar Lemes de Paula]

On 09/02/2015 11:15 AM, Jonathan Corbet wrote:
> On Tue, 1 Sep 2015 14:57:33 -0300
> Danilo Cesar Lemes de Paula  wrote:
> 
>> Did you find time to check this patch? As you mentioned that you applied
>> the Markdown support for the linux-next tree, this patch might be needed
>> (maybe "wanted" is a better word).
> 
> Not quite what I said...I said I'd apply it right after the merge window
> so it can sit in linux-next through the full cycle.  It's a bit early to
> be pushing 4.4 stuff into linux-next now...
> 
> Beyond that, I wasn't sure where things stand with fixes... Can you send
> me a new patch set with this fix (and any others that might
> exist) integrated in?

Sure, but I'm a bit confused now (kernel noob here).

In the last few days I sent three features:
Markdown support (patch series 1)
Cross-reference hyperlink support (patch series 1)
in-struct-body documentation (series 2)

I assume you want a new patch series for the series 1, containing the
feature itself and the fixes that I sent later, correct?

Thanks,

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

Re: [PATCH] scripts/kernel-doc: Improve Markdown results

[Danilo Cesar Lemes de Paula]

On 09/02/2015 11:15 AM, Jonathan Corbet wrote:
> On Tue, 1 Sep 2015 14:57:33 -0300
> Danilo Cesar Lemes de Paula <danilo.ce...@collabora.co.uk> wrote:
> 
>> Did you find time to check this patch? As you mentioned that you applied
>> the Markdown support for the linux-next tree, this patch might be needed
>> (maybe "wanted" is a better word).
> 
> Not quite what I said...I said I'd apply it right after the merge window
> so it can sit in linux-next through the full cycle.  It's a bit early to
> be pushing 4.4 stuff into linux-next now...
> 
> Beyond that, I wasn't sure where things stand with fixes... Can you send
> me a new patch set with this fix (and any others that might
> exist) integrated in?

Sure, but I'm a bit confused now (kernel noob here).

In the last few days I sent three features:
Markdown support (patch series 1)
Cross-reference hyperlink support (patch series 1)
in-struct-body documentation (series 2)

I assume you want a new patch series for the series 1, containing the
feature itself and the fixes that I sent later, correct?

Thanks,

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

Re: [PATCH] scripts/kernel-doc: Improve Markdown results

[Danilo Cesar Lemes de Paula]

On 08/21/2015 04:39 PM, Danilo Cesar Lemes de Paula wrote:
> Using pandoc as the Markdown engine cause some minor side effects as
> pandoc includes  main  tags for almost everything.
> Original Markdown support approach removes those main tags, but it caused
> some inconsistencies when that tag is not the main one, like:
> ..
> ...
> 
> As kernel-doc was already including a  tag, it causes the presence
> of double  tags (), which is not supported by DocBook
> spec.
> 
> Html target gets away with it, so it causes no harm, although other
> targets might not be so lucky (pdf as example).
> 
> We're now delegating the inclusion of the main  tag to pandoc
> only, as it knows when it's necessary or not.
> 
> That behavior causes a corner case, the only situation where we're
> certainly that  is not needed, which is the  content.
> For those cases, we're using a $output_markdown_nopara = 1 control var.
> 
> Signed-off-by: Danilo Cesar Lemes de Paula 
> Cc: Randy Dunlap 
> Cc: Daniel Vetter 
> Cc: Laurent Pinchart 
> Cc: Jonathan Corbet 
> Cc: Herbert Xu 
> Cc: Stephan Mueller 
> Cc: Michal Marek 
> Cc: linux-kernel@vger.kernel.org
> Cc: linux-...@vger.kernel.org
> Cc: intel-gfx 
> Cc: dri-devel 
> Cc: Graham Whaley 
> ---
>  Thanks to Graham Whaley who helped me to debug this.
> 
>  scripts/kernel-doc | 48 ++--
>  1 file changed, 34 insertions(+), 14 deletions(-)
> 
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 3850c1e..12a106c 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -288,6 +288,7 @@ my $use_markdown = 0;
>  my $verbose = 0;
>  my $output_mode = "man";
>  my $output_preformatted = 0;
> +my $output_markdown_nopara = 0;
>  my $no_doc_sections = 0;
>  my @highlights = @highlights_man;
>  my $blankline = $blankline_man;
> @@ -529,8 +530,11 @@ sub markdown_to_docbook {
>   close(CHLD_OUT);
>   close(CHLD_ERR);
>  
> - # pandoc insists in adding Main , we should remove them.
> - $content =~ s:\A\s*\s*\n(.*)\n\Z$:$1:egsm;
> + if ($output_markdown_nopara) {
> + # pandoc insists in adding Main , sometimes we
> + # want to remove them.
> + $content =~ s:\A\s*\s*\n(.*)\n\Z$:$1:egsm;
> + }
>  
>   return $content;
>  }
> @@ -605,7 +609,7 @@ sub output_highlight {
>   $line =~ s/^\s*//;
>   }
>   if ($line eq ""){
> - if (! $output_preformatted) {
> + if (! $output_preformatted && ! $use_markdown) {
>   print $lineprefix, local_unescape($blankline);
>   }
>   } else {
> @@ -1026,7 +1030,7 @@ sub output_section_xml(%) {
>   # programlisting is already included by pandoc
>   print "\n" unless $use_markdown;
>   $output_preformatted = 1;
> - } else {
> + } elsif (! $use_markdown) {
>   print "\n";
>   }
>   output_highlight($args{'sections'}{$section});
> @@ -1034,7 +1038,7 @@ sub output_section_xml(%) {
>   if ($section =~ m/EXAMPLE/i) {
>   print "\n" unless $use_markdown;
>   print "\n";
> - } else {
> + } elsif (! $use_markdown) {
>   print "\n";
>   }
>   print "\n";
> @@ -1066,7 +1070,9 @@ sub output_function_xml(%) {
>  print " " . $args{'function'} . "\n";
>  print " \n";
>  print "  ";
> +$output_markdown_nopara = 1;
>  output_highlight ($args{'purpose'});
> +$output_markdown_nopara = 0;
>  print " \n";
>  print "\n";
>  
> @@ -1104,10 +1110,12 @@ sub output_function_xml(%) {
>   $parameter_name =~ s/\[.*//;
>  
>   print "  \n   
> $parameter\n";
> - print "   \n\n";
> + print "   \n";
> + print "\n" unless $use_markdown;
>   $lineprefix=" ";
>   output_highlight($args{'parameterdescs'}{$parameter_name});
> - print "\n   \n  \n";
> + print "\n" unless $use_markdown;
> + print "   \n  \n";
>   }
>   print " \n";
>  } else {
> @@ -1143,7 +1151,9 @@ sub output_struct_xml(%) {
>  print " " . $args{'type'} . " " . $args{'struct'} . 
> "\n";
>  print " \n";
>  print "  ";
> +$output_markdown_nopara = 1;
>  output_highlight ($args{'purpose'});
> +$output_markdown_nopara = 0;
>  print " \

[PATCH] scripts/kernel-doc: Processing -nofunc for functions only

[Danilo Cesar Lemes de Paula]

Docproc process EXPORT_SYMBOL(f1) macro and uses -nofunc f1 to
avoid duplicated documentation in the next call.
It works for most of the cases, but there are some specific situations
where a struct has the same name of an already-exported function.

Current kernel-doc behavior ignores those structs and do not add them
to the final documentation. This patch fixes it.

This is non-usual and the only case I've found is the drm_modeset_lock
(function and struct) defined in drm_modeset_lock.h and
drm_modeset_lock.c. Considering this, it should only affect the DRM
documentation by including struct drm_modeset_lock to the final Docbook.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Daniel Vetter 
Cc: Jonathan Corbet 
Cc: Andrew Morton 
Cc: Johannes Berg 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 12a106c..047deb7 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1827,7 +1827,7 @@ sub output_declaration {
 my $func = "output_${functype}_$output_mode";
 if (($function_only==0) ||
( $function_only == 1 && defined($function_table{$name})) ||
-   ( $function_only == 2 && !defined($function_table{$name})))
+   ( $function_only == 2 && !($functype eq "function" && 
defined($function_table{$name}
 {
&$func(@_);
$section_counter++;
-- 
2.4.3

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

[PATCH] scripts/kernel-doc: Processing -nofunc for functions only

[Danilo Cesar Lemes de Paula]

Docproc process EXPORT_SYMBOL(f1) macro and uses -nofunc f1 to
avoid duplicated documentation in the next call.
It works for most of the cases, but there are some specific situations
where a struct has the same name of an already-exported function.

Current kernel-doc behavior ignores those structs and do not add them
to the final documentation. This patch fixes it.

This is non-usual and the only case I've found is the drm_modeset_lock
(function and struct) defined in drm_modeset_lock.h and
drm_modeset_lock.c. Considering this, it should only affect the DRM
documentation by including struct drm_modeset_lock to the final Docbook.

Signed-off-by: Danilo Cesar Lemes de Paula <danilo.ce...@collabora.co.uk>
Cc: Daniel Vetter <daniel.vet...@ffwll.ch>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Andrew Morton <a...@linux-foundation.org>
Cc: Johannes Berg <johannes.b...@intel.com>
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx <intel-...@lists.freedesktop.org>
Cc: dri-devel <dri-de...@lists.freedesktop.org>
---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 12a106c..047deb7 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1827,7 +1827,7 @@ sub output_declaration {
 my $func = "output_${functype}_$output_mode";
 if (($function_only==0) ||
( $function_only == 1 && defined($function_table{$name})) ||
-   ( $function_only == 2 && !defined($function_table{$name})))
+   ( $function_only == 2 && !($functype eq "function" && 
defined($function_table{$name}
 {
&$func(@_);
$section_counter++;
-- 
2.4.3

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

Re: [PATCH] scripts/kernel-doc: Improve Markdown results

[Danilo Cesar Lemes de Paula]

On 08/21/2015 04:39 PM, Danilo Cesar Lemes de Paula wrote:
> Using pandoc as the Markdown engine cause some minor side effects as
> pandoc includes  main  tags for almost everything.
> Original Markdown support approach removes those main tags, but it caused
> some inconsistencies when that tag is not the main one, like:
> ..
> ...
> 
> As kernel-doc was already including a  tag, it causes the presence
> of double  tags (), which is not supported by DocBook
> spec.
> 
> Html target gets away with it, so it causes no harm, although other
> targets might not be so lucky (pdf as example).
> 
> We're now delegating the inclusion of the main  tag to pandoc
> only, as it knows when it's necessary or not.
> 
> That behavior causes a corner case, the only situation where we're
> certainly that  is not needed, which is the  content.
> For those cases, we're using a $output_markdown_nopara = 1 control var.
> 
> Signed-off-by: Danilo Cesar Lemes de Paula <danilo.ce...@collabora.co.uk>
> Cc: Randy Dunlap <rdun...@infradead.org>
> Cc: Daniel Vetter <daniel.vet...@ffwll.ch>
> Cc: Laurent Pinchart <laurent.pinch...@ideasonboard.com>
> Cc: Jonathan Corbet <cor...@lwn.net>
> Cc: Herbert Xu <herb...@gondor.apana.org.au>
> Cc: Stephan Mueller <smuel...@chronox.de>
> Cc: Michal Marek <mma...@suse.cz>
> Cc: linux-kernel@vger.kernel.org
> Cc: linux-...@vger.kernel.org
> Cc: intel-gfx <intel-...@lists.freedesktop.org>
> Cc: dri-devel <dri-de...@lists.freedesktop.org>
> Cc: Graham Whaley <graham.wha...@linux.intel.com>
> ---
>  Thanks to Graham Whaley who helped me to debug this.
> 
>  scripts/kernel-doc | 48 ++--
>  1 file changed, 34 insertions(+), 14 deletions(-)
> 
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 3850c1e..12a106c 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -288,6 +288,7 @@ my $use_markdown = 0;
>  my $verbose = 0;
>  my $output_mode = "man";
>  my $output_preformatted = 0;
> +my $output_markdown_nopara = 0;
>  my $no_doc_sections = 0;
>  my @highlights = @highlights_man;
>  my $blankline = $blankline_man;
> @@ -529,8 +530,11 @@ sub markdown_to_docbook {
>   close(CHLD_OUT);
>   close(CHLD_ERR);
>  
> - # pandoc insists in adding Main , we should remove them.
> - $content =~ s:\A\s*\s*\n(.*)\n\Z$:$1:egsm;
> + if ($output_markdown_nopara) {
> + # pandoc insists in adding Main , sometimes we
> + # want to remove them.
> + $content =~ s:\A\s*\s*\n(.*)\n\Z$:$1:egsm;
> + }
>  
>   return $content;
>  }
> @@ -605,7 +609,7 @@ sub output_highlight {
>   $line =~ s/^\s*//;
>   }
>   if ($line eq ""){
> - if (! $output_preformatted) {
> + if (! $output_preformatted && ! $use_markdown) {
>   print $lineprefix, local_unescape($blankline);
>   }
>   } else {
> @@ -1026,7 +1030,7 @@ sub output_section_xml(%) {
>   # programlisting is already included by pandoc
>   print "\n" unless $use_markdown;
>   $output_preformatted = 1;
> - } else {
> + } elsif (! $use_markdown) {
>   print "\n";
>   }
>   output_highlight($args{'sections'}{$section});
> @@ -1034,7 +1038,7 @@ sub output_section_xml(%) {
>   if ($section =~ m/EXAMPLE/i) {
>   print "\n" unless $use_markdown;
>   print "\n";
> - } else {
> + } elsif (! $use_markdown) {
>   print "\n";
>   }
>   print "\n";
> @@ -1066,7 +1070,9 @@ sub output_function_xml(%) {
>  print " " . $args{'function'} . "\n";
>  print " \n";
>  print "  ";
> +$output_markdown_nopara = 1;
>  output_highlight ($args{'purpose'});
> +$output_markdown_nopara = 0;
>  print " \n";
>  print "\n";
>  
> @@ -1104,10 +1110,12 @@ sub output_function_xml(%) {
>   $parameter_name =~ s/\[.*//;
>  
>   print "  \n   
> $parameter\n";
> - print "   \n\n";
> + print "   \n";
> + print "\n" unless $use_markdown;
>   $lineprefix=" ";
>   output_highlight($args{'parameterdescs'}{$parameter_name});
> - print "\n   \n  \n";
> + print "\n" unless $use_markdown;
> + print "   \n  \n";
>   }
>   print " \n";
>  } else {
> @@ -1143,7

[PATCH] drm/doc: Fixing xml documentation warning

[Danilo Cesar Lemes de Paula]

"/**" should be used for kernel-doc documentation only.
It causes a warning with the new "in struct body" format.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
Cc: Graham Whaley 
---
 include/drm/drm_modeset_lock.h | 10 +-
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/include/drm/drm_modeset_lock.h b/include/drm/drm_modeset_lock.h
index 70595ff..c16a3ec 100644
--- a/include/drm/drm_modeset_lock.h
+++ b/include/drm/drm_modeset_lock.h
@@ -43,19 +43,19 @@ struct drm_modeset_acquire_ctx {
 
struct ww_acquire_ctx ww_ctx;
 
-   /**
+   /*
 * Contended lock: if a lock is contended you should only call
 * drm_modeset_backoff() which drops locks and slow-locks the
 * contended lock.
 */
struct drm_modeset_lock *contended;
 
-   /**
+   /*
 * list of held locks (drm_modeset_lock)
 */
struct list_head locked;
 
-   /**
+   /*
 * Trylock mode, use only for panic handlers!
 */
bool trylock_only;
@@ -70,12 +70,12 @@ struct drm_modeset_acquire_ctx {
  * Used for locking CRTCs and other modeset resources.
  */
 struct drm_modeset_lock {
-   /**
+   /*
 * modeset lock
 */
struct ww_mutex mutex;
 
-   /**
+   /*
 * Resources that are locked as part of an atomic update are added
 * to a list (so we know what to unlock at the end).
 */
-- 
2.4.3

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

[PATCH] scripts/kernel-doc: Improve Markdown results

[Danilo Cesar Lemes de Paula]

Using pandoc as the Markdown engine cause some minor side effects as
pandoc includes  main  tags for almost everything.
Original Markdown support approach removes those main tags, but it caused
some inconsistencies when that tag is not the main one, like:
..
...

As kernel-doc was already including a  tag, it causes the presence
of double  tags (), which is not supported by DocBook
spec.

Html target gets away with it, so it causes no harm, although other
targets might not be so lucky (pdf as example).

We're now delegating the inclusion of the main  tag to pandoc
only, as it knows when it's necessary or not.

That behavior causes a corner case, the only situation where we're
certainly that  is not needed, which is the  content.
For those cases, we're using a $output_markdown_nopara = 1 control var.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
Cc: Graham Whaley 
---
 Thanks to Graham Whaley who helped me to debug this.

 scripts/kernel-doc | 48 ++--
 1 file changed, 34 insertions(+), 14 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 3850c1e..12a106c 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -288,6 +288,7 @@ my $use_markdown = 0;
 my $verbose = 0;
 my $output_mode = "man";
 my $output_preformatted = 0;
+my $output_markdown_nopara = 0;
 my $no_doc_sections = 0;
 my @highlights = @highlights_man;
 my $blankline = $blankline_man;
@@ -529,8 +530,11 @@ sub markdown_to_docbook {
close(CHLD_OUT);
close(CHLD_ERR);
 
-   # pandoc insists in adding Main , we should remove them.
-   $content =~ s:\A\s*\s*\n(.*)\n\Z$:$1:egsm;
+   if ($output_markdown_nopara) {
+   # pandoc insists in adding Main , sometimes we
+   # want to remove them.
+   $content =~ s:\A\s*\s*\n(.*)\n\Z$:$1:egsm;
+   }
 
return $content;
 }
@@ -605,7 +609,7 @@ sub output_highlight {
$line =~ s/^\s*//;
}
if ($line eq ""){
-   if (! $output_preformatted) {
+   if (! $output_preformatted && ! $use_markdown) {
print $lineprefix, local_unescape($blankline);
}
} else {
@@ -1026,7 +1030,7 @@ sub output_section_xml(%) {
# programlisting is already included by pandoc
print "\n" unless $use_markdown;
$output_preformatted = 1;
-   } else {
+   } elsif (! $use_markdown) {
print "\n";
}
output_highlight($args{'sections'}{$section});
@@ -1034,7 +1038,7 @@ sub output_section_xml(%) {
if ($section =~ m/EXAMPLE/i) {
print "\n" unless $use_markdown;
print "\n";
-   } else {
+   } elsif (! $use_markdown) {
print "\n";
}
print "\n";
@@ -1066,7 +1070,9 @@ sub output_function_xml(%) {
 print " " . $args{'function'} . "\n";
 print " \n";
 print "  ";
+$output_markdown_nopara = 1;
 output_highlight ($args{'purpose'});
+$output_markdown_nopara = 0;
 print " \n";
 print "\n";
 
@@ -1104,10 +1110,12 @@ sub output_function_xml(%) {
$parameter_name =~ s/\[.*//;
 
print "  \n   
$parameter\n";
-   print "   \n\n";
+   print "   \n";
+   print "\n" unless $use_markdown;
$lineprefix=" ";
output_highlight($args{'parameterdescs'}{$parameter_name});
-   print "\n   \n  \n";
+   print "\n" unless $use_markdown;
+   print "   \n  \n";
}
print " \n";
 } else {
@@ -1143,7 +1151,9 @@ sub output_struct_xml(%) {
 print " " . $args{'type'} . " " . $args{'struct'} . 
"\n";
 print " \n";
 print "  ";
+$output_markdown_nopara = 1;
 output_highlight ($args{'purpose'});
+$output_markdown_nopara = 0;
 print " \n";
 print "\n";
 
@@ -1196,9 +1206,11 @@ sub output_struct_xml(%) {
   ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
   print "";
   print "  $parameter\n";
-  print "  \n";
+  print "  \n";
+  print " \n" unless $use_markdown;
   output_highlight($args{'parameterdescs'}{$parameter_name});
-  print "  \n";
+  print " \n" unless $use_markdown;
+  print "  \n";
   print "\n";
 }
 print &

[PATCH] scripts/kernel-doc: Improve Markdown results

[Danilo Cesar Lemes de Paula]

Using pandoc as the Markdown engine cause some minor side effects as
pandoc includes  main para tags for almost everything.
Original Markdown support approach removes those main tags, but it caused
some inconsistencies when that tag is not the main one, like:
something../something
para.../para

As kernel-doc was already including a para tag, it causes the presence
of double para tags (parapara), which is not supported by DocBook
spec.

Html target gets away with it, so it causes no harm, although other
targets might not be so lucky (pdf as example).

We're now delegating the inclusion of the main para tag to pandoc
only, as it knows when it's necessary or not.

That behavior causes a corner case, the only situation where we're
certainly that para is not needed, which is the refpurpose content.
For those cases, we're using a $output_markdown_nopara = 1 control var.

Signed-off-by: Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk
Cc: Randy Dunlap rdun...@infradead.org
Cc: Daniel Vetter daniel.vet...@ffwll.ch
Cc: Laurent Pinchart laurent.pinch...@ideasonboard.com
Cc: Jonathan Corbet cor...@lwn.net
Cc: Herbert Xu herb...@gondor.apana.org.au
Cc: Stephan Mueller smuel...@chronox.de
Cc: Michal Marek mma...@suse.cz
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx intel-...@lists.freedesktop.org
Cc: dri-devel dri-de...@lists.freedesktop.org
Cc: Graham Whaley graham.wha...@linux.intel.com
---
 Thanks to Graham Whaley who helped me to debug this.

 scripts/kernel-doc | 48 ++--
 1 file changed, 34 insertions(+), 14 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 3850c1e..12a106c 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -288,6 +288,7 @@ my $use_markdown = 0;
 my $verbose = 0;
 my $output_mode = man;
 my $output_preformatted = 0;
+my $output_markdown_nopara = 0;
 my $no_doc_sections = 0;
 my @highlights = @highlights_man;
 my $blankline = $blankline_man;
@@ -529,8 +530,11 @@ sub markdown_to_docbook {
close(CHLD_OUT);
close(CHLD_ERR);
 
-   # pandoc insists in adding Main para/para, we should remove them.
-   $content =~ s:\A\s*para\s*\n(.*)\n/para\Z$:$1:egsm;
+   if ($output_markdown_nopara) {
+   # pandoc insists in adding Main para/para, sometimes we
+   # want to remove them.
+   $content =~ s:\A\s*para\s*\n(.*)\n/para\Z$:$1:egsm;
+   }
 
return $content;
 }
@@ -605,7 +609,7 @@ sub output_highlight {
$line =~ s/^\s*//;
}
if ($line eq ){
-   if (! $output_preformatted) {
+   if (! $output_preformatted  ! $use_markdown) {
print $lineprefix, local_unescape($blankline);
}
} else {
@@ -1026,7 +1030,7 @@ sub output_section_xml(%) {
# programlisting is already included by pandoc
print programlisting\n unless $use_markdown;
$output_preformatted = 1;
-   } else {
+   } elsif (! $use_markdown) {
print para\n;
}
output_highlight($args{'sections'}{$section});
@@ -1034,7 +1038,7 @@ sub output_section_xml(%) {
if ($section =~ m/EXAMPLE/i) {
print /programlisting\n unless $use_markdown;
print /informalexample\n;
-   } else {
+   } elsif (! $use_markdown) {
print /para\n;
}
print /refsect1\n;
@@ -1066,7 +1070,9 @@ sub output_function_xml(%) {
 print  refname . $args{'function'} . /refname\n;
 print  refpurpose\n;
 print   ;
+$output_markdown_nopara = 1;
 output_highlight ($args{'purpose'});
+$output_markdown_nopara = 0;
 print  /refpurpose\n;
 print /refnamediv\n;
 
@@ -1104,10 +1110,12 @@ sub output_function_xml(%) {
$parameter_name =~ s/\[.*//;
 
print   varlistentry\n   
termparameter$parameter/parameter/term\n;
-   printlistitem\npara\n;
+   printlistitem\n;
+   print para\n unless $use_markdown;
$lineprefix= ;
output_highlight($args{'parameterdescs'}{$parameter_name});
-   print /para\n   /listitem\n  /varlistentry\n;
+   print /para\n unless $use_markdown;
+   print/listitem\n  /varlistentry\n;
}
print  /variablelist\n;
 } else {
@@ -1143,7 +1151,9 @@ sub output_struct_xml(%) {
 print  refname . $args{'type'} .   . $args{'struct'} . 
/refname\n;
 print  refpurpose\n;
 print   ;
+$output_markdown_nopara = 1;
 output_highlight ($args{'purpose'});
+$output_markdown_nopara = 0;
 print  /refpurpose\n;
 print /refnamediv\n;
 
@@ -1196,9 +1206,11 @@ sub output_struct_xml(%) {
   ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
   print varlistentry;
   print   term$parameter/term\n;
-  print   listitempara\n;
+  print   listitem\n;
+  print  para

[PATCH] drm/doc: Fixing xml documentation warning

[Danilo Cesar Lemes de Paula]

/** should be used for kernel-doc documentation only.
It causes a warning with the new in struct body format.

Signed-off-by: Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk
Cc: Randy Dunlap rdun...@infradead.org
Cc: Daniel Vetter daniel.vet...@ffwll.ch
Cc: Laurent Pinchart laurent.pinch...@ideasonboard.com
Cc: Jonathan Corbet cor...@lwn.net
Cc: Herbert Xu herb...@gondor.apana.org.au
Cc: Stephan Mueller smuel...@chronox.de
Cc: Michal Marek mma...@suse.cz
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx intel-...@lists.freedesktop.org
Cc: dri-devel dri-de...@lists.freedesktop.org
Cc: Graham Whaley graham.wha...@linux.intel.com
---
 include/drm/drm_modeset_lock.h | 10 +-
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/include/drm/drm_modeset_lock.h b/include/drm/drm_modeset_lock.h
index 70595ff..c16a3ec 100644
--- a/include/drm/drm_modeset_lock.h
+++ b/include/drm/drm_modeset_lock.h
@@ -43,19 +43,19 @@ struct drm_modeset_acquire_ctx {
 
struct ww_acquire_ctx ww_ctx;
 
-   /**
+   /*
 * Contended lock: if a lock is contended you should only call
 * drm_modeset_backoff() which drops locks and slow-locks the
 * contended lock.
 */
struct drm_modeset_lock *contended;
 
-   /**
+   /*
 * list of held locks (drm_modeset_lock)
 */
struct list_head locked;
 
-   /**
+   /*
 * Trylock mode, use only for panic handlers!
 */
bool trylock_only;
@@ -70,12 +70,12 @@ struct drm_modeset_acquire_ctx {
  * Used for locking CRTCs and other modeset resources.
  */
 struct drm_modeset_lock {
-   /**
+   /*
 * modeset lock
 */
struct ww_mutex mutex;
 
-   /**
+   /*
 * Resources that are locked as part of an atomic update are added
 * to a list (so we know what to unlock at the end).
 */
-- 
2.4.3

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

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

[Danilo Cesar Lemes de Paula]

On 08/17/2015 01:10 AM, Jonathan Corbet wrote:
> On Tue, 28 Jul 2015 16:45:15 -0300
> Danilo Cesar Lemes de Paula  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  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  from the DocBook XML to generate a database. Then it looks
>> for , and  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 majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

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

[Danilo Cesar Lemes de Paula]

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.ce...@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 majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

Re: [PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc

[Danilo Cesar Lemes de Paula]

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

Re: [PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc

[Danilo Cesar Lemes de Paula]

On 08/13/2015 08:20 PM, Jonathan Corbet wrote:
 On Thu, 13 Aug 2015 20:09:35 -0300
 Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk 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
--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

Re: [PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc

[Danilo Cesar Lemes de Paula]

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

Re: [PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc

[Danilo Cesar Lemes de Paula]

On 07/23/2015 05:29 PM, Jonathan Corbet wrote:
 On Thu, 23 Jul 2015 15:16:23 -0300
 Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk 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
--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[PATCH v2] scripts/kernel-doc Allow struct arguments documentation in struct body

[Danilo Cesar Lemes de Paula]

Describing arguments at top of a struct definition works fine
for small/medium size structs, but it definitely doesn't work well
for struct with a huge list of elements.

Keeping the arguments list inside the struct body makes it easier
to maintain the documentation.
ie:
/**
 * struct my_struct - short description
 * @a: first member
 * @b: second member
 *
 * Longer description
 */
struct my_struct {
int a;
int b;
/**
 * @c: This is longer description of C
 *
 * You can use paragraphs to describe arguments
 * using this method.
 */
int c;
};

This patch allows the use of this kind of syntax. Only one argument
per comment and user can use how many paragraphs he needs. It should
start with /**, which is already being used by kernel-doc. If those
comment doesn't follow those rules, it will be ignored.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 Changelog:
  v2:
 - Fixed comment typo
 - Fixed identantion by following the rest of the kernel-doc script pattern.
 - Improved usage comment.

 scripts/kernel-doc | 77 --
 1 file changed, 75 insertions(+), 2 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9922e66..5adc7ee 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -133,6 +133,30 @@ use strict;
 #
 # All descriptions can be multiline, except the short function description.
 #
+# For really longs structs, you can also describe arguments inside the
+# body of the struct.
+# eg.
+# /**
+#  * struct my_struct - short description
+#  * @a: first member
+#  * @b: second member
+#  *
+#  * Longer description
+#  */
+# struct my_struct {
+# int a;
+# int b;
+# /**
+#  * @c: This is longer description of C
+#  *
+#  * You can use paragraphs to describe arguments
+#  * using this method.
+#  */
+# int c;
+# };
+#
+# This should be use only for struct/enum members.
+#
 # You can also add additional sections. When documenting kernel functions you
 # should document the "Context:" of the function, e.g. whether the functions
 # can be called form interrupts. Unlike other sections you can end it with an
@@ -287,9 +311,19 @@ my $lineprefix="";
 # 2 - scanning field start.
 # 3 - scanning prototype.
 # 4 - documentation block
+# 5 - gathering documentation outside main block
 my $state;
 my $in_doc_sect;
 
+# Split Doc State
+# 0 - Invalid (Before start or after finish)
+# 1 - Is started (the /** was found inside a struct)
+# 2 - The @parameter header was found, start accepting multi paragraph text.
+# 3 - Finished (the */ was found)
+# 4 - Error - Comment without header was found. Spit a warning as it's not
+# proper kernel-doc and ignore the rest.
+my $split_doc_state;
+
 #declaration types: can be
 # 'function', 'struct', 'union', 'enum', 'typedef'
 my $decl_type;
@@ -304,6 +338,9 @@ my $doc_decl = $doc_com . '(\w+)';
 my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
+my $doc_split_start = '^\s*/\*\*\s*$';
+my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
+my $doc_split_end = '^\s*\*/\s*$';
 
 my %constants;
 my %parameterdescs;
@@ -2181,6 +2218,7 @@ sub reset_state {
 $prototype = "";
 
 $state = 0;
+$split_doc_state = 0;
 }
 
 sub tracepoint_munge($) {
@@ -2453,7 +2491,6 @@ sub process_file($) {
}
$section = $newsection;
} elsif (/$doc_end/) {
-
if (($contents ne "") && ($contents ne "\n")) {
dump_section($file, $section, xml_escape($contents));
$section = $section_default;
@@ -2494,8 +2531,44 @@ sub process_file($) {
print STDERR "Warning(${file}:$.): bad line: $_";
++$warnings;
}
+   } elsif ($state == 5) { # scanning for split parameters
+   # First line (state 1) needs to be a @parameter
+   if ($split_doc_state == 1 && /$doc_split_sect/o) {
+   $section = $1;
+   $contents = $2;
+   if ($contents ne "") {
+   while ((substr($contents, 0, 1) eq " ") ||
+  substr($contents, 0, 1) eq "\t") {
+   $contents = substr($contents, 1);
+   }
+   $contents .= "\n";
+   }
+   $split_doc_state = 2;
+   # Documentation block end */
+   } elsif (/$doc_split_end/) {
+   if (($contents ne "") && ($contents ne "\n")) {
+   

[PATCH v2] scripts/kernel-doc Allow struct arguments documentation in struct body

[Danilo Cesar Lemes de Paula]

Describing arguments at top of a struct definition works fine
for small/medium size structs, but it definitely doesn't work well
for struct with a huge list of elements.

Keeping the arguments list inside the struct body makes it easier
to maintain the documentation.
ie:
/**
 * struct my_struct - short description
 * @a: first member
 * @b: second member
 *
 * Longer description
 */
struct my_struct {
int a;
int b;
/**
 * @c: This is longer description of C
 *
 * You can use paragraphs to describe arguments
 * using this method.
 */
int c;
};

This patch allows the use of this kind of syntax. Only one argument
per comment and user can use how many paragraphs he needs. It should
start with /**, which is already being used by kernel-doc. If those
comment doesn't follow those rules, it will be ignored.

Signed-off-by: Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk
Cc: Randy Dunlap rdun...@infradead.org
Cc: Daniel Vetter daniel.vet...@ffwll.ch
Cc: Laurent Pinchart laurent.pinch...@ideasonboard.com
Cc: Jonathan Corbet cor...@lwn.net
Cc: Herbert Xu herb...@gondor.apana.org.au
Cc: Stephan Mueller smuel...@chronox.de
Cc: Michal Marek mma...@suse.cz
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx intel-...@lists.freedesktop.org
Cc: dri-devel dri-de...@lists.freedesktop.org
---
 Changelog:
  v2:
 - Fixed comment typo
 - Fixed identantion by following the rest of the kernel-doc script pattern.
 - Improved usage comment.

 scripts/kernel-doc | 77 --
 1 file changed, 75 insertions(+), 2 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9922e66..5adc7ee 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -133,6 +133,30 @@ use strict;
 #
 # All descriptions can be multiline, except the short function description.
 #
+# For really longs structs, you can also describe arguments inside the
+# body of the struct.
+# eg.
+# /**
+#  * struct my_struct - short description
+#  * @a: first member
+#  * @b: second member
+#  *
+#  * Longer description
+#  */
+# struct my_struct {
+# int a;
+# int b;
+# /**
+#  * @c: This is longer description of C
+#  *
+#  * You can use paragraphs to describe arguments
+#  * using this method.
+#  */
+# int c;
+# };
+#
+# This should be use only for struct/enum members.
+#
 # You can also add additional sections. When documenting kernel functions you
 # should document the Context: of the function, e.g. whether the functions
 # can be called form interrupts. Unlike other sections you can end it with an
@@ -287,9 +311,19 @@ my $lineprefix=;
 # 2 - scanning field start.
 # 3 - scanning prototype.
 # 4 - documentation block
+# 5 - gathering documentation outside main block
 my $state;
 my $in_doc_sect;
 
+# Split Doc State
+# 0 - Invalid (Before start or after finish)
+# 1 - Is started (the /** was found inside a struct)
+# 2 - The @parameter header was found, start accepting multi paragraph text.
+# 3 - Finished (the */ was found)
+# 4 - Error - Comment without header was found. Spit a warning as it's not
+# proper kernel-doc and ignore the rest.
+my $split_doc_state;
+
 #declaration types: can be
 # 'function', 'struct', 'union', 'enum', 'typedef'
 my $decl_type;
@@ -304,6 +338,9 @@ my $doc_decl = $doc_com . '(\w+)';
 my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
+my $doc_split_start = '^\s*/\*\*\s*$';
+my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
+my $doc_split_end = '^\s*\*/\s*$';
 
 my %constants;
 my %parameterdescs;
@@ -2181,6 +2218,7 @@ sub reset_state {
 $prototype = ;
 
 $state = 0;
+$split_doc_state = 0;
 }
 
 sub tracepoint_munge($) {
@@ -2453,7 +2491,6 @@ sub process_file($) {
}
$section = $newsection;
} elsif (/$doc_end/) {
-
if (($contents ne )  ($contents ne \n)) {
dump_section($file, $section, xml_escape($contents));
$section = $section_default;
@@ -2494,8 +2531,44 @@ sub process_file($) {
print STDERR Warning(${file}:$.): bad line: $_;
++$warnings;
}
+   } elsif ($state == 5) { # scanning for split parameters
+   # First line (state 1) needs to be a @parameter
+   if ($split_doc_state == 1  /$doc_split_sect/o) {
+   $section = $1;
+   $contents = $2;
+   if ($contents ne ) {
+   while ((substr($contents, 0, 1) eq  ) ||
+  substr($contents, 0, 1) eq \t) {
+   $contents = substr($contents, 1);
+   }
+   $contents .= \n;
+   }
+   $split_doc_state = 2;
+   # Documentation block end */
+   } elsif (/$doc_split_end

Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body

[Danilo Cesar Lemes de Paula]

On 08/03/2015 12:59 PM, Randy Dunlap wrote:
> On 07/31/15 14:06, Danilo Cesar Lemes de Paula wrote:
>> Describing arguments at top of a struct definition works fine
>> for small/medium size structs, but it definitely doesn't work well
>> for struct with a huge list of elements.
>>
>> Keeping the arguments list inside the struct body makes it easier
>> to maintain the documentation.
>> ie:
>> /**
>>  * struct my_struct - short description
>>  * @a: first member
>>  * @b: second member
>>  *
>>  * Longer description
>>  */
>> struct my_struct {
>> int a;
>> int b;
>> /**
>>  * @c: This is longer description of C
>>  *
>>  * You can use paragraphs to describe arguments
>>  * using this method.
>>  */
>> int c;
>> };
>>
>> This patch allows the use of this kind of syntax. Only one argument
>> per comment and user can use how many paragraphs he needs. It should
>> start with /**, which is already being used by kernel-doc. If those
>> comment doesn't follow those rules, it will be ignored.
>>
>> Signed-off-by: Danilo Cesar Lemes de Paula 
>> Cc: Randy Dunlap 
>> Cc: Daniel Vetter 
>> Cc: Laurent Pinchart 
>> Cc: Jonathan Corbet 
>> Cc: Herbert Xu 
>> Cc: Stephan Mueller 
>> Cc: Michal Marek 
>> Cc: linux-kernel@vger.kernel.org
>> Cc: linux-...@vger.kernel.org
>> Cc: intel-gfx 
>> Cc: dri-devel 
>> ---
>>  scripts/kernel-doc | 80 
>> --
>>  1 file changed, 78 insertions(+), 2 deletions(-)
>>
>> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
>> index 9922e66..9bfa8b9 100755
>> --- a/scripts/kernel-doc
>> +++ b/scripts/kernel-doc
>> @@ -133,6 +133,30 @@ use strict;
>>  #
>>  # All descriptions can be multiline, except the short function description.
>>  #
>> +# For really longs structs, you can also describe arguments inside the
>> +# body of the struct.
>> +# eg.
>> +# /**
>> +#  * struct my_struct - short description
>> +#  * @a: first member
>> +#  * @b: second member
>> +#  *
>> +#  * Longer description
>> +#  */
>> +# struct my_struct {
>> +# int a;
>> +# int b;
>> +# /**
>> +#  * @c: This is longer description of C
>> +#  *
>> +#  * You can use paragraphs to describe arguments
>> +#  * using this method.
>> +#  */
>> +# int c;
>> +# };
>> +#
>> +# This should be use for arguments only.
> 
> used
> 
> What are "arguments" in this context?  do you mean struct fields or members?

Yes. I can change the text if you want to.

> 
>> +#
>>  # You can also add additional sections. When documenting kernel functions 
>> you
>>  # should document the "Context:" of the function, e.g. whether the functions
>>  # can be called form interrupts. Unlike other sections you can end it with 
>> an
>> @@ -287,9 +311,19 @@ my $lineprefix="";
>>  # 2 - scanning field start.
>>  # 3 - scanning prototype.
>>  # 4 - documentation block
>> +# 5 - gathering documentation outside main block
>>  my $state;
>>  my $in_doc_sect;
>>  
>> +# Split Doc State
>> +# 0 - Invalid (Before start or after finish)
>> +# 1 - Is started (the /** was found inside a struct)
>> +# 2 - The @parameter header was found, start accepting multi paragraph text.
>> +# 3 - Finished (the */ was found)
>> +# 4 - Error - Comment without header was found. Spit a warning as it's not
>> +# proper kernel-doc and ignore the rest.
>> +my $split_doc_state;
>> +
>>  #declaration types: can be
>>  # 'function', 'struct', 'union', 'enum', 'typedef'
>>  my $decl_type;
>> @@ -304,6 +338,9 @@ my $doc_decl = $doc_com . '(\w+)';
>>  my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
>>  my $doc_content = $doc_com_body . '(.*)';
>>  my $doc_block = $doc_com . 'DOC:\s*(.*)?';
>> +my $doc_split_start = '^\s*/\*\*\s*$';
>> +my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
>> +my $doc_split_end = '^\s*\*/\s*$';
>>  
>>  my %constants;
>>  my %parameterdescs;
>> @@ -2181,6 +2218,7 @@ sub reset_state {
>>  $prototype = "";
>>  
>>  $state = 0;
>> +$split_doc_state = 0;
>>  }
>>  
>>  sub tracepoint_munge($) {
>> @@ -2453,7 +2491,6 @@ sub process_file($) {
>>  }
>>  $section 

Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body

[Danilo Cesar Lemes de Paula]

On 08/03/2015 12:59 PM, Randy Dunlap wrote:
 On 07/31/15 14:06, Danilo Cesar Lemes de Paula wrote:
 Describing arguments at top of a struct definition works fine
 for small/medium size structs, but it definitely doesn't work well
 for struct with a huge list of elements.

 Keeping the arguments list inside the struct body makes it easier
 to maintain the documentation.
 ie:
 /**
  * struct my_struct - short description
  * @a: first member
  * @b: second member
  *
  * Longer description
  */
 struct my_struct {
 int a;
 int b;
 /**
  * @c: This is longer description of C
  *
  * You can use paragraphs to describe arguments
  * using this method.
  */
 int c;
 };

 This patch allows the use of this kind of syntax. Only one argument
 per comment and user can use how many paragraphs he needs. It should
 start with /**, which is already being used by kernel-doc. If those
 comment doesn't follow those rules, it will be ignored.

 Signed-off-by: Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk
 Cc: Randy Dunlap rdun...@infradead.org
 Cc: Daniel Vetter daniel.vet...@ffwll.ch
 Cc: Laurent Pinchart laurent.pinch...@ideasonboard.com
 Cc: Jonathan Corbet cor...@lwn.net
 Cc: Herbert Xu herb...@gondor.apana.org.au
 Cc: Stephan Mueller smuel...@chronox.de
 Cc: Michal Marek mma...@suse.cz
 Cc: linux-kernel@vger.kernel.org
 Cc: linux-...@vger.kernel.org
 Cc: intel-gfx intel-...@lists.freedesktop.org
 Cc: dri-devel dri-de...@lists.freedesktop.org
 ---
  scripts/kernel-doc | 80 
 --
  1 file changed, 78 insertions(+), 2 deletions(-)

 diff --git a/scripts/kernel-doc b/scripts/kernel-doc
 index 9922e66..9bfa8b9 100755
 --- a/scripts/kernel-doc
 +++ b/scripts/kernel-doc
 @@ -133,6 +133,30 @@ use strict;
  #
  # All descriptions can be multiline, except the short function description.
  #
 +# For really longs structs, you can also describe arguments inside the
 +# body of the struct.
 +# eg.
 +# /**
 +#  * struct my_struct - short description
 +#  * @a: first member
 +#  * @b: second member
 +#  *
 +#  * Longer description
 +#  */
 +# struct my_struct {
 +# int a;
 +# int b;
 +# /**
 +#  * @c: This is longer description of C
 +#  *
 +#  * You can use paragraphs to describe arguments
 +#  * using this method.
 +#  */
 +# int c;
 +# };
 +#
 +# This should be use for arguments only.
 
 used
 
 What are arguments in this context?  do you mean struct fields or members?

Yes. I can change the text if you want to.

 
 +#
  # You can also add additional sections. When documenting kernel functions 
 you
  # should document the Context: of the function, e.g. whether the functions
  # can be called form interrupts. Unlike other sections you can end it with 
 an
 @@ -287,9 +311,19 @@ my $lineprefix=;
  # 2 - scanning field start.
  # 3 - scanning prototype.
  # 4 - documentation block
 +# 5 - gathering documentation outside main block
  my $state;
  my $in_doc_sect;
  
 +# Split Doc State
 +# 0 - Invalid (Before start or after finish)
 +# 1 - Is started (the /** was found inside a struct)
 +# 2 - The @parameter header was found, start accepting multi paragraph text.
 +# 3 - Finished (the */ was found)
 +# 4 - Error - Comment without header was found. Spit a warning as it's not
 +# proper kernel-doc and ignore the rest.
 +my $split_doc_state;
 +
  #declaration types: can be
  # 'function', 'struct', 'union', 'enum', 'typedef'
  my $decl_type;
 @@ -304,6 +338,9 @@ my $doc_decl = $doc_com . '(\w+)';
  my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
  my $doc_content = $doc_com_body . '(.*)';
  my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 +my $doc_split_start = '^\s*/\*\*\s*$';
 +my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
 +my $doc_split_end = '^\s*\*/\s*$';
  
  my %constants;
  my %parameterdescs;
 @@ -2181,6 +2218,7 @@ sub reset_state {
  $prototype = ;
  
  $state = 0;
 +$split_doc_state = 0;
  }
  
  sub tracepoint_munge($) {
 @@ -2453,7 +2491,6 @@ sub process_file($) {
  }
  $section = $newsection;
  } elsif (/$doc_end/) {
 -
  if (($contents ne )  ($contents ne \n)) {
  dump_section($file, $section, xml_escape($contents));
  $section = $section_default;
 @@ -2494,8 +2531,47 @@ sub process_file($) {
  print STDERR Warning(${file}:$.): bad line: $_;
  ++$warnings;
  }
 +} elsif ($state == 5) { # scanning for split parameters
 +
 +# First line (state 1) needs to be a @parameter
 +if ($split_doc_state == 1  /$doc_split_sect/o) {
 +$section = $1;
 +$contents = $2;
 +if ($contents ne ) {
 +while ((substr($contents, 0, 1) eq  ) ||
 +substr($contents, 0, 1) eq \t) {
 +$contents = substr($contents, 1

[PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body

[Danilo Cesar Lemes de Paula]

Describing arguments at top of a struct definition works fine
for small/medium size structs, but it definitely doesn't work well
for struct with a huge list of elements.

Keeping the arguments list inside the struct body makes it easier
to maintain the documentation.
ie:
/**
 * struct my_struct - short description
 * @a: first member
 * @b: second member
 *
 * Longer description
 */
struct my_struct {
int a;
int b;
/**
 * @c: This is longer description of C
 *
 * You can use paragraphs to describe arguments
 * using this method.
 */
int c;
};

This patch allows the use of this kind of syntax. Only one argument
per comment and user can use how many paragraphs he needs. It should
start with /**, which is already being used by kernel-doc. If those
comment doesn't follow those rules, it will be ignored.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 scripts/kernel-doc | 80 --
 1 file changed, 78 insertions(+), 2 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9922e66..9bfa8b9 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -133,6 +133,30 @@ use strict;
 #
 # All descriptions can be multiline, except the short function description.
 #
+# For really longs structs, you can also describe arguments inside the
+# body of the struct.
+# eg.
+# /**
+#  * struct my_struct - short description
+#  * @a: first member
+#  * @b: second member
+#  *
+#  * Longer description
+#  */
+# struct my_struct {
+# int a;
+# int b;
+# /**
+#  * @c: This is longer description of C
+#  *
+#  * You can use paragraphs to describe arguments
+#  * using this method.
+#  */
+# int c;
+# };
+#
+# This should be use for arguments only.
+#
 # You can also add additional sections. When documenting kernel functions you
 # should document the "Context:" of the function, e.g. whether the functions
 # can be called form interrupts. Unlike other sections you can end it with an
@@ -287,9 +311,19 @@ my $lineprefix="";
 # 2 - scanning field start.
 # 3 - scanning prototype.
 # 4 - documentation block
+# 5 - gathering documentation outside main block
 my $state;
 my $in_doc_sect;
 
+# Split Doc State
+# 0 - Invalid (Before start or after finish)
+# 1 - Is started (the /** was found inside a struct)
+# 2 - The @parameter header was found, start accepting multi paragraph text.
+# 3 - Finished (the */ was found)
+# 4 - Error - Comment without header was found. Spit a warning as it's not
+# proper kernel-doc and ignore the rest.
+my $split_doc_state;
+
 #declaration types: can be
 # 'function', 'struct', 'union', 'enum', 'typedef'
 my $decl_type;
@@ -304,6 +338,9 @@ my $doc_decl = $doc_com . '(\w+)';
 my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
+my $doc_split_start = '^\s*/\*\*\s*$';
+my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
+my $doc_split_end = '^\s*\*/\s*$';
 
 my %constants;
 my %parameterdescs;
@@ -2181,6 +2218,7 @@ sub reset_state {
 $prototype = "";
 
 $state = 0;
+$split_doc_state = 0;
 }
 
 sub tracepoint_munge($) {
@@ -2453,7 +2491,6 @@ sub process_file($) {
}
$section = $newsection;
} elsif (/$doc_end/) {
-
if (($contents ne "") && ($contents ne "\n")) {
dump_section($file, $section, xml_escape($contents));
$section = $section_default;
@@ -2494,8 +2531,47 @@ sub process_file($) {
print STDERR "Warning(${file}:$.): bad line: $_";
++$warnings;
}
+   } elsif ($state == 5) { # scanning for split parameters
+
+   # First line (state 1) needs to be a @parameter
+   if ($split_doc_state == 1 && /$doc_split_sect/o) {
+   $section = $1;
+   $contents = $2;
+   if ($contents ne "") {
+   while ((substr($contents, 0, 1) eq " ") ||
+   substr($contents, 0, 1) eq "\t") {
+   $contents = substr($contents, 1);
+   }
+   $contents .= "\n";
+   }
+   $split_doc_state = 2;
+
+   # End commend */
+   } elsif (/$doc_split_end/) {
+   if (($contents ne "") && ($contents ne "\n")) {
+   dump_section($file, $section, xml_escape($contents));
+   $section = $section_default;
+   $contents = "&

[PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body

[Danilo Cesar Lemes de Paula]

Describing arguments at top of a struct definition works fine
for small/medium size structs, but it definitely doesn't work well
for struct with a huge list of elements.

Keeping the arguments list inside the struct body makes it easier
to maintain the documentation.
ie:
/**
 * struct my_struct - short description
 * @a: first member
 * @b: second member
 *
 * Longer description
 */
struct my_struct {
int a;
int b;
/**
 * @c: This is longer description of C
 *
 * You can use paragraphs to describe arguments
 * using this method.
 */
int c;
};

This patch allows the use of this kind of syntax. Only one argument
per comment and user can use how many paragraphs he needs. It should
start with /**, which is already being used by kernel-doc. If those
comment doesn't follow those rules, it will be ignored.

Signed-off-by: Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk
Cc: Randy Dunlap rdun...@infradead.org
Cc: Daniel Vetter daniel.vet...@ffwll.ch
Cc: Laurent Pinchart laurent.pinch...@ideasonboard.com
Cc: Jonathan Corbet cor...@lwn.net
Cc: Herbert Xu herb...@gondor.apana.org.au
Cc: Stephan Mueller smuel...@chronox.de
Cc: Michal Marek mma...@suse.cz
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx intel-...@lists.freedesktop.org
Cc: dri-devel dri-de...@lists.freedesktop.org
---
 scripts/kernel-doc | 80 --
 1 file changed, 78 insertions(+), 2 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9922e66..9bfa8b9 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -133,6 +133,30 @@ use strict;
 #
 # All descriptions can be multiline, except the short function description.
 #
+# For really longs structs, you can also describe arguments inside the
+# body of the struct.
+# eg.
+# /**
+#  * struct my_struct - short description
+#  * @a: first member
+#  * @b: second member
+#  *
+#  * Longer description
+#  */
+# struct my_struct {
+# int a;
+# int b;
+# /**
+#  * @c: This is longer description of C
+#  *
+#  * You can use paragraphs to describe arguments
+#  * using this method.
+#  */
+# int c;
+# };
+#
+# This should be use for arguments only.
+#
 # You can also add additional sections. When documenting kernel functions you
 # should document the Context: of the function, e.g. whether the functions
 # can be called form interrupts. Unlike other sections you can end it with an
@@ -287,9 +311,19 @@ my $lineprefix=;
 # 2 - scanning field start.
 # 3 - scanning prototype.
 # 4 - documentation block
+# 5 - gathering documentation outside main block
 my $state;
 my $in_doc_sect;
 
+# Split Doc State
+# 0 - Invalid (Before start or after finish)
+# 1 - Is started (the /** was found inside a struct)
+# 2 - The @parameter header was found, start accepting multi paragraph text.
+# 3 - Finished (the */ was found)
+# 4 - Error - Comment without header was found. Spit a warning as it's not
+# proper kernel-doc and ignore the rest.
+my $split_doc_state;
+
 #declaration types: can be
 # 'function', 'struct', 'union', 'enum', 'typedef'
 my $decl_type;
@@ -304,6 +338,9 @@ my $doc_decl = $doc_com . '(\w+)';
 my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
+my $doc_split_start = '^\s*/\*\*\s*$';
+my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
+my $doc_split_end = '^\s*\*/\s*$';
 
 my %constants;
 my %parameterdescs;
@@ -2181,6 +2218,7 @@ sub reset_state {
 $prototype = ;
 
 $state = 0;
+$split_doc_state = 0;
 }
 
 sub tracepoint_munge($) {
@@ -2453,7 +2491,6 @@ sub process_file($) {
}
$section = $newsection;
} elsif (/$doc_end/) {
-
if (($contents ne )  ($contents ne \n)) {
dump_section($file, $section, xml_escape($contents));
$section = $section_default;
@@ -2494,8 +2531,47 @@ sub process_file($) {
print STDERR Warning(${file}:$.): bad line: $_;
++$warnings;
}
+   } elsif ($state == 5) { # scanning for split parameters
+
+   # First line (state 1) needs to be a @parameter
+   if ($split_doc_state == 1  /$doc_split_sect/o) {
+   $section = $1;
+   $contents = $2;
+   if ($contents ne ) {
+   while ((substr($contents, 0, 1) eq  ) ||
+   substr($contents, 0, 1) eq \t) {
+   $contents = substr($contents, 1);
+   }
+   $contents .= \n;
+   }
+   $split_doc_state = 2;
+
+   # End commend */
+   } elsif (/$doc_split_end/) {
+   if (($contents ne )  ($contents ne \n)) {
+   dump_section($file, $section, xml_escape($contents));
+   $section = $section_default

[PATCH v2 2/4] scripts/kernel-doc: Replacing highlights hash by an array

[Danilo Cesar Lemes de Paula]

The "highlight" code is very sensible to the order of the hash keys,
but the order of the keys cannot be predicted on Perl. It generates
faulty DocBook entries like:
- @device_for_each_child

We should use an array for that job, so we can guarantee that the order
of the regex execution on dohighlight won't change.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 Changelog:
v2: No changes

 scripts/kernel-doc | 104 ++---
 1 file changed, 60 insertions(+), 44 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9922e66..a38a69a 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -182,59 +182,73 @@ my $type_env = '(\$\w+)';
 #  One for each output format
 
 # these work fairly well
-my %highlights_html = ( $type_constant, "\$1",
-   $type_func, "\$1",
-   $type_struct_xml, "\$1",
-   $type_env, "\$1",
-   $type_param, "\$1" );
+my @highlights_html = (
+   [$type_constant, "\$1"],
+   [$type_func, "\$1"],
+   [$type_struct_xml, "\$1"],
+   [$type_env, "\$1"],
+   [$type_param, "\$1"]
+  );
 my $local_lt = "lt:";
 my $local_gt = "gt:";
 my $blankline_html = $local_lt . "p" . $local_gt;  # was ""
 
 # html version 5
-my %highlights_html5 = ( $type_constant, "\$1",
-   $type_func, "\$1",
-   $type_struct_xml, "\$1",
-   $type_env, "\$1",
-   $type_param, "\$1" );
+my @highlights_html5 = (
+[$type_constant, "\$1"],
+[$type_func, "\$1"],
+[$type_struct_xml, "\$1"],
+[$type_env, "\$1"],
+[$type_param, "\$1]"]
+  );
 my $blankline_html5 = $local_lt . "br /" . $local_gt;
 
 # XML, docbook format
-my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2",
-   $type_constant, "\$1",
-   $type_func, "\$1",
-   $type_struct_xml, "\$1",
-   $type_env, "\$1",
-   $type_param, "\$1" );
+my @highlights_xml = (
+  ["([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2"],
+  [$type_constant, "\$1"],
+  [$type_struct_xml, "\$1"],
+  [$type_param, "\$1"],
+  [$type_func, "\$1"],
+  [$type_env, "\$1"]
+);
 my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . 
$local_gt . "\n";
 
 # gnome, docbook format
-my %highlights_gnome = ( $type_constant, "\$1",
-$type_func, "\$1",
-$type_struct, "\$1",
-$type_env, "\$1",
-$type_param, "\$1" );
+my @highlights_gnome = (
+[$type_constant, "\$1"],
+[$type_func, "\$1"],
+[$type_struct, "\$1"],
+[$type_env, "\$1"],
+[$type_param, "\$1" ]
+  );
 my $blankline_gnome = "\n";
 
 # these are pretty rough
-my %highlights_man = ( $type_constant, "\$1",
-  $type_func, "fB\$1fP",
-  $type_struct, "fI\$1fP",
-  $type_param, "fI\$1fP" );
+my @highlights_man = (
+  [$type_constant, "\$1"],
+  [$type_func, "fB\$1fP"],
+  [$type_struct, "fI\$1fP"],
+  [$type_param, "fI\$1fP"]
+);
 my $blankline_man = "";
 
 # text-mode
-my %highlights_text = ( $type_constant, "\$1",
-   $type_func, "\$1",
-   $type_struct, "\$1",
-   $type_param, "\$1&q

[PATCH v2 3/4] scripts/kernel-doc: Adding infrastructure for markdown support

[Danilo Cesar Lemes de Paula]

Markdown support is given by calling an external tool, pandoc, for all
highlighted text on kernel-doc.

Pandoc converts Markdown text to proper Docbook tags, which will be
later translated to pdf, html or other targets.

This adds the capability of adding human-readle text highlight (bold,
underline, etc), bullet and numbered lists, simple tables, fixed-width
text (including asciiart), requiring minimal changes to current
documentation.

So, text using *must* will be rendered as must
inside DocBook and then must for HTML.
Bullet lists eg:
* Element 1
* Element 2
will also be converted to proper docbook/html lists.
Although it has the support for a good part of the markup language,
pandoc has some limitations and won't render tables with spanning cells
or headings. The use of those features are not recommended.

At this moment, pandoc is totally optional. Docbooks ready for markdown
should be added to the MARKDOWNREADY variable inside the Makefile. In
case the developer doesn't have pandoc installed, Make will throw a
warning and the documentation build will continue, generating
simple Documentation without the features brought by pandoc.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 Changelog:
  v2:
* Fix checkpatch issues.
* Improved commit message.
* Fixed dependency issue causing "make htmldocs" recalculate without
  any code change.

 Documentation/DocBook/Makefile | 25 +++-
 scripts/docproc.c  | 54 --
 scripts/kernel-doc | 66 --
 3 files changed, 119 insertions(+), 26 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 322255b..8e6d022 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -17,6 +17,8 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
tracepoint.xml drm.xml media_api.xml w1.xml \
writing_musb_glue_layer.xml crypto-API.xml
 
+MARKDOWNREADY :=
+
 include Documentation/DocBook/media/Makefile
 
 ###
@@ -79,18 +81,23 @@ XMLTOFLAGS += --skip-validation
 # The following rules are used to generate the .xml documentation
 # required to generate the final targets. (ps, pdf, html).
 quiet_cmd_docproc = DOCPROC $@
-  cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@
+  cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $<
 define rule_docproc
-   set -e; \
-$(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';)\
-$(cmd_$(1));   \
-(  \
-  echo 'cmd_$@ := $(cmd_$(1))';\
-  echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`;  \
+   set -e; 
\
+   USEMARKDOWN=""; 
\
+   FILE=`basename $@`; 
\
+   [[ "$(MARKDOWNREADY)" =~ "$${FILE}" ]] && USEMARKDOWN="-use-markdown";  
\
+$(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';)
\
+$(cmd_$(1)) $$USEMARKDOWN >$@; 
\
+(  
\
+  echo 'cmd_$@ := $(cmd_$(1))';
\
+  echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`;  
\
 ) > $(dir $@).$(notdir $@).cmd
 endef
 
 %.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
+   @(which pandoc > /dev/null 2>&1) || \
+   (echo "*** To get propper documentation you need to install pandoc 
***";)
$(call if_changed_rule,docproc)
 
 # Tell kbuild to always build the programs
@@ -101,6 +108,10 @@ notfoundtemplate = echo "*** You have to install 
docbook-utils or xmlto ***"; \
 db2xtemplate = db2TYPE -o $(dir $@) $<
 xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
 
+ifneq ($(shell which pandoc >/dev/null 2>&1 && echo found),found)
+   MARKDOWNREADY := "";
+endif
+
 # determine which methods are available
 ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
use-db2x = db2x
diff --git a/scripts/docproc.c b/scripts/docproc.c
index e267e621..7c6b225 100644
--- a/scripts/docproc.c
+++ b/scripts/docproc.c
@@ -73,12 +73,15 @@ FILELINE * docsection;
 #define NOF

[PATCH v2 4/4] drm/doc: Convert to markdown

[Danilo Cesar Lemes de Paula]

DRM Docbook is now Markdown ready. This means its doc is able to
use markdown text on it.

* Documentation/DocBook/drm.tmpl: Contains a table duplicated from
  drivers/gpu/drm/i915/i915_reg.h. This is not needed anymore

* drivers/gpu/drm/drm_modeset_lock.c: had a code example that used
  to look pretty bad on html. Fixed by using proper code markup.

* drivers/gpu/drm/drm_prime.c: Remove spaces between lines to make
  a proper markup list.

* drivers/gpu/drm/i915/i915_reg.h: Altought pandoc supports tables,
  it doesn't support table cell spanning. But we can use fixed-width
  for those special cases.

* include/drm/drm_vma_manager.h: Another code example that should be
  proper indented with four spaces.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 Changelog:
  v2:
* Improve markup in drivers/gpu/drm/drm_modes.c

 Documentation/DocBook/Makefile |  2 +-
 Documentation/DocBook/drm.tmpl | 86 --
 drivers/gpu/drm/drm_modes.c| 12 +++---
 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 ++---
 7 files changed, 48 insertions(+), 140 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 8e6d022..f2408b3 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -17,7 +17,7 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
tracepoint.xml drm.xml media_api.xml w1.xml \
writing_musb_glue_layer.xml crypto-API.xml
 
-MARKDOWNREADY :=
+MARKDOWNREADY := drm.xml
 
 include Documentation/DocBook/media/Makefile
 
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 2fb9a54..4fb4636 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -4073,92 +4073,6 @@ int num_ioctls;
   
 DPIO
 !Pdrivers/gpu/drm/i915/i915_reg.h DPIO
-   
- Dual channel PHY (VLV/CHV/BXT)
- 
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
- 
-   CH0
-   CH1
- 
-   
-   
- 
-   CMN/PLL/REF
-   CMN/PLL/REF
- 
- 
-   PCS01
-   PCS23
-   PCS01
-   PCS23
- 
- 
-   TX0
-   TX1
-   TX2
-   TX3
-   TX0
-   TX1
-   TX2
-   TX3
- 
- 
-   DDI0
-   DDI1
- 
-   
- 
-   
-   
- Single channel PHY (CHV/BXT)
- 
-   
-   
-   
-   
-   
-   
-   
-   
- 
-   CH0
- 
-   
-   
- 
-   CMN/PLL/REF
- 
- 
-   PCS01
-   PCS23
- 
- 
-   TX0
-   TX1
-   TX2
-   TX3
- 
- 
-   DDI2
- 
-   
- 
-   
   
 
   
diff --git a/drivers/gpu/drm/drm_modes.c b/drivers/gpu/drm/drm_modes.c
index cd74a09..9480464 100644
--- a/drivers/gpu/drm/drm_modes.c
+++ b/drivers/gpu/drm/drm_modes.c
@@ -553,10 +553,10 @@ EXPORT_SYMBOL(drm_gtf_mode_complex);
  * drivers/video/fbmon.c
  *
  * Standard GTF parameters:
- * M = 600
- * C = 40
- * K = 128
- * J = 20
+ * M = 600
+ * C = 40
+ * K = 128
+ * J = 20
  *
  * Returns:
  * The modeline based on the GTF algorithm stored in a drm_display_mode object.
@@ -1212,7 +1212,7 @@ EXPORT_SYMBOL(drm_mode_connector_list_update);
  * This uses the same parameters as the fb modedb.c, except for an extra
  * force-enable, force-enable-digital and force-disable bit at the end:
  *
- * x[M][R][-][@][i][m][eDd]
+ * x[M][R][-][@][i][m][eDd]
  *
  * The intermediate drm_cmdline_mode structure is required to store additional
  * options from the command line modline like the force-enable/disable flag.
@@ -1491,4 +1491,4 @@ int drm_mode_convert_umode(struct drm_display_mode *out,
 
 out:
return ret;
-}
\ No newline at end of file
+}
diff --git a/drivers/gpu/drm/drm_modeset_lock.c 
b/drivers/gpu/drm/drm_modeset_lock.c
index c0a5cd8..de59b0c 100644
--- a/drivers/gpu/drm/drm_modeset_lock.c
+++ b/drivers/gpu/drm/drm_modeset_lock.c
@@ -40,17 +40,15 @@
  * The basic usage pattern

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

[Danilo Cesar Lemes de Paula]

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  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  from the DocBook XML to generate a database. Then it looks
for , and  tags that matches the ones in
the database. As it only links existent references, no broken links are
added.

[1] - lists.freedesktop.org/archives/dri-devel/2014-August/065404.html

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 Changelog:
  v1 (missing changlog from v1):
 * Add a "XMLREF FooBar.xml" as build output to reduce build noise.
 * Make kernel-doc-xml-ref ignore invalid arguments.
 * Improve kernel-doc-xml-ref documentation.

 Documentation/DocBook/Makefile |  43 ++---
 scripts/kernel-doc-xml-ref | 198 +
 2 files changed, 228 insertions(+), 13 deletions(-)
 create mode 100755 scripts/kernel-doc-xml-ref

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index b6a6a2e..322255b 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -64,8 +64,9 @@ installmandocs: mandocs
 
 ###
 #External programs used
-KERNELDOC = $(srctree)/scripts/kernel-doc
-DOCPROC   = $(objtree)/scripts/docproc
+KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref
+KERNELDOC   = $(srctree)/scripts/kernel-doc
+DOCPROC = $(objtree)/scripts/docproc
 
 XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl
 XMLTOFLAGS += --skip-validation
@@ -89,7 +90,7 @@ define rule_docproc
 ) > $(dir $@).$(notdir $@).cmd
 endef
 
-%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) FORCE
+%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
$(call if_changed_rule,docproc)
 
 # Tell kbuild to always build the programs
@@ -140,7 +141,20 @@ quiet_cmd_db2html = HTML$@
echo ' \
$(patsubst %.html,%,$(notdir $@))' > $@
 
-%.html:%.xml
+###
+# Rules to create an aux XML and .db, and use them to re-process the DocBook 
XML
+# to fill internal hyperlinks
+   gen_aux_xml = :
+ quiet_gen_aux_xml = echo '  XMLREF  $@'
+silent_gen_aux_xml = :
+%.aux.xml: %.xml
+   @$($(quiet)gen_aux_xml)
+   @rm -rf $@
+   @(cat $< | egrep "^ 
$<.db)
+   @$(KERNELDOCXMLREF) -db $<.db $< > $@
+.PRECIOUS: %.aux.xml
+
+%.html:%.aux.xml
@(which xmlto > /dev/null 2>&1) || \
 (echo "*** You need to install xmlto ***"; \
  exit 1)
@@ -209,15 +223,18 @@ dochelp:
 ###
 # Temporary files left by various tools
 clean-files := $(DOCBOOKS) \
-   $(patsubst %.xml, %.dvi,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.aux,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.tex,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.log,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.out,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.ps,   $(DOCBOOKS)) \
-   $(patsubst %.xml, %.pdf,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.html, $(DOCBOOKS)) \
-   $(patsubst %.xml, %.9,$(DOCBOOKS)) \
+   $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.aux, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.tex, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.log, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.out, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.ps,  $(DOCBOOKS)) \
+   $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.html,$(DOCBOOKS)) \
+   $(patsubst %.xml, %.9,   $(DOCBOOKS)) \
+   $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.xml.db,  $(DOCBOOKS)) \
+   $(patsubst %.xml, %.xml, $(DOCBOOKS)) \
$(index)
 
 clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
diff --git a/scripts/kernel-doc-xml-ref b/scripts/kernel-doc-xml-ref
new file mode 100755
index 000..104a5a5
--- /dev/null
+++ b/scripts/kernel-doc-xml-ref
@@ -0,0 +1,198 @@
+#!/usr/bin/perl -w
+
+use strict;
+
+## Copyright (C) 2015  Intel Corporation ##
+###
+## This software falls under the GNU General Public License. ##
+## Please read the COPYING file for more information ##
+#
+#
+# This software reads a XML file and a list of valid interal
+# references to replace Docbook tags with links.
+#
+# The list of "valid internal references" must be one-per-line in the 
following format:
+#  API-struct-foo
+#  API-enum-bar
+#  API-my-function
+#
+# The software walks over the XML file looking for xml tags re

[PATCH v2 0/4] Add support for Hyperlinks and Markup on kernel-doc

[Danilo Cesar Lemes de Paula]

This series add supports for hyperlink cross-references on
Docbooks and an optional markup syntax for in-source
Documentation.

eg:
  
https://people.collabora.com/~danilo/intel/Documentation.MarkDown/DocBook/drm/API-drm-dev-ref.html
old:
  
https://people.collabora.com/~danilo/intel/Documentation.old/DocBook/drm/API-drm-dev-ref.html

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_modes.c|  12 +--
 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  |  54 +++---
 scripts/kernel-doc | 170 ++-
 scripts/kernel-doc-xml-ref | 198 +
 10 files changed, 454 insertions(+), 222 deletions(-)
 create mode 100755 scripts/kernel-doc-xml-ref

-- 
2.4.6

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

Re: [PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc

[Danilo Cesar Lemes de Paula]

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

[PATCH v2 4/4] drm/doc: Convert to markdown

[Danilo Cesar Lemes de Paula]

DRM Docbook is now Markdown ready. This means its doc is able to
use markdown text on it.

* Documentation/DocBook/drm.tmpl: Contains a table duplicated from
  drivers/gpu/drm/i915/i915_reg.h. This is not needed anymore

* drivers/gpu/drm/drm_modeset_lock.c: had a code example that used
  to look pretty bad on html. Fixed by using proper code markup.

* drivers/gpu/drm/drm_prime.c: Remove spaces between lines to make
  a proper markup list.

* drivers/gpu/drm/i915/i915_reg.h: Altought pandoc supports tables,
  it doesn't support table cell spanning. But we can use fixed-width
  for those special cases.

* include/drm/drm_vma_manager.h: Another code example that should be
  proper indented with four spaces.

Signed-off-by: Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk
Cc: Randy Dunlap rdun...@infradead.org
Cc: Daniel Vetter daniel.vet...@ffwll.ch
Cc: Laurent Pinchart laurent.pinch...@ideasonboard.com
Cc: Jonathan Corbet cor...@lwn.net
Cc: Herbert Xu herb...@gondor.apana.org.au
Cc: Stephan Mueller smuel...@chronox.de
Cc: Michal Marek mma...@suse.cz
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx intel-...@lists.freedesktop.org
Cc: dri-devel dri-de...@lists.freedesktop.org
---
 Changelog:
  v2:
* Improve markup in drivers/gpu/drm/drm_modes.c

 Documentation/DocBook/Makefile |  2 +-
 Documentation/DocBook/drm.tmpl | 86 --
 drivers/gpu/drm/drm_modes.c| 12 +++---
 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 ++---
 7 files changed, 48 insertions(+), 140 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 8e6d022..f2408b3 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -17,7 +17,7 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
tracepoint.xml drm.xml media_api.xml w1.xml \
writing_musb_glue_layer.xml crypto-API.xml
 
-MARKDOWNREADY :=
+MARKDOWNREADY := drm.xml
 
 include Documentation/DocBook/media/Makefile
 
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 2fb9a54..4fb4636 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -4073,92 +4073,6 @@ int num_ioctls;/synopsis
   sect2
 titleDPIO/title
 !Pdrivers/gpu/drm/i915/i915_reg.h DPIO
-   table id=dpiox2
- titleDual channel PHY (VLV/CHV/BXT)/title
- tgroup cols=8
-   colspec colname=c0 /
-   colspec colname=c1 /
-   colspec colname=c2 /
-   colspec colname=c3 /
-   colspec colname=c4 /
-   colspec colname=c5 /
-   colspec colname=c6 /
-   colspec colname=c7 /
-   spanspec spanname=ch0 namest=c0 nameend=c3 /
-   spanspec spanname=ch1 namest=c4 nameend=c7 /
-   spanspec spanname=ch0pcs01 namest=c0 nameend=c1 /
-   spanspec spanname=ch0pcs23 namest=c2 nameend=c3 /
-   spanspec spanname=ch1pcs01 namest=c4 nameend=c5 /
-   spanspec spanname=ch1pcs23 namest=c6 nameend=c7 /
-   thead
- row
-   entry spanname=ch0CH0/entry
-   entry spanname=ch1CH1/entry
- /row
-   /thead
-   tbody valign=top align=center
- row
-   entry spanname=ch0CMN/PLL/REF/entry
-   entry spanname=ch1CMN/PLL/REF/entry
- /row
- row
-   entry spanname=ch0pcs01PCS01/entry
-   entry spanname=ch0pcs23PCS23/entry
-   entry spanname=ch1pcs01PCS01/entry
-   entry spanname=ch1pcs23PCS23/entry
- /row
- row
-   entryTX0/entry
-   entryTX1/entry
-   entryTX2/entry
-   entryTX3/entry
-   entryTX0/entry
-   entryTX1/entry
-   entryTX2/entry
-   entryTX3/entry
- /row
- row
-   entry spanname=ch0DDI0/entry
-   entry spanname=ch1DDI1/entry
- /row
-   /tbody
- /tgroup
-   /table
-   table id=dpiox1
- titleSingle channel PHY (CHV/BXT)/title
- tgroup cols=4
-   colspec colname=c0 /
-   colspec colname=c1 /
-   colspec colname=c2 /
-   colspec colname=c3 /
-   spanspec spanname=ch0 namest=c0 nameend=c3 /
-   spanspec spanname=ch0pcs01 namest=c0 nameend=c1 /
-   spanspec spanname=ch0pcs23 namest=c2 nameend=c3 /
-   thead
- row
-   entry spanname=ch0CH0/entry
- /row
-   /thead
-   tbody valign=top align=center
- row
-   entry spanname=ch0CMN/PLL/REF/entry
- /row
- row
-   entry spanname

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

[Danilo Cesar Lemes de Paula]

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.

[1] - lists.freedesktop.org/archives/dri-devel/2014-August/065404.html

Signed-off-by: Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk
Cc: Randy Dunlap rdun...@infradead.org
Cc: Daniel Vetter daniel.vet...@ffwll.ch
Cc: Laurent Pinchart laurent.pinch...@ideasonboard.com
Cc: Jonathan Corbet cor...@lwn.net
Cc: Herbert Xu herb...@gondor.apana.org.au
Cc: Stephan Mueller smuel...@chronox.de
Cc: Michal Marek mma...@suse.cz
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx intel-...@lists.freedesktop.org
Cc: dri-devel dri-de...@lists.freedesktop.org
---
 Changelog:
  v1 (missing changlog from v1):
 * Add a XMLREF FooBar.xml as build output to reduce build noise.
 * Make kernel-doc-xml-ref ignore invalid arguments.
 * Improve kernel-doc-xml-ref documentation.

 Documentation/DocBook/Makefile |  43 ++---
 scripts/kernel-doc-xml-ref | 198 +
 2 files changed, 228 insertions(+), 13 deletions(-)
 create mode 100755 scripts/kernel-doc-xml-ref

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index b6a6a2e..322255b 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -64,8 +64,9 @@ installmandocs: mandocs
 
 ###
 #External programs used
-KERNELDOC = $(srctree)/scripts/kernel-doc
-DOCPROC   = $(objtree)/scripts/docproc
+KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref
+KERNELDOC   = $(srctree)/scripts/kernel-doc
+DOCPROC = $(objtree)/scripts/docproc
 
 XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl
 XMLTOFLAGS += --skip-validation
@@ -89,7 +90,7 @@ define rule_docproc
 )  $(dir $@).$(notdir $@).cmd
 endef
 
-%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) FORCE
+%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
$(call if_changed_rule,docproc)
 
 # Tell kbuild to always build the programs
@@ -140,7 +141,20 @@ quiet_cmd_db2html = HTML$@
echo 'a HREF=$(patsubst %.html,%,$(notdir $@))/index.html \
$(patsubst %.html,%,$(notdir $@))/ap'  $@
 
-%.html:%.xml
+###
+# Rules to create an aux XML and .db, and use them to re-process the DocBook 
XML
+# to fill internal hyperlinks
+   gen_aux_xml = :
+ quiet_gen_aux_xml = echo '  XMLREF  $@'
+silent_gen_aux_xml = :
+%.aux.xml: %.xml
+   @$($(quiet)gen_aux_xml)
+   @rm -rf $@
+   @(cat $ | egrep ^refentry id | egrep -o \.*\ | cut -f 2 -d \  
$.db)
+   @$(KERNELDOCXMLREF) -db $.db $  $@
+.PRECIOUS: %.aux.xml
+
+%.html:%.aux.xml
@(which xmlto  /dev/null 21) || \
 (echo *** You need to install xmlto ***; \
  exit 1)
@@ -209,15 +223,18 @@ dochelp:
 ###
 # Temporary files left by various tools
 clean-files := $(DOCBOOKS) \
-   $(patsubst %.xml, %.dvi,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.aux,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.tex,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.log,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.out,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.ps,   $(DOCBOOKS)) \
-   $(patsubst %.xml, %.pdf,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.html, $(DOCBOOKS)) \
-   $(patsubst %.xml, %.9,$(DOCBOOKS)) \
+   $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.aux, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.tex, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.log, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.out, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.ps,  $(DOCBOOKS)) \
+   $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.html,$(DOCBOOKS)) \
+   $(patsubst %.xml, %.9,   $(DOCBOOKS)) \
+   $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.xml.db,  $(DOCBOOKS)) \
+   $(patsubst %.xml, %.xml, $(DOCBOOKS)) \
$(index)
 
 clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
diff --git a/scripts/kernel-doc-xml-ref b/scripts/kernel-doc-xml-ref
new file mode 100755
index 000..104a5a5
--- /dev/null
+++ b/scripts/kernel-doc-xml-ref
@@ -0,0 +1,198 @@
+#!/usr/bin/perl -w
+
+use strict;
+
+## Copyright (C) 2015  Intel Corporation ##
+###
+## This software falls under the GNU General Public License. ##
+## Please read the COPYING file for more information ##
+#
+#
+# This software reads a XML file and a list

Re: [PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc

[Danilo Cesar Lemes de Paula]

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
--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[PATCH v2 0/4] Add support for Hyperlinks and Markup on kernel-doc

[Danilo Cesar Lemes de Paula]

This series add supports for hyperlink cross-references on
Docbooks and an optional markup syntax for in-source
Documentation.

eg:
  
https://people.collabora.com/~danilo/intel/Documentation.MarkDown/DocBook/drm/API-drm-dev-ref.html
old:
  
https://people.collabora.com/~danilo/intel/Documentation.old/DocBook/drm/API-drm-dev-ref.html

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_modes.c|  12 +--
 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  |  54 +++---
 scripts/kernel-doc | 170 ++-
 scripts/kernel-doc-xml-ref | 198 +
 10 files changed, 454 insertions(+), 222 deletions(-)
 create mode 100755 scripts/kernel-doc-xml-ref

-- 
2.4.6

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

[PATCH v2 3/4] scripts/kernel-doc: Adding infrastructure for markdown support

[Danilo Cesar Lemes de Paula]

Markdown support is given by calling an external tool, pandoc, for all
highlighted text on kernel-doc.

Pandoc converts Markdown text to proper Docbook tags, which will be
later translated to pdf, html or other targets.

This adds the capability of adding human-readle text highlight (bold,
underline, etc), bullet and numbered lists, simple tables, fixed-width
text (including asciiart), requiring minimal changes to current
documentation.

So, text using *must* will be rendered as emphasismust/empasis
inside DocBook and then strongmust/strong for HTML.
Bullet lists eg:
* Element 1
* Element 2
will also be converted to proper docbook/html lists.
Although it has the support for a good part of the markup language,
pandoc has some limitations and won't render tables with spanning cells
or headings. The use of those features are not recommended.

At this moment, pandoc is totally optional. Docbooks ready for markdown
should be added to the MARKDOWNREADY variable inside the Makefile. In
case the developer doesn't have pandoc installed, Make will throw a
warning and the documentation build will continue, generating
simple Documentation without the features brought by pandoc.

Signed-off-by: Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk
Cc: Randy Dunlap rdun...@infradead.org
Cc: Daniel Vetter daniel.vet...@ffwll.ch
Cc: Laurent Pinchart laurent.pinch...@ideasonboard.com
Cc: Jonathan Corbet cor...@lwn.net
Cc: Herbert Xu herb...@gondor.apana.org.au
Cc: Stephan Mueller smuel...@chronox.de
Cc: Michal Marek mma...@suse.cz
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx intel-...@lists.freedesktop.org
Cc: dri-devel dri-de...@lists.freedesktop.org
---
 Changelog:
  v2:
* Fix checkpatch issues.
* Improved commit message.
* Fixed dependency issue causing make htmldocs recalculate without
  any code change.

 Documentation/DocBook/Makefile | 25 +++-
 scripts/docproc.c  | 54 --
 scripts/kernel-doc | 66 --
 3 files changed, 119 insertions(+), 26 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 322255b..8e6d022 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -17,6 +17,8 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
tracepoint.xml drm.xml media_api.xml w1.xml \
writing_musb_glue_layer.xml crypto-API.xml
 
+MARKDOWNREADY :=
+
 include Documentation/DocBook/media/Makefile
 
 ###
@@ -79,18 +81,23 @@ XMLTOFLAGS += --skip-validation
 # The following rules are used to generate the .xml documentation
 # required to generate the final targets. (ps, pdf, html).
 quiet_cmd_docproc = DOCPROC $@
-  cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $ $@
+  cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $
 define rule_docproc
-   set -e; \
-$(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';)\
-$(cmd_$(1));   \
-(  \
-  echo 'cmd_$@ := $(cmd_$(1))';\
-  echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $`;  \
+   set -e; 
\
+   USEMARKDOWN=; 
\
+   FILE=`basename $@`; 
\
+   [[ $(MARKDOWNREADY) =~ $${FILE} ]]  USEMARKDOWN=-use-markdown;  
\
+$(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';)
\
+$(cmd_$(1)) $$USEMARKDOWN $@; 
\
+(  
\
+  echo 'cmd_$@ := $(cmd_$(1))';
\
+  echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $`;  
\
 )  $(dir $@).$(notdir $@).cmd
 endef
 
 %.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
+   @(which pandoc  /dev/null 21) || \
+   (echo *** To get propper documentation you need to install pandoc 
***;)
$(call if_changed_rule,docproc)
 
 # Tell kbuild to always build the programs
@@ -101,6 +108,10 @@ notfoundtemplate = echo *** You have to install 
docbook-utils or xmlto ***; \
 db2xtemplate = db2TYPE -o $(dir $@) $
 xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $
 
+ifneq ($(shell which pandoc /dev/null 21  echo found),found)
+   MARKDOWNREADY := ;
+endif
+
 # determine which methods are available
 ifeq ($(shell which db2ps /dev/null 21  echo found),found)
use-db2x = db2x
diff --git a/scripts/docproc.c b/scripts/docproc.c
index e267e621..7c6b225 100644
--- a/scripts/docproc.c
+++ b

[PATCH v2 2/4] scripts/kernel-doc: Replacing highlights hash by an array

[Danilo Cesar Lemes de Paula]

The highlight code is very sensible to the order of the hash keys,
but the order of the keys cannot be predicted on Perl. It generates
faulty DocBook entries like:
- @functiondevice_for_each_child/function

We should use an array for that job, so we can guarantee that the order
of the regex execution on dohighlight won't change.

Signed-off-by: Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk
Cc: Randy Dunlap rdun...@infradead.org
Cc: Daniel Vetter daniel.vet...@ffwll.ch
Cc: Laurent Pinchart laurent.pinch...@ideasonboard.com
Cc: Jonathan Corbet cor...@lwn.net
Cc: Herbert Xu herb...@gondor.apana.org.au
Cc: Stephan Mueller smuel...@chronox.de
Cc: Michal Marek mma...@suse.cz
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx intel-...@lists.freedesktop.org
Cc: dri-devel dri-de...@lists.freedesktop.org
---
 Changelog:
v2: No changes

 scripts/kernel-doc | 104 ++---
 1 file changed, 60 insertions(+), 44 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9922e66..a38a69a 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -182,59 +182,73 @@ my $type_env = '(\$\w+)';
 #  One for each output format
 
 # these work fairly well
-my %highlights_html = ( $type_constant, i\$1/i,
-   $type_func, b\$1/b,
-   $type_struct_xml, i\$1/i,
-   $type_env, bi\$1/i/b,
-   $type_param, ttb\$1/b/tt );
+my @highlights_html = (
+   [$type_constant, i\$1/i],
+   [$type_func, b\$1/b],
+   [$type_struct_xml, i\$1/i],
+   [$type_env, bi\$1/i/b],
+   [$type_param, ttb\$1/b/tt]
+  );
 my $local_lt = lt:;
 my $local_gt = gt:;
 my $blankline_html = $local_lt . p . $local_gt;  # was p
 
 # html version 5
-my %highlights_html5 = ( $type_constant, span class=\const\\$1/span,
-   $type_func, span class=\func\\$1/span,
-   $type_struct_xml, span class=\struct\\$1/span,
-   $type_env, span class=\env\\$1/span,
-   $type_param, span class=\param\\$1/span );
+my @highlights_html5 = (
+[$type_constant, span class=\const\\$1/span],
+[$type_func, span class=\func\\$1/span],
+[$type_struct_xml, span 
class=\struct\\$1/span],
+[$type_env, span class=\env\\$1/span],
+[$type_param, span class=\param\\$1/span]]
+  );
 my $blankline_html5 = $local_lt . br / . $local_gt;
 
 # XML, docbook format
-my %highlights_xml = ( ([^=])\\\([^\\\]+)\\\, \$1quote\$2/quote,
-   $type_constant, constant\$1/constant,
-   $type_func, function\$1/function,
-   $type_struct_xml, structname\$1/structname,
-   $type_env, envar\$1/envar,
-   $type_param, parameter\$1/parameter );
+my @highlights_xml = (
+  [([^=])\\\([^\\\]+)\\\, \$1quote\$2/quote],
+  [$type_constant, constant\$1/constant],
+  [$type_struct_xml, structname\$1/structname],
+  [$type_param, parameter\$1/parameter],
+  [$type_func, function\$1/function],
+  [$type_env, envar\$1/envar]
+);
 my $blankline_xml = $local_lt . /para . $local_gt . $local_lt . para . 
$local_gt . \n;
 
 # gnome, docbook format
-my %highlights_gnome = ( $type_constant, replaceable 
class=\option\\$1/replaceable,
-$type_func, function\$1/function,
-$type_struct, structname\$1/structname,
-$type_env, envar\$1/envar,
-$type_param, parameter\$1/parameter );
+my @highlights_gnome = (
+[$type_constant, replaceable 
class=\option\\$1/replaceable],
+[$type_func, function\$1/function],
+[$type_struct, structname\$1/structname],
+[$type_env, envar\$1/envar],
+[$type_param, parameter\$1/parameter ]
+  );
 my $blankline_gnome = /parapara\n;
 
 # these are pretty rough
-my %highlights_man = ( $type_constant, \$1,
-  $type_func, fB\$1fP,
-  $type_struct, fI\$1fP,
-  $type_param, fI\$1fP );
+my @highlights_man = (
+  [$type_constant, \$1],
+  [$type_func, fB\$1fP],
+  [$type_struct, fI\$1fP],
+  [$type_param, fI\$1fP]
+);
 my $blankline_man = ;
 
 # text-mode
-my %highlights_text = ( $type_constant, \$1

[PATCH 2/4] scripts/kernel-doc: Replacing highlights hash by an array

[Danilo Cesar Lemes de Paula]

The "highlight" code is very sensible to the order of the hash keys,
but the order of the keys cannot be predicted on Perl. It generates
faulty DocBook entries like:
- @device_for_each_child

We should use an array for that job, so we can guarantee that the order
of the regex execution on dohighlight won't change.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 scripts/kernel-doc | 104 ++---
 1 file changed, 60 insertions(+), 44 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9922e66..a38a69a 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -182,59 +182,73 @@ my $type_env = '(\$\w+)';
 #  One for each output format
 
 # these work fairly well
-my %highlights_html = ( $type_constant, "\$1",
-   $type_func, "\$1",
-   $type_struct_xml, "\$1",
-   $type_env, "\$1",
-   $type_param, "\$1" );
+my @highlights_html = (
+   [$type_constant, "\$1"],
+   [$type_func, "\$1"],
+   [$type_struct_xml, "\$1"],
+   [$type_env, "\$1"],
+   [$type_param, "\$1"]
+  );
 my $local_lt = "lt:";
 my $local_gt = "gt:";
 my $blankline_html = $local_lt . "p" . $local_gt;  # was ""
 
 # html version 5
-my %highlights_html5 = ( $type_constant, "\$1",
-   $type_func, "\$1",
-   $type_struct_xml, "\$1",
-   $type_env, "\$1",
-   $type_param, "\$1" );
+my @highlights_html5 = (
+[$type_constant, "\$1"],
+[$type_func, "\$1"],
+[$type_struct_xml, "\$1"],
+[$type_env, "\$1"],
+[$type_param, "\$1]"]
+  );
 my $blankline_html5 = $local_lt . "br /" . $local_gt;
 
 # XML, docbook format
-my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2",
-   $type_constant, "\$1",
-   $type_func, "\$1",
-   $type_struct_xml, "\$1",
-   $type_env, "\$1",
-   $type_param, "\$1" );
+my @highlights_xml = (
+  ["([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2"],
+  [$type_constant, "\$1"],
+  [$type_struct_xml, "\$1"],
+  [$type_param, "\$1"],
+  [$type_func, "\$1"],
+  [$type_env, "\$1"]
+);
 my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . 
$local_gt . "\n";
 
 # gnome, docbook format
-my %highlights_gnome = ( $type_constant, "\$1",
-$type_func, "\$1",
-$type_struct, "\$1",
-$type_env, "\$1",
-$type_param, "\$1" );
+my @highlights_gnome = (
+[$type_constant, "\$1"],
+[$type_func, "\$1"],
+[$type_struct, "\$1"],
+[$type_env, "\$1"],
+[$type_param, "\$1" ]
+  );
 my $blankline_gnome = "\n";
 
 # these are pretty rough
-my %highlights_man = ( $type_constant, "\$1",
-  $type_func, "fB\$1fP",
-  $type_struct, "fI\$1fP",
-  $type_param, "fI\$1fP" );
+my @highlights_man = (
+  [$type_constant, "\$1"],
+  [$type_func, "fB\$1fP"],
+  [$type_struct, "fI\$1fP"],
+  [$type_param, "fI\$1fP"]
+);
 my $blankline_man = "";
 
 # text-mode
-my %highlights_text = ( $type_constant, "\$1",
-   $type_func, "\$1",
-   $type_struct, "\$1",
-   $type_param, "\$1" );
+my @highlights_text = (

[PATCH 3/4] scripts/kernel-doc: Adding infrastructure for markdown support

[Danilo Cesar Lemes de Paula]

Markdown support is given by calling an external tool, pandoc, for all
highlighted text on kernel-doc.

Pandoc converts Markdown text to proper Docbook tags, which will be
later translated to pdf, html or other targets.

This adds the capability of adding human-readle text highlight (bold,
underline, etc), bullet and numbered lists, simple tables, fixed-width
text (including asciiart), requiring minimal changes to current documentation.

At this moment, pandoc is totally optional. Docbooks ready for markdown
should be added to the MARKDOWNREADY variable inside the Makefile. In
case the developer doesn't have pandoc installed, Make will throw a
warning and the documentation build will continue, generating
simple Documentation without the features brought by pandoc.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 Documentation/DocBook/Makefile | 25 +++-
 scripts/docproc.c  | 49 +--
 scripts/kernel-doc | 66 --
 3 files changed, 115 insertions(+), 25 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 322255b..7c404b3 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -17,6 +17,8 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
tracepoint.xml drm.xml media_api.xml w1.xml \
writing_musb_glue_layer.xml crypto-API.xml
 
+MARKDOWNREADY := 
+
 include Documentation/DocBook/media/Makefile
 
 ###
@@ -79,18 +81,23 @@ XMLTOFLAGS += --skip-validation
 # The following rules are used to generate the .xml documentation
 # required to generate the final targets. (ps, pdf, html).
 quiet_cmd_docproc = DOCPROC $@
-  cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@
+  cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< $$USEMARKDOWN >$@
 define rule_docproc
-   set -e; \
-$(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';)\
-$(cmd_$(1));   \
-(  \
-  echo 'cmd_$@ := $(cmd_$(1))';\
-  echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`;  \
+   set -e; 
\
+   USEMARKDOWN=""; 
\
+   FILE=`basename $@`; 
\
+   [[ "$(MARKDOWNREADY)" =~ "$${FILE}" ]] && USEMARKDOWN="-use-markdown";  
\
+$(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';)
\
+$(cmd_$(1));   
\
+(  
\
+  echo 'cmd_$@ := $(cmd_$(1))';
\
+  echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`;  
\
 ) > $(dir $@).$(notdir $@).cmd
 endef
 
 %.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
+   @(which pandoc > /dev/null 2>&1) || \
+   (echo "*** To get propper documentation you need to install pandoc 
***";)
$(call if_changed_rule,docproc)
 
 # Tell kbuild to always build the programs
@@ -101,6 +108,10 @@ notfoundtemplate = echo "*** You have to install 
docbook-utils or xmlto ***"; \
 db2xtemplate = db2TYPE -o $(dir $@) $<
 xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
 
+ifneq ($(shell which pandoc >/dev/null 2>&1 && echo found),found)
+   MARKDOWNREADY := "";
+endif
+
 # determine which methods are available
 ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
use-db2x = db2x
diff --git a/scripts/docproc.c b/scripts/docproc.c
index e267e621..45140b2 100644
--- a/scripts/docproc.c
+++ b/scripts/docproc.c
@@ -73,12 +73,15 @@ FILELINE * docsection;
 #define NOFUNCTION"-nofunction"
 #define NODOCSECTIONS "-no-doc-sections"
 #define SHOWNOTFOUND  "-show-not-found"
+#define USEMARKDOWN   "-use-markdown"
 
 static char *srctree, *kernsrctree;
 
 static char **all_list = NULL;
 static int all_list_len = 0;
 
+static int use_markdown = 0;
+
 static void consume_symbol(const char *sym)
 {
int i;
@@ -95,10 +98,11 @@ static void consume_symbol(const char *sym)
 
 static void usage (void)
 {
-   fprintf(stderr, "Usage: docproc {doc|depend} file\n");
+   fprintf(stderr, &q

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

[Danilo Cesar Lemes de Paula]

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  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  from the DocBook XML to generate a database. Then it looks
for , and  tags that matches the ones in
the database. As it only links existent references, no broken links are
added.

[1] - lists.freedesktop.org/archives/dri-devel/2014-August/065404.html

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 Documentation/DocBook/Makefile |  43 ++---
 scripts/kernel-doc-xml-ref | 198 +
 2 files changed, 228 insertions(+), 13 deletions(-)
 create mode 100755 scripts/kernel-doc-xml-ref

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index b6a6a2e..322255b 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -64,8 +64,9 @@ installmandocs: mandocs
 
 ###
 #External programs used
-KERNELDOC = $(srctree)/scripts/kernel-doc
-DOCPROC   = $(objtree)/scripts/docproc
+KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref
+KERNELDOC   = $(srctree)/scripts/kernel-doc
+DOCPROC = $(objtree)/scripts/docproc
 
 XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl
 XMLTOFLAGS += --skip-validation
@@ -89,7 +90,7 @@ define rule_docproc
 ) > $(dir $@).$(notdir $@).cmd
 endef
 
-%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) FORCE
+%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
$(call if_changed_rule,docproc)
 
 # Tell kbuild to always build the programs
@@ -140,7 +141,20 @@ quiet_cmd_db2html = HTML$@
echo ' \
$(patsubst %.html,%,$(notdir $@))' > $@
 
-%.html:%.xml
+###
+# Rules to create an aux XML and .db, and use them to re-process the DocBook 
XML
+# to fill internal hyperlinks
+   gen_aux_xml = :
+ quiet_gen_aux_xml = echo '  XMLREF  $@'
+silent_gen_aux_xml = :
+%.aux.xml: %.xml
+   @$($(quiet)gen_aux_xml)
+   @rm -rf $@
+   @(cat $< | egrep "^ 
$<.db)
+   @$(KERNELDOCXMLREF) -db $<.db $< > $@
+.PRECIOUS: %.aux.xml
+
+%.html:%.aux.xml
@(which xmlto > /dev/null 2>&1) || \
 (echo "*** You need to install xmlto ***"; \
  exit 1)
@@ -209,15 +223,18 @@ dochelp:
 ###
 # Temporary files left by various tools
 clean-files := $(DOCBOOKS) \
-   $(patsubst %.xml, %.dvi,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.aux,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.tex,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.log,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.out,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.ps,   $(DOCBOOKS)) \
-   $(patsubst %.xml, %.pdf,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.html, $(DOCBOOKS)) \
-   $(patsubst %.xml, %.9,$(DOCBOOKS)) \
+   $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.aux, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.tex, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.log, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.out, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.ps,  $(DOCBOOKS)) \
+   $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.html,$(DOCBOOKS)) \
+   $(patsubst %.xml, %.9,   $(DOCBOOKS)) \
+   $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.xml.db,  $(DOCBOOKS)) \
+   $(patsubst %.xml, %.xml, $(DOCBOOKS)) \
$(index)
 
 clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
diff --git a/scripts/kernel-doc-xml-ref b/scripts/kernel-doc-xml-ref
new file mode 100755
index 000..104a5a5
--- /dev/null
+++ b/scripts/kernel-doc-xml-ref
@@ -0,0 +1,198 @@
+#!/usr/bin/perl -w
+
+use strict;
+
+## Copyright (C) 2015  Intel Corporation ##
+###
+## This software falls under the GNU General Public License. ##
+## Please read the COPYING file for more information ##
+#
+#
+# This software reads a XML file and a list of valid interal
+# references to replace Docbook tags with links.
+#
+# The list of "valid internal references" must be one-per-line in the 
following format:
+#  API-struct-foo
+#  API-enum-bar
+#  API-my-function
+#
+# The software walks over the XML file looking for xml tags representing 
possible references
+# to the Document. Each reference will be cross checked against the "Valid 
Internal Reference" list. If
+# the referece is found it replaces its content by a  tag.
+#
+# usage:
+# kernel-doc-x

[PATCH 4/4] drm/doc: Convert to markdown

[Danilo Cesar Lemes de Paula]

DRM Docbook is now Markdown ready. This means its doc is able to
use markdown text on it.

* Documentation/DocBook/drm.tmpl: Contains a table duplicated from
  drivers/gpu/drm/i915/i915_reg.h. This is not needed anymore

* drivers/gpu/drm/drm_modeset_lock.c: had a code example that used
  to look pretty bad on html. Fixed by using proper code markup.

* drivers/gpu/drm/drm_prime.c: Remove spaces between lines to make
  a proper markup list.

* drivers/gpu/drm/i915/i915_reg.h: Altought pandoc supports tables,
  it doesn't support table cell spanning. But we can use fixed-width
  for those special cases.

* include/drm/drm_vma_manager.h: Another code example that should be
  proper indented with four spaces.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 Documentation/DocBook/Makefile |  2 +-
 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 ++---
 6 files changed, 42 insertions(+), 134 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 7c404b3..702e812 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -17,7 +17,7 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
tracepoint.xml drm.xml media_api.xml w1.xml \
writing_musb_glue_layer.xml crypto-API.xml
 
-MARKDOWNREADY := 
+MARKDOWNREADY := drm.xml
 
 include Documentation/DocBook/media/Makefile
 
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 2fb9a54..4fb4636 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -4073,92 +4073,6 @@ int num_ioctls;
   
 DPIO
 !Pdrivers/gpu/drm/i915/i915_reg.h DPIO
-   
- Dual channel PHY (VLV/CHV/BXT)
- 
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
- 
-   CH0
-   CH1
- 
-   
-   
- 
-   CMN/PLL/REF
-   CMN/PLL/REF
- 
- 
-   PCS01
-   PCS23
-   PCS01
-   PCS23
- 
- 
-   TX0
-   TX1
-   TX2
-   TX3
-   TX0
-   TX1
-   TX2
-   TX3
- 
- 
-   DDI0
-   DDI1
- 
-   
- 
-   
-   
- Single channel PHY (CHV/BXT)
- 
-   
-   
-   
-   
-   
-   
-   
-   
- 
-   CH0
- 
-   
-   
- 
-   CMN/PLL/REF
- 
- 
-   PCS01
-   PCS23
- 
- 
-   TX0
-   TX1
-   TX2
-   TX3
- 
- 
-   DDI2
- 
-   
- 
-   
   
 
   
diff --git a/drivers/gpu/drm/drm_modeset_lock.c 
b/drivers/gpu/drm/drm_modeset_lock.c
index c0a5cd8..de59b0c 100644
--- a/drivers/gpu/drm/drm_modeset_lock.c
+++ b/drivers/gpu/drm/drm_modeset_lock.c
@@ -40,17 +40,15 @@
  * The basic usage pattern is to:
  *
  * drm_modeset_acquire_init()
- *   retry:
+ * retry:
  * foreach (lock in random_ordered_set_of_locks) {
- *   ret = drm_modeset_lock(lock, )
- *   if (ret == -EDEADLK) {
- *  drm_modeset_backoff();
- *  goto retry;
- *   }
+ * ret = drm_modeset_lock(lock, )
+ * if (ret == -EDEADLK) {
+ * drm_modeset_backoff();
+ * goto retry;
+ * }
  * }
- *
  * ... do stuff ...
- *
  * drm_modeset_drop_locks();
  * drm_modeset_acquire_fini();
  */
diff --git a/drivers/gpu/drm/drm_prime.c b/drivers/gpu/drm/drm_prime.c
index 9f935f5..27aa718 100644
--- a/drivers/gpu/drm/drm_prime.c
+++ b/drivers/gpu/drm/drm_prime.c
@@ -313,19 +313,15 @@ static const struct dma_buf_ops drm_gem_prime_dmabuf_ops 
=  {
  *
  * Export callbacks:
  *
- *  - @gem_prime_pin (optional): prepare a GEM object for exporting
- *
- *  - @gem_prime_get_sg_table: provide a scatter/gather table of pinned pages
- *
- *  - @gem_prime_vmap: vmap a buffer exported by your driver
- *
- *  - @gem_prime_vunmap: vunmap a buffer exported by your driver
- *
- *  - @gem_prime_mmap (optional): mmap a buffer exported by your

[PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc

[Danilo Cesar Lemes de Paula]

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

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

[PATCH 4/4] drm/doc: Convert to markdown

[Danilo Cesar Lemes de Paula]

DRM Docbook is now Markdown ready. This means its doc is able to
use markdown text on it.

* Documentation/DocBook/drm.tmpl: Contains a table duplicated from
  drivers/gpu/drm/i915/i915_reg.h. This is not needed anymore

* drivers/gpu/drm/drm_modeset_lock.c: had a code example that used
  to look pretty bad on html. Fixed by using proper code markup.

* drivers/gpu/drm/drm_prime.c: Remove spaces between lines to make
  a proper markup list.

* drivers/gpu/drm/i915/i915_reg.h: Altought pandoc supports tables,
  it doesn't support table cell spanning. But we can use fixed-width
  for those special cases.

* include/drm/drm_vma_manager.h: Another code example that should be
  proper indented with four spaces.

Signed-off-by: Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk
Cc: Randy Dunlap rdun...@infradead.org
Cc: Daniel Vetter daniel.vet...@ffwll.ch
Cc: Laurent Pinchart laurent.pinch...@ideasonboard.com
Cc: Jonathan Corbet cor...@lwn.net
Cc: Herbert Xu herb...@gondor.apana.org.au
Cc: Stephan Mueller smuel...@chronox.de
Cc: Michal Marek mma...@suse.cz
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx intel-...@lists.freedesktop.org
Cc: dri-devel dri-de...@lists.freedesktop.org
---
 Documentation/DocBook/Makefile |  2 +-
 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 ++---
 6 files changed, 42 insertions(+), 134 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 7c404b3..702e812 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -17,7 +17,7 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
tracepoint.xml drm.xml media_api.xml w1.xml \
writing_musb_glue_layer.xml crypto-API.xml
 
-MARKDOWNREADY := 
+MARKDOWNREADY := drm.xml
 
 include Documentation/DocBook/media/Makefile
 
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 2fb9a54..4fb4636 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -4073,92 +4073,6 @@ int num_ioctls;/synopsis
   sect2
 titleDPIO/title
 !Pdrivers/gpu/drm/i915/i915_reg.h DPIO
-   table id=dpiox2
- titleDual channel PHY (VLV/CHV/BXT)/title
- tgroup cols=8
-   colspec colname=c0 /
-   colspec colname=c1 /
-   colspec colname=c2 /
-   colspec colname=c3 /
-   colspec colname=c4 /
-   colspec colname=c5 /
-   colspec colname=c6 /
-   colspec colname=c7 /
-   spanspec spanname=ch0 namest=c0 nameend=c3 /
-   spanspec spanname=ch1 namest=c4 nameend=c7 /
-   spanspec spanname=ch0pcs01 namest=c0 nameend=c1 /
-   spanspec spanname=ch0pcs23 namest=c2 nameend=c3 /
-   spanspec spanname=ch1pcs01 namest=c4 nameend=c5 /
-   spanspec spanname=ch1pcs23 namest=c6 nameend=c7 /
-   thead
- row
-   entry spanname=ch0CH0/entry
-   entry spanname=ch1CH1/entry
- /row
-   /thead
-   tbody valign=top align=center
- row
-   entry spanname=ch0CMN/PLL/REF/entry
-   entry spanname=ch1CMN/PLL/REF/entry
- /row
- row
-   entry spanname=ch0pcs01PCS01/entry
-   entry spanname=ch0pcs23PCS23/entry
-   entry spanname=ch1pcs01PCS01/entry
-   entry spanname=ch1pcs23PCS23/entry
- /row
- row
-   entryTX0/entry
-   entryTX1/entry
-   entryTX2/entry
-   entryTX3/entry
-   entryTX0/entry
-   entryTX1/entry
-   entryTX2/entry
-   entryTX3/entry
- /row
- row
-   entry spanname=ch0DDI0/entry
-   entry spanname=ch1DDI1/entry
- /row
-   /tbody
- /tgroup
-   /table
-   table id=dpiox1
- titleSingle channel PHY (CHV/BXT)/title
- tgroup cols=4
-   colspec colname=c0 /
-   colspec colname=c1 /
-   colspec colname=c2 /
-   colspec colname=c3 /
-   spanspec spanname=ch0 namest=c0 nameend=c3 /
-   spanspec spanname=ch0pcs01 namest=c0 nameend=c1 /
-   spanspec spanname=ch0pcs23 namest=c2 nameend=c3 /
-   thead
- row
-   entry spanname=ch0CH0/entry
- /row
-   /thead
-   tbody valign=top align=center
- row
-   entry spanname=ch0CMN/PLL/REF/entry
- /row
- row
-   entry spanname=ch0pcs01PCS01/entry
-   entry spanname=ch0pcs23PCS23/entry
- /row
- row

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

[Danilo Cesar Lemes de Paula]

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.

[1] - lists.freedesktop.org/archives/dri-devel/2014-August/065404.html

Signed-off-by: Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk
Cc: Randy Dunlap rdun...@infradead.org
Cc: Daniel Vetter daniel.vet...@ffwll.ch
Cc: Laurent Pinchart laurent.pinch...@ideasonboard.com
Cc: Jonathan Corbet cor...@lwn.net
Cc: Herbert Xu herb...@gondor.apana.org.au
Cc: Stephan Mueller smuel...@chronox.de
Cc: Michal Marek mma...@suse.cz
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx intel-...@lists.freedesktop.org
Cc: dri-devel dri-de...@lists.freedesktop.org
---
 Documentation/DocBook/Makefile |  43 ++---
 scripts/kernel-doc-xml-ref | 198 +
 2 files changed, 228 insertions(+), 13 deletions(-)
 create mode 100755 scripts/kernel-doc-xml-ref

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index b6a6a2e..322255b 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -64,8 +64,9 @@ installmandocs: mandocs
 
 ###
 #External programs used
-KERNELDOC = $(srctree)/scripts/kernel-doc
-DOCPROC   = $(objtree)/scripts/docproc
+KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref
+KERNELDOC   = $(srctree)/scripts/kernel-doc
+DOCPROC = $(objtree)/scripts/docproc
 
 XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl
 XMLTOFLAGS += --skip-validation
@@ -89,7 +90,7 @@ define rule_docproc
 )  $(dir $@).$(notdir $@).cmd
 endef
 
-%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) FORCE
+%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
$(call if_changed_rule,docproc)
 
 # Tell kbuild to always build the programs
@@ -140,7 +141,20 @@ quiet_cmd_db2html = HTML$@
echo 'a HREF=$(patsubst %.html,%,$(notdir $@))/index.html \
$(patsubst %.html,%,$(notdir $@))/ap'  $@
 
-%.html:%.xml
+###
+# Rules to create an aux XML and .db, and use them to re-process the DocBook 
XML
+# to fill internal hyperlinks
+   gen_aux_xml = :
+ quiet_gen_aux_xml = echo '  XMLREF  $@'
+silent_gen_aux_xml = :
+%.aux.xml: %.xml
+   @$($(quiet)gen_aux_xml)
+   @rm -rf $@
+   @(cat $ | egrep ^refentry id | egrep -o \.*\ | cut -f 2 -d \  
$.db)
+   @$(KERNELDOCXMLREF) -db $.db $  $@
+.PRECIOUS: %.aux.xml
+
+%.html:%.aux.xml
@(which xmlto  /dev/null 21) || \
 (echo *** You need to install xmlto ***; \
  exit 1)
@@ -209,15 +223,18 @@ dochelp:
 ###
 # Temporary files left by various tools
 clean-files := $(DOCBOOKS) \
-   $(patsubst %.xml, %.dvi,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.aux,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.tex,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.log,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.out,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.ps,   $(DOCBOOKS)) \
-   $(patsubst %.xml, %.pdf,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.html, $(DOCBOOKS)) \
-   $(patsubst %.xml, %.9,$(DOCBOOKS)) \
+   $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.aux, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.tex, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.log, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.out, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.ps,  $(DOCBOOKS)) \
+   $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.html,$(DOCBOOKS)) \
+   $(patsubst %.xml, %.9,   $(DOCBOOKS)) \
+   $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.xml.db,  $(DOCBOOKS)) \
+   $(patsubst %.xml, %.xml, $(DOCBOOKS)) \
$(index)
 
 clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
diff --git a/scripts/kernel-doc-xml-ref b/scripts/kernel-doc-xml-ref
new file mode 100755
index 000..104a5a5
--- /dev/null
+++ b/scripts/kernel-doc-xml-ref
@@ -0,0 +1,198 @@
+#!/usr/bin/perl -w
+
+use strict;
+
+## Copyright (C) 2015  Intel Corporation ##
+###
+## This software falls under the GNU General Public License. ##
+## Please read the COPYING file for more information ##
+#
+#
+# This software reads a XML file and a list of valid interal
+# references to replace Docbook tags with links.
+#
+# The list of valid internal references must be one-per-line in the 
following format:
+#  API-struct-foo
+#  API-enum-bar
+#  API-my-function

[PATCH 2/4] scripts/kernel-doc: Replacing highlights hash by an array

[Danilo Cesar Lemes de Paula]

The highlight code is very sensible to the order of the hash keys,
but the order of the keys cannot be predicted on Perl. It generates
faulty DocBook entries like:
- @functiondevice_for_each_child/function

We should use an array for that job, so we can guarantee that the order
of the regex execution on dohighlight won't change.

Signed-off-by: Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk
Cc: Randy Dunlap rdun...@infradead.org
Cc: Daniel Vetter daniel.vet...@ffwll.ch
Cc: Laurent Pinchart laurent.pinch...@ideasonboard.com
Cc: Jonathan Corbet cor...@lwn.net
Cc: Herbert Xu herb...@gondor.apana.org.au
Cc: Stephan Mueller smuel...@chronox.de
Cc: Michal Marek mma...@suse.cz
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx intel-...@lists.freedesktop.org
Cc: dri-devel dri-de...@lists.freedesktop.org
---
 scripts/kernel-doc | 104 ++---
 1 file changed, 60 insertions(+), 44 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9922e66..a38a69a 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -182,59 +182,73 @@ my $type_env = '(\$\w+)';
 #  One for each output format
 
 # these work fairly well
-my %highlights_html = ( $type_constant, i\$1/i,
-   $type_func, b\$1/b,
-   $type_struct_xml, i\$1/i,
-   $type_env, bi\$1/i/b,
-   $type_param, ttb\$1/b/tt );
+my @highlights_html = (
+   [$type_constant, i\$1/i],
+   [$type_func, b\$1/b],
+   [$type_struct_xml, i\$1/i],
+   [$type_env, bi\$1/i/b],
+   [$type_param, ttb\$1/b/tt]
+  );
 my $local_lt = lt:;
 my $local_gt = gt:;
 my $blankline_html = $local_lt . p . $local_gt;  # was p
 
 # html version 5
-my %highlights_html5 = ( $type_constant, span class=\const\\$1/span,
-   $type_func, span class=\func\\$1/span,
-   $type_struct_xml, span class=\struct\\$1/span,
-   $type_env, span class=\env\\$1/span,
-   $type_param, span class=\param\\$1/span );
+my @highlights_html5 = (
+[$type_constant, span class=\const\\$1/span],
+[$type_func, span class=\func\\$1/span],
+[$type_struct_xml, span 
class=\struct\\$1/span],
+[$type_env, span class=\env\\$1/span],
+[$type_param, span class=\param\\$1/span]]
+  );
 my $blankline_html5 = $local_lt . br / . $local_gt;
 
 # XML, docbook format
-my %highlights_xml = ( ([^=])\\\([^\\\]+)\\\, \$1quote\$2/quote,
-   $type_constant, constant\$1/constant,
-   $type_func, function\$1/function,
-   $type_struct_xml, structname\$1/structname,
-   $type_env, envar\$1/envar,
-   $type_param, parameter\$1/parameter );
+my @highlights_xml = (
+  [([^=])\\\([^\\\]+)\\\, \$1quote\$2/quote],
+  [$type_constant, constant\$1/constant],
+  [$type_struct_xml, structname\$1/structname],
+  [$type_param, parameter\$1/parameter],
+  [$type_func, function\$1/function],
+  [$type_env, envar\$1/envar]
+);
 my $blankline_xml = $local_lt . /para . $local_gt . $local_lt . para . 
$local_gt . \n;
 
 # gnome, docbook format
-my %highlights_gnome = ( $type_constant, replaceable 
class=\option\\$1/replaceable,
-$type_func, function\$1/function,
-$type_struct, structname\$1/structname,
-$type_env, envar\$1/envar,
-$type_param, parameter\$1/parameter );
+my @highlights_gnome = (
+[$type_constant, replaceable 
class=\option\\$1/replaceable],
+[$type_func, function\$1/function],
+[$type_struct, structname\$1/structname],
+[$type_env, envar\$1/envar],
+[$type_param, parameter\$1/parameter ]
+  );
 my $blankline_gnome = /parapara\n;
 
 # these are pretty rough
-my %highlights_man = ( $type_constant, \$1,
-  $type_func, fB\$1fP,
-  $type_struct, fI\$1fP,
-  $type_param, fI\$1fP );
+my @highlights_man = (
+  [$type_constant, \$1],
+  [$type_func, fB\$1fP],
+  [$type_struct, fI\$1fP],
+  [$type_param, fI\$1fP]
+);
 my $blankline_man = ;
 
 # text-mode
-my %highlights_text = ( $type_constant, \$1,
-   $type_func, \$1

[PATCH 3/4] scripts/kernel-doc: Adding infrastructure for markdown support

[Danilo Cesar Lemes de Paula]

Markdown support is given by calling an external tool, pandoc, for all
highlighted text on kernel-doc.

Pandoc converts Markdown text to proper Docbook tags, which will be
later translated to pdf, html or other targets.

This adds the capability of adding human-readle text highlight (bold,
underline, etc), bullet and numbered lists, simple tables, fixed-width
text (including asciiart), requiring minimal changes to current documentation.

At this moment, pandoc is totally optional. Docbooks ready for markdown
should be added to the MARKDOWNREADY variable inside the Makefile. In
case the developer doesn't have pandoc installed, Make will throw a
warning and the documentation build will continue, generating
simple Documentation without the features brought by pandoc.

Signed-off-by: Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk
Cc: Randy Dunlap rdun...@infradead.org
Cc: Daniel Vetter daniel.vet...@ffwll.ch
Cc: Laurent Pinchart laurent.pinch...@ideasonboard.com
Cc: Jonathan Corbet cor...@lwn.net
Cc: Herbert Xu herb...@gondor.apana.org.au
Cc: Stephan Mueller smuel...@chronox.de
Cc: Michal Marek mma...@suse.cz
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx intel-...@lists.freedesktop.org
Cc: dri-devel dri-de...@lists.freedesktop.org
---
 Documentation/DocBook/Makefile | 25 +++-
 scripts/docproc.c  | 49 +--
 scripts/kernel-doc | 66 --
 3 files changed, 115 insertions(+), 25 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 322255b..7c404b3 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -17,6 +17,8 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
tracepoint.xml drm.xml media_api.xml w1.xml \
writing_musb_glue_layer.xml crypto-API.xml
 
+MARKDOWNREADY := 
+
 include Documentation/DocBook/media/Makefile
 
 ###
@@ -79,18 +81,23 @@ XMLTOFLAGS += --skip-validation
 # The following rules are used to generate the .xml documentation
 # required to generate the final targets. (ps, pdf, html).
 quiet_cmd_docproc = DOCPROC $@
-  cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $ $@
+  cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $ $$USEMARKDOWN $@
 define rule_docproc
-   set -e; \
-$(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';)\
-$(cmd_$(1));   \
-(  \
-  echo 'cmd_$@ := $(cmd_$(1))';\
-  echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $`;  \
+   set -e; 
\
+   USEMARKDOWN=; 
\
+   FILE=`basename $@`; 
\
+   [[ $(MARKDOWNREADY) =~ $${FILE} ]]  USEMARKDOWN=-use-markdown;  
\
+$(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';)
\
+$(cmd_$(1));   
\
+(  
\
+  echo 'cmd_$@ := $(cmd_$(1))';
\
+  echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $`;  
\
 )  $(dir $@).$(notdir $@).cmd
 endef
 
 %.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
+   @(which pandoc  /dev/null 21) || \
+   (echo *** To get propper documentation you need to install pandoc 
***;)
$(call if_changed_rule,docproc)
 
 # Tell kbuild to always build the programs
@@ -101,6 +108,10 @@ notfoundtemplate = echo *** You have to install 
docbook-utils or xmlto ***; \
 db2xtemplate = db2TYPE -o $(dir $@) $
 xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $
 
+ifneq ($(shell which pandoc /dev/null 21  echo found),found)
+   MARKDOWNREADY := ;
+endif
+
 # determine which methods are available
 ifeq ($(shell which db2ps /dev/null 21  echo found),found)
use-db2x = db2x
diff --git a/scripts/docproc.c b/scripts/docproc.c
index e267e621..45140b2 100644
--- a/scripts/docproc.c
+++ b/scripts/docproc.c
@@ -73,12 +73,15 @@ FILELINE * docsection;
 #define NOFUNCTION-nofunction
 #define NODOCSECTIONS -no-doc-sections
 #define SHOWNOTFOUND  -show-not-found
+#define USEMARKDOWN   -use-markdown
 
 static char *srctree, *kernsrctree;
 
 static char **all_list = NULL;
 static int all_list_len = 0;
 
+static int use_markdown = 0;
+
 static void consume_symbol(const char *sym)
 {
int i;
@@ -95,10 +98,11 @@ static void consume_symbol(const char *sym)
 
 static void usage (void)
 {
-   fprintf(stderr, Usage: docproc {doc|depend} file\n);
+   fprintf(stderr, Usage: docproc {doc

[PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc

[Danilo Cesar Lemes de Paula]

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

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

kernel-doc markdown support

[Danilo Cesar Lemes de Paula]

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 majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

kernel-doc markdown support

[Danilo Cesar Lemes de Paula]

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 majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[PATCH v3] scripts/kernel-doc: Adding cross-reference links to html documentation.

[Danilo Cesar Lemes de Paula]

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  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  from the DocBook XML to generate a database. Then it looks
for , and  tags that matches the ones in
the database. As it only links existent references, no broken links are
added.

[1] - lists.freedesktop.org/archives/dri-devel/2014-August/065404.html

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 CHANGELOG
 v3:
   * Add a "XMLREF FooBar.xml" as build output to reduce build noise.
   * Make kernel-doc-xml-ref ignore invalid arguments.
   * Improve kernel-doc-xml-ref documentation.


 Documentation/DocBook/Makefile |  42 ++---
 scripts/kernel-doc-xml-ref | 198 +
 2 files changed, 227 insertions(+), 13 deletions(-)
 create mode 100755 scripts/kernel-doc-xml-ref

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index b6a6a2e..16a6d94 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -64,8 +64,9 @@ installmandocs: mandocs
 
 ###
 #External programs used
-KERNELDOC = $(srctree)/scripts/kernel-doc
-DOCPROC   = $(objtree)/scripts/docproc
+KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref
+KERNELDOC   = $(srctree)/scripts/kernel-doc
+DOCPROC = $(objtree)/scripts/docproc
 
 XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl
 XMLTOFLAGS += --skip-validation
@@ -89,7 +90,7 @@ define rule_docproc
 ) > $(dir $@).$(notdir $@).cmd
 endef
 
-%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) FORCE
+%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
$(call if_changed_rule,docproc)
 
 # Tell kbuild to always build the programs
@@ -140,7 +141,19 @@ quiet_cmd_db2html = HTML$@
echo ' \
$(patsubst %.html,%,$(notdir $@))' > $@
 
-%.html:%.xml
+###
+# Rules to create an aux XML and .db, and use them to re-process the DocBook 
XML
+# to fill internal hyperlinks
+   gen_aux_xml = :
+ quiet_gen_aux_xml = echo '  XMLREF  $@'
+silent_gen_aux_xml = :
+%.aux.xml: %.xml
+   @$($(quiet)gen_aux_xml)
+   @rm -rf $@
+   @(cat $< | egrep "^ 
$<.db)
+   @$(KERNELDOCXMLREF) -db $<.db $< > $@
+
+%.html:%.aux.xml
@(which xmlto > /dev/null 2>&1) || \
 (echo "*** You need to install xmlto ***"; \
  exit 1)
@@ -209,15 +222,18 @@ dochelp:
 ###
 # Temporary files left by various tools
 clean-files := $(DOCBOOKS) \
-   $(patsubst %.xml, %.dvi,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.aux,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.tex,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.log,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.out,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.ps,   $(DOCBOOKS)) \
-   $(patsubst %.xml, %.pdf,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.html, $(DOCBOOKS)) \
-   $(patsubst %.xml, %.9,$(DOCBOOKS)) \
+   $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.aux, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.tex, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.log, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.out, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.ps,  $(DOCBOOKS)) \
+   $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.html,$(DOCBOOKS)) \
+   $(patsubst %.xml, %.9,   $(DOCBOOKS)) \
+   $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.xml.db,  $(DOCBOOKS)) \
+   $(patsubst %.xml, %.xml, $(DOCBOOKS)) \
$(index)
 
 clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
diff --git a/scripts/kernel-doc-xml-ref b/scripts/kernel-doc-xml-ref
new file mode 100755
index 000..104a5a5
--- /dev/null
+++ b/scripts/kernel-doc-xml-ref
@@ -0,0 +1,198 @@
+#!/usr/bin/perl -w
+
+use strict;
+
+## Copyright (C) 2015  Intel Corporation ##
+###
+## This software falls under the GNU General Public License. ##
+## Please read the COPYING file for more information ##
+#
+#
+# This software reads a XML file and a list of valid interal
+# references to replace Docbook tags with links.
+#
+# The list of "valid internal references" must be one-per-line in the 
following format:
+#  API-struct-foo
+#  API-enum-bar
+#  API-my-function
+#
+# The software walks over the XML file looking for xml tags representing 
possible references
+# to the Document. Each refe

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

[Danilo Cesar Lemes de Paula]

On 07/09/2015 08:56 PM, Jonathan Corbet wrote:
> On Fri, 26 Jun 2015 12:08:57 -0300
> Danilo Cesar Lemes de Paula  wrote:
> 
>> To ease the navigation in the documentation we should use  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  from the DocBook XML to generate a database. Then it looks
>> for , and  tags that matches the ones in
>> the database. As it only links existent references, no broken links are
>> added.
> 
> So I put a lot more time into this today than I really had available.  I

Thanks, I really appreciate that.

> think it's cool stuff, and we definitely want it.  But can I ask for one
> more pass?  In particular:
> 
>  - It makes the docs build a lot more noisy, that would be nice to fix.

Fair enough. It was showing all the commands. I did change that to a
fancy "XMLREF  Documentation/DocBook/FooBar.xml" message.

> 
>  - A bit more documentation in the script would be nice.  It also is happy
>to run with silly arguments; a detail since nobody will run it
>directly, but still...

I did improve the documentation and also fixed the silly argument thing.

> 
>  - Most importantly, it breaks "make htmldocs"; in particular, vast
>amounts of error spew results when it gets around to media_api.html.  I
>spent a while trying to figure out what was going on but didn't come up
>with anything conclusive; my suspicion is that it has to do with the
>separate makefile in Documentation/DocBook/media/.

I'm not sure about this.
media-api is spitting lots of warnings with or without the documentation
patch.
I compared the number of files and they're the same (excepting those
auxiliary db files). For me, both builds actually spits 2825 lines on
STDERR...

I also did a smoke check in the media-api html documentation and it
looks fine.

Would you mind to check again if it happens with the v3 of my patch I'm
sending next?

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

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

[Danilo Cesar Lemes de Paula]

On 07/09/2015 08:56 PM, Jonathan Corbet wrote:
 On Fri, 26 Jun 2015 12:08:57 -0300
 Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk wrote:
 
 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 put a lot more time into this today than I really had available.  I

Thanks, I really appreciate that.

 think it's cool stuff, and we definitely want it.  But can I ask for one
 more pass?  In particular:
 
  - It makes the docs build a lot more noisy, that would be nice to fix.

Fair enough. It was showing all the commands. I did change that to a
fancy XMLREF  Documentation/DocBook/FooBar.xml message.

 
  - A bit more documentation in the script would be nice.  It also is happy
to run with silly arguments; a detail since nobody will run it
directly, but still...

I did improve the documentation and also fixed the silly argument thing.

 
  - Most importantly, it breaks make htmldocs; in particular, vast
amounts of error spew results when it gets around to media_api.html.  I
spent a while trying to figure out what was going on but didn't come up
with anything conclusive; my suspicion is that it has to do with the
separate makefile in Documentation/DocBook/media/.

I'm not sure about this.
media-api is spitting lots of warnings with or without the documentation
patch.
I compared the number of files and they're the same (excepting those
auxiliary db files). For me, both builds actually spits 2825 lines on
STDERR...

I also did a smoke check in the media-api html documentation and it
looks fine.

Would you mind to check again if it happens with the v3 of my patch I'm
sending next?

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

[PATCH v3] scripts/kernel-doc: Adding cross-reference links to html documentation.

[Danilo Cesar Lemes de Paula]

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.

[1] - lists.freedesktop.org/archives/dri-devel/2014-August/065404.html

Signed-off-by: Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk
Cc: Randy Dunlap rdun...@infradead.org
Cc: Daniel Vetter daniel.vet...@ffwll.ch
Cc: Laurent Pinchart laurent.pinch...@ideasonboard.com
Cc: Jonathan Corbet cor...@lwn.net
Cc: Herbert Xu herb...@gondor.apana.org.au
Cc: Stephan Mueller smuel...@chronox.de
Cc: Michal Marek mma...@suse.cz
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx intel-...@lists.freedesktop.org
Cc: dri-devel dri-de...@lists.freedesktop.org
---
 CHANGELOG
 v3:
   * Add a XMLREF FooBar.xml as build output to reduce build noise.
   * Make kernel-doc-xml-ref ignore invalid arguments.
   * Improve kernel-doc-xml-ref documentation.


 Documentation/DocBook/Makefile |  42 ++---
 scripts/kernel-doc-xml-ref | 198 +
 2 files changed, 227 insertions(+), 13 deletions(-)
 create mode 100755 scripts/kernel-doc-xml-ref

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index b6a6a2e..16a6d94 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -64,8 +64,9 @@ installmandocs: mandocs
 
 ###
 #External programs used
-KERNELDOC = $(srctree)/scripts/kernel-doc
-DOCPROC   = $(objtree)/scripts/docproc
+KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref
+KERNELDOC   = $(srctree)/scripts/kernel-doc
+DOCPROC = $(objtree)/scripts/docproc
 
 XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl
 XMLTOFLAGS += --skip-validation
@@ -89,7 +90,7 @@ define rule_docproc
 )  $(dir $@).$(notdir $@).cmd
 endef
 
-%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) FORCE
+%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
$(call if_changed_rule,docproc)
 
 # Tell kbuild to always build the programs
@@ -140,7 +141,19 @@ quiet_cmd_db2html = HTML$@
echo 'a HREF=$(patsubst %.html,%,$(notdir $@))/index.html \
$(patsubst %.html,%,$(notdir $@))/ap'  $@
 
-%.html:%.xml
+###
+# Rules to create an aux XML and .db, and use them to re-process the DocBook 
XML
+# to fill internal hyperlinks
+   gen_aux_xml = :
+ quiet_gen_aux_xml = echo '  XMLREF  $@'
+silent_gen_aux_xml = :
+%.aux.xml: %.xml
+   @$($(quiet)gen_aux_xml)
+   @rm -rf $@
+   @(cat $ | egrep ^refentry id | egrep -o \.*\ | cut -f 2 -d \  
$.db)
+   @$(KERNELDOCXMLREF) -db $.db $  $@
+
+%.html:%.aux.xml
@(which xmlto  /dev/null 21) || \
 (echo *** You need to install xmlto ***; \
  exit 1)
@@ -209,15 +222,18 @@ dochelp:
 ###
 # Temporary files left by various tools
 clean-files := $(DOCBOOKS) \
-   $(patsubst %.xml, %.dvi,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.aux,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.tex,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.log,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.out,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.ps,   $(DOCBOOKS)) \
-   $(patsubst %.xml, %.pdf,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.html, $(DOCBOOKS)) \
-   $(patsubst %.xml, %.9,$(DOCBOOKS)) \
+   $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.aux, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.tex, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.log, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.out, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.ps,  $(DOCBOOKS)) \
+   $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.html,$(DOCBOOKS)) \
+   $(patsubst %.xml, %.9,   $(DOCBOOKS)) \
+   $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.xml.db,  $(DOCBOOKS)) \
+   $(patsubst %.xml, %.xml, $(DOCBOOKS)) \
$(index)
 
 clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
diff --git a/scripts/kernel-doc-xml-ref b/scripts/kernel-doc-xml-ref
new file mode 100755
index 000..104a5a5
--- /dev/null
+++ b/scripts/kernel-doc-xml-ref
@@ -0,0 +1,198 @@
+#!/usr/bin/perl -w
+
+use strict;
+
+## Copyright (C) 2015  Intel Corporation ##
+###
+## This software falls under the GNU General Public License. ##
+## Please read the COPYING file for more information ##
+#
+#
+# This software reads a XML file and a list of valid interal
+# references to replace Docbook tags

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

[Danilo Cesar Lemes de Paula]

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  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  from the DocBook XML to generate a database. Then it looks
for , and  tags that matches the ones in
the database. As it only links existent references, no broken links are
added.

[1] - lists.freedesktop.org/archives/dri-devel/2014-August/065404.html

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 To understand a bit more of what this patch is trying to acomplish you can find
 two examples of the old and new htmldocs outputs:
 OLD: 
https://people.collabora.com/~danilo/intel/Documentation.old/DocBook/drm/API-drm-crtc-vblank-on.html
 NEW: 
https://people.collabora.com/~danilo/intel/Documentation.new/DocBook/drm/API-drm-crtc-vblank-on.html

 Documentation/DocBook/Makefile |  34 +---
 scripts/kernel-doc-xml-ref | 181 +
 2 files changed, 202 insertions(+), 13 deletions(-)
 create mode 100755 scripts/kernel-doc-xml-ref

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index b6a6a2e..8aea45a 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -64,8 +64,9 @@ installmandocs: mandocs
 
 ###
 #External programs used
-KERNELDOC = $(srctree)/scripts/kernel-doc
-DOCPROC   = $(objtree)/scripts/docproc
+KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref
+KERNELDOC   = $(srctree)/scripts/kernel-doc
+DOCPROC = $(objtree)/scripts/docproc
 
 XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl
 XMLTOFLAGS += --skip-validation
@@ -89,7 +90,7 @@ define rule_docproc
 ) > $(dir $@).$(notdir $@).cmd
 endef
 
-%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) FORCE
+%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
$(call if_changed_rule,docproc)
 
 # Tell kbuild to always build the programs
@@ -139,8 +140,12 @@ quiet_cmd_db2html = HTML$@
   cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
echo ' \
$(patsubst %.html,%,$(notdir $@))' > $@
+%.aux.xml: %.xml
+   @rm -rf $@
+   (cat $< | egrep "^ 
$<.db)
+   $(KERNELDOCXMLREF) -db $<.db $< > $@
 
-%.html:%.xml
+%.html:%.aux.xml
@(which xmlto > /dev/null 2>&1) || \
 (echo "*** You need to install xmlto ***"; \
  exit 1)
@@ -209,15 +214,18 @@ dochelp:
 ###
 # Temporary files left by various tools
 clean-files := $(DOCBOOKS) \
-   $(patsubst %.xml, %.dvi,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.aux,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.tex,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.log,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.out,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.ps,   $(DOCBOOKS)) \
-   $(patsubst %.xml, %.pdf,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.html, $(DOCBOOKS)) \
-   $(patsubst %.xml, %.9,$(DOCBOOKS)) \
+   $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.aux, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.tex, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.log, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.out, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.ps,  $(DOCBOOKS)) \
+   $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.html,$(DOCBOOKS)) \
+   $(patsubst %.xml, %.9,   $(DOCBOOKS)) \
+   $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.xml.db,  $(DOCBOOKS)) \
+   $(patsubst %.xml, %.xml, $(DOCBOOKS)) \
$(index)
 
 clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
diff --git a/scripts/kernel-doc-xml-ref b/scripts/kernel-doc-xml-ref
new file mode 100755
index 000..c61cdad
--- /dev/null
+++ b/scripts/kernel-doc-xml-ref
@@ -0,0 +1,181 @@
+#!/usr/bin/perl -w
+
+use strict;
+
+## Copyright (C) 2015  Intel Corporation ##
+###
+## This software falls under the GNU General Public License. ##
+## Please read the COPYING file for more information ##
+#
+#
+# This software reads a XML file and a list of valid interal
+# references to replace Docbook tags with links.
+#
+# usage:
+# kernel-doc-xml-ref -db filename
+#   xml filename > outputfile
+
+# read arguments
+if ($#ARGV != 2) {
+   usage();
+}
+
+#Holds the database filename
+my $databasefile;
+my @database;
+
+#holds the inputfile
+my $inputfile;
+my $errors = 0;
+
+my %highlights =

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

[Danilo Cesar Lemes de Paula]

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.

[1] - lists.freedesktop.org/archives/dri-devel/2014-August/065404.html

Signed-off-by: Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk
Cc: Randy Dunlap rdun...@infradead.org
Cc: Daniel Vetter daniel.vet...@ffwll.ch
Cc: Laurent Pinchart laurent.pinch...@ideasonboard.com
Cc: Jonathan Corbet cor...@lwn.net
Cc: Herbert Xu herb...@gondor.apana.org.au
Cc: Stephan Mueller smuel...@chronox.de
Cc: Michal Marek mma...@suse.cz
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx intel-...@lists.freedesktop.org
Cc: dri-devel dri-de...@lists.freedesktop.org
---
 To understand a bit more of what this patch is trying to acomplish you can find
 two examples of the old and new htmldocs outputs:
 OLD: 
https://people.collabora.com/~danilo/intel/Documentation.old/DocBook/drm/API-drm-crtc-vblank-on.html
 NEW: 
https://people.collabora.com/~danilo/intel/Documentation.new/DocBook/drm/API-drm-crtc-vblank-on.html

 Documentation/DocBook/Makefile |  34 +---
 scripts/kernel-doc-xml-ref | 181 +
 2 files changed, 202 insertions(+), 13 deletions(-)
 create mode 100755 scripts/kernel-doc-xml-ref

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index b6a6a2e..8aea45a 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -64,8 +64,9 @@ installmandocs: mandocs
 
 ###
 #External programs used
-KERNELDOC = $(srctree)/scripts/kernel-doc
-DOCPROC   = $(objtree)/scripts/docproc
+KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref
+KERNELDOC   = $(srctree)/scripts/kernel-doc
+DOCPROC = $(objtree)/scripts/docproc
 
 XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl
 XMLTOFLAGS += --skip-validation
@@ -89,7 +90,7 @@ define rule_docproc
 )  $(dir $@).$(notdir $@).cmd
 endef
 
-%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) FORCE
+%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
$(call if_changed_rule,docproc)
 
 # Tell kbuild to always build the programs
@@ -139,8 +140,12 @@ quiet_cmd_db2html = HTML$@
   cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $  \
echo 'a HREF=$(patsubst %.html,%,$(notdir $@))/index.html \
$(patsubst %.html,%,$(notdir $@))/ap'  $@
+%.aux.xml: %.xml
+   @rm -rf $@
+   (cat $ | egrep ^refentry id | egrep -o \.*\ | cut -f 2 -d \  
$.db)
+   $(KERNELDOCXMLREF) -db $.db $  $@
 
-%.html:%.xml
+%.html:%.aux.xml
@(which xmlto  /dev/null 21) || \
 (echo *** You need to install xmlto ***; \
  exit 1)
@@ -209,15 +214,18 @@ dochelp:
 ###
 # Temporary files left by various tools
 clean-files := $(DOCBOOKS) \
-   $(patsubst %.xml, %.dvi,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.aux,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.tex,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.log,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.out,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.ps,   $(DOCBOOKS)) \
-   $(patsubst %.xml, %.pdf,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.html, $(DOCBOOKS)) \
-   $(patsubst %.xml, %.9,$(DOCBOOKS)) \
+   $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.aux, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.tex, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.log, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.out, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.ps,  $(DOCBOOKS)) \
+   $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.html,$(DOCBOOKS)) \
+   $(patsubst %.xml, %.9,   $(DOCBOOKS)) \
+   $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \
+   $(patsubst %.xml, %.xml.db,  $(DOCBOOKS)) \
+   $(patsubst %.xml, %.xml, $(DOCBOOKS)) \
$(index)
 
 clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
diff --git a/scripts/kernel-doc-xml-ref b/scripts/kernel-doc-xml-ref
new file mode 100755
index 000..c61cdad
--- /dev/null
+++ b/scripts/kernel-doc-xml-ref
@@ -0,0 +1,181 @@
+#!/usr/bin/perl -w
+
+use strict;
+
+## Copyright (C) 2015  Intel Corporation ##
+###
+## This software falls under the GNU General Public License. ##
+## Please read the COPYING file for more information ##
+#
+#
+# This software reads a XML file and a list of valid interal
+# references to replace Docbook tags with links