Re: [Intel-gfx] [PATCH v2 2/4] scripts/kernel-doc: Replacing highlights hash by an array
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
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [RFC] Docs: drm: Move KMS properties table out to source files
On 09/22/2015 07:22 AM, Graham Whaley wrote:
> On Wed, Sep 02, 2015 at 02:50:52PM +0100, Graham Whaley wrote:
>>> (RFC/test - not for merging)
>>> The below is a test of moving the large HTML KMS properties table
>>> out
>>> to markdown style in the appropriate files.
>>> In the test we only use the first few rows of the existing KMS
>>> table
>>> an example.
>>> We use a fixed width table as the other styles of table supported
>>> by
>>> pandoc markdown do not support multi-column cells.
>>>
>>> The test shows a couple of issues:
>>> 1) double quote characters are being expanded in the fixed width
>>> table
>>> which then breaks the table alignment and leaves html style
>>> tags
>>> in the text
>
> Further to this item:
> Before I continue working on splitting the tables and converting to
> markdown (which btw Daniel does look feasible so far...), I thought we
> should understand what was going on with the markdown table quote
> breakage.
> I think I know what is happenig.
> The problem revolves around highlight expansion in the kenrel-doc
> script. In the output_highlight function we can see that first the
> script does highlight expansion (with the eval of @dohighlight), and
> then it invokes the markdown processing.
> Done that way around what happens is:
> - @dohighlight expands any "X" to html/xml quote tag sequences
> - which can push the text beyond the table column widths,
> - and then the markdown tries to split the text over columns, and
> manages to put the break in the middle of a tag, and thus breaks the
> tag formatting (see below)
>
> At least that is what I think is happening.
> I had thought maybe we could swap the markdown and highlight processing
> order, but then that presents a different issue - the markdown table
> contains metadata with quoted items (such as cols="5"), which the
> highligh processing then expands into tags, and hence breaks the table
> format metadata.
>
> As an example, using the following table !Pinclude'd into drm.tmpl:
> /**
> * DOC: DRM generic
> *
> * : DRM generic properties
> *
> * +--+++-+
> +
> * |Property |Type|Property Values |Object
> |Description/Restrictions|
> *
> +==+++=+===
> =+
> * |"rotation"|BITMASK |{ 0, "rotate-0" }, {|CRTC,|rotate-(degrees)
> rotates|
> * +--+++-+
> +
> *
> */
>
> The post-highlight pre-markdown text captured as the $orig_context in
> the markdown_to_docbook function is:
>
> +--+++-+---
> -+
> |Property |Type|Property Values |Object
> |Description/Restrictions|
> +==+++=+===
> =+
> |rotation|BITMASK |{ 0, rotate-0 },
> {|CRTC,|rotate-(degrees) rotates|
> +--+++-+---
> -+
>
> which when processed (and you can do this by hand with 'pandoc -
> -columns=80 -f markdown -t docbook ...' generates the broken tags
> example:
>
> ...
>
>
>
>
>rota
>
>
>
>
>tion
>
>
>
>te>|BITMASK |{ 0,
>
>
>
>ote>rotate
>
>
>
>
>-0 }, {|CRTC, |rotate-(degrees) rotates
>
> ...
>
> where you can see the quote tag processing has gone horribly wrong.
>
> I believe we'll have the same problem for the other 'highlight'
> processed items from kern-doc as well, meaning:
> funcname()
> $ENVVAR
> &struct_name
> @parameter
> %CONST
>
> As the kern-doc processing has no knowledge of when it is about to
> process a markdown table I can't think of an obvious way around this.
> At present I think the implicit rule is 'no highlight/expansion items
> allowed in markdown tables', which means all those quoted strings for
> the DRM properties cannot currently be migrated to look like strings.
>
> Danilo, or anybody, any ideas?
Your debugging is pretty precise. The "+=+===" format is rigid. I
don't know if it's a bug in pandoc or something from the spec itself.
May I suggest another format?
| Property | Type |
||:---:|
| "rotation" | BITMASK |
This format looks to work pretty well even if "rotation" is replaced by
some very long string (which seems to be the problem). I didn't test it
with kernel-doc, but pandoc looks to work fine with it.
I'm not sure if we can call it a proper fix, but it should allow you to
keep the ball rolling.
--
Danilo Cesar
___
Intel-gfx mailing list
Intel-gfx@lists.freedeskt
Re: [Intel-gfx] [PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements
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: [Intel-gfx] [PATCH] scripts/kernel-doc: Improve Markdown results
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 ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
[Intel-gfx] [PATCH 3/6] drm/doc: Convert to markdown
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-ker...@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(&ctx) -
[Intel-gfx] [PATCH 6/6] scripts/kernel-doc: Processing -nofunc for functions only
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-ker...@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
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
[Intel-gfx] [PATCH 4/6] drm/doc: Fixing xml documentation warning
"/**" 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-ker...@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
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
[Intel-gfx] [PATCH 5/6] scripts/kernel-doc: Improve Markdown results
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-ker...@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
[Intel-gfx] [PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an array
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-ker...@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", -
[Intel-gfx] [PATCH 2/6] scripts/kernel-doc: Adding infrastructure for markdown support
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-ker...@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|dep
[Intel-gfx] [PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements
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-ker...@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 ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH] scripts/kernel-doc: Improve Markdown results
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 ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH] scripts/kernel-doc: Improve Markdown results
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-ker...@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 ($a
Re: [Intel-gfx] [PATCH 4/5] Documentation: drm: Convert KMS Properties HTML table to CALS
On 08/25/2015 01:10 PM, Graham Whaley wrote: > On Tue, 2015-08-25 at 16:29 +0200, Daniel Vetter wrote: >> On Tue, Aug 25, 2015 at 10:26:44AM +0100, Graham Whaley wrote: >>> The KMS Properties table is in HTML format, which is not supported >>> for building pdfdocs, resulting in the following types of errors: >>> >>> jade:/Documentation/DocBook/drm.xml:34413:15:E: there is no >>> attribute >>> "border" >>> jade:/Documentation/DocBook/drm.xml:34413:31:E: there is no >>> attribute >>> "cellpadding" >>> jade:/Documentation/DocBook/drm.xml:34413:47:E: there is no >>> attribute >>> "cellspacing" >>> jade:/Documentation/DocBook/drm.xml:34414:7:E: document type does >>> not >>> allow element "tbody" here >>> >>> Convert the table over to a CALS format table >> >> Hm, long-term plan was to move this table into DOC: comments in the >> source-code using markdown, which we now have (at least in >> drm-intel-nightly and also planned to be merged into 4.4). Since this >> is >> both a lot of churn I'd like to get there in just 1 step ... >> -Daniel > First - I've just noted an erroneous debug comment (or two) left in > this patch as well, so looks like I will have to re-issue the series > anyway. > > OK. I guess this comes down to a matter of timing... > From Danilos patch of: f6d6913 (drm/doc: Convert to markdown) > we can see markdown does not natively support tables, and we'd have to > make this a fixed width layout like the one in that patch I suspect. > Danilo - any advice on how you did that other table conversion? I just > did a pandoc docbook->markdown_github and it looks some way there - but > of course seems to have not honored the multi-column items, of which > there are a few. It's probably not too bad to fix up by hand - I'll see > if I can get that to work... Hi Graham, To be honest I didn't have to do any conversion as that table was already in the header file. I just added 4 spaces so it would be transformed into fixed width. However, there's tool you can use to help you: http://pandoc.org/try/ I did a lot of translation there. If your table doesn't have any spancells, you can put the HTML code there and get the Markdown for free. Danilo ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
[Intel-gfx] [PATCH] scripts/kernel-doc: Processing -nofunc for functions only
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-ker...@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
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
[Intel-gfx] [PATCH] drm/doc: Fixing xml documentation warning
"/**" 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-ker...@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
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
[Intel-gfx] [PATCH] scripts/kernel-doc: Improve Markdown results
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-ker...@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"
Re: [Intel-gfx] [PATCH v2 1/4] scripts/kernel-doc: Adding cross-reference links to html documentation.
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 ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc
On 08/13/2015 08:20 PM, Jonathan Corbet wrote: > On Thu, 13 Aug 2015 20:09:35 -0300 > Danilo Cesar Lemes de Paula wrote: > >> Did you find time to take a look on this? > > No. Just when I thought things couldn't get crazier, my laptop died. > > https://plus.google.com/+JonathanCorbet/posts/FBHp48dPb95 > > What spare time I had has been dedicated to recovering from that in time > to give my talk next week. Those evil machines... =) > >> I understand that there's some discussion behind the curtains regarding >> the markdown support, but the cross-reference-hyperlink patch is also in >> the same patch series. It doesn't change any text in the docbook unless >> there's really a cross-reference link to it. Different from the markdown >> support (when people start to use markdown to write docs it will be hard >> to go back), the cross-link stuff doesn't require/create any change to >> current documentation, it is pretty safe to use. >> >> Would you mind to share your plans about this? > > No behind-the-curtains discussions happening, or, let's say, if there > are, I've not been invited either. I meant the Kernel summit mailing list, but looks like that thread died even before my patches. > > I'd like to get back to the cross-reference stuff. Last I tried, it > failed while building the media docs; have you been able to look at > that? I did, and I didn't find anything. Media API already spits lots of warnings without my patch. I did send those warnings to a file and count them. My patch produces the same amount of warnings as the original branch. I did, however, use a clean build to test that. Daniel Vetter complained that the Documentation was being rebuilt all the time, something wrong with the dependencies. I did fix that in v2. Maybe the errors you got were related to it? > > Longer term, as you may know from the kernel summit discussions, I'd > really like to get rid of a lot of the XML gunk and put in something more > straightforward, be it based on Markdown or something else. Doing that, > however, requires that I find the time to implement something that's > convincingly better. It may happen soon, but I sure can't guarantee it. > > Meanwhile, I think it would be a horrible mistake to delay useful work > because I have a gleam in my eye to do something different one of these > years, so I'll not do that. I fully expect to merge all of the stuff > you've done, I just need to have a good look at it and test it out a > bit. As I said before, I can't promise that for the 4.3 merge window, > but I'll try. > > Apologies, No need to apologize, just wanted to know what was going on. Danilo Cesar ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc
On 07/23/2015 05:29 PM, Jonathan Corbet wrote: > On Thu, 23 Jul 2015 15:16:23 -0300 > Danilo Cesar Lemes de Paula wrote: > >> This series add supports for hyperlink cross-references on Docbooks and >> an optional markup syntax for in-source Documentation. > > I like the idea; just be warned that it's likely to be a week or two and > one more ocean crossing before I can take a serious look at this... > > Thanks, Hey, Did you find time to take a look on this? I understand that there's some discussion behind the curtains regarding the markdown support, but the cross-reference-hyperlink patch is also in the same patch series. It doesn't change any text in the docbook unless there's really a cross-reference link to it. Different from the markdown support (when people start to use markdown to write docs it will be hard to go back), the cross-link stuff doesn't require/create any change to current documentation, it is pretty safe to use. Would you mind to share your plans about this? Thanks, Danilo Cesar ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
[Intel-gfx] [PATCH v2] scripts/kernel-doc Allow struct arguments documentation in struct body
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-ker...@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
Re: [Intel-gfx] [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body
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-ker...@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;
>> }
>>
[Intel-gfx] [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body
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-ker...@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,
[Intel-gfx] [PATCH v2 1/4] scripts/kernel-doc: Adding cross-reference links to html documentation.
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-ker...@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
[Intel-gfx] [PATCH v2 2/4] scripts/kernel-doc: Replacing highlights hash by an array
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-ker...@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_par
[Intel-gfx] [PATCH v2 3/4] scripts/kernel-doc: Adding infrastructure for markdown support
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-ker...@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
@@ -7
[Intel-gfx] [PATCH v2 4/4] drm/doc: Convert to markdown
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-ker...@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 pa
[Intel-gfx] [PATCH v2 0/4] Add support for Hyperlinks and Markup on kernel-doc
This series add supports for hyperlink cross-references on Docbooks and an optional markup syntax for in-source Documentation. 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 ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc
On 07/25/2015 07:20 AM, Stephan Mueller wrote: > Am Donnerstag, 23. Juli 2015, 15:16:23 schrieb Danilo Cesar Lemes de Paula: > > Hi Danilo, > >> This series add supports for hyperlink cross-references on Docbooks and >> an optional markup syntax for in-source Documentation. > > Can you please give an example what you mean with the latter? Sure, take a look on https://people.collabora.com/~danilo/intel/Documentation.MarkDown/DocBook/drm/API-drm-dev-ref.html The words "must" and "any" are emphasised, it's different from the original https://people.collabora.com/~danilo/intel/Documentation.old/DocBook/drm/API-drm-dev-ref.html That page is created from drivers/gpu/drm/drm_drv.c, part of drm_dev_ref Documentation, where the text is "You *must* already own". This is a ridiculous simple example but there are some bullet lists, numbered lists and code example in my patch 4/4. It can also do asciiart and tables. I'm sending a v2 of this patch series later as I have some fixes for it. Danilo Cesar ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
[Intel-gfx] [PATCH 4/4] drm/doc: Convert to markdown
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-ker...@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(&ctx)
- * retry:
+ * retry:
* foreach (lock in random_ordered_set_of_locks) {
- * ret = drm_modeset_lock(lock, &ctx)
- * if (ret == -EDEADLK) {
- * drm_modeset_backoff(&ctx);
- * goto retry;
- * }
+ * ret = drm_modeset_lock(lock, &ctx)
+ * if (ret == -EDEADLK) {
+ * drm_modeset_backoff(&ctx);
+ * goto retry;
+ * }
* }
- *
* ... do stuff ...
- *
* drm_modeset_drop_locks(&ctx);
* drm_modeset_acquire_fini(&ctx);
*/
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
- *
- * - @
[Intel-gfx] [PATCH 3/4] scripts/kernel-doc: Adding infrastructure for markdown support
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-ker...@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|depe
[Intel-gfx] [PATCH 1/4] scripts/kernel-doc: Adding cross-reference links to html documentation.
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-ker...@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. +# +# us
[Intel-gfx] [PATCH 2/4] scripts/kernel-doc: Replacing highlights hash by an array
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-ker...@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 @high
[Intel-gfx] [PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc
This series add supports for hyperlink cross-references on Docbooks and an optional markup syntax for in-source Documentation. Danilo Cesar Lemes de Paula (4): scripts/kernel-doc: Adding cross-reference links to html documentation. scripts/kernel-doc: Replacing highlights hash by an array scripts/kernel-doc: Adding infrastructure for markdown support drm/doc: Convert to markdown Documentation/DocBook/Makefile | 68 + Documentation/DocBook/drm.tmpl | 86 drivers/gpu/drm/drm_modeset_lock.c | 14 ++- drivers/gpu/drm/drm_prime.c| 16 ++- drivers/gpu/drm/i915/i915_reg.h| 48 - include/drm/drm_vma_manager.h | 10 +- scripts/docproc.c | 49 ++--- scripts/kernel-doc | 170 ++- scripts/kernel-doc-xml-ref | 198 + 9 files changed, 444 insertions(+), 215 deletions(-) create mode 100755 scripts/kernel-doc-xml-ref -- 2.1.4 ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
[Intel-gfx] kernel-doc markdown support
Hey there, I've been discussing with Daniel Vetter about adding Markdown support to kernel-doc. There were some discussions about improving documentation flexibility and although there were no consensus at the time I believe (and I think others might agree) that Markdown is best suit for this job. First of all, it's already there, it's being used by md-files everywhere and it can add the flexibility we're looking for. Second, I believe it's a important point, it keeps the current in-source-documentation readable. I started that by writing my own markdown regex rules to be executed by dohighlight in kernel-doc. They started simple, but they get really complex over time and there's no good reason to create a yet-another-markdown-parser. So, my proposal here is to use an external tool to do this job, and my suggestion is pandoc [1], and use it inside kernel-doc. I know there's some perl libs (pandoc-elements-perl and pandoc-perl) around, but I couldn't get the same results using the first lib and the second one is not packaged by the main distros. pandoc is almost everywhere. My plan is to make it optional in the Makefile (if pandoc is installed, use it. Otherwise, you're going to get a lovelly warning and receive a simple documentation without fancy features). I'm also planning to split the Docbooks between those who are "markdown-ready" and those who aren't. I'm working mostly with the DRM docbook but it works with a good part of the current docbooks without changes (xmlto complains about tags in a few of them) I do have a few examples for the DRM Documentation: - Fixed-width / code examples: [1] with markdown support and without [2] markdown support. - bold/string style. [3] "*must*" with markdown support and without [4]. - List example: [5] a list with markdown support and without [6] Those examples almost didn't require any change on the current source code (it did require one: A fixed-width text in markdown requires four indent-spaces instead of two). With this approach we're also getting tables and other elements for free, I did test a few and they work, but there's no source-code example using them to show. Would like to know the opinion regarding this approach to continue this work. -- About the execution approach [7] (still a wip. Only the pandoc call is implemented). I'm basically using perl's IPC::open3 to call pandoc, sending each kernel-doc comment as the input and getting an output for it. I'm not a perl expert and not sure if that's the best way to do it so I'm taking suggestions. Thanks, Danilo Cesar Lemes de Paula [1] https://people.collabora.com/~danilo/intel/Documentation.MarkDown/DocBook/drm/API-drm-vma-offset-lock-lookup.html [2] https://people.collabora.com/~danilo/intel/Documentation.new/DocBook/drm/API-drm-vma-offset-lock-lookup.html [3] https://people.collabora.com/~danilo/intel/Documentation.MarkDown/DocBook/drm/API-drm-dev-ref.html [4] https://people.collabora.com/~danilo/intel/Documentation.new/DocBook/drm/API-drm-dev-ref.html [5] https://people.collabora.com/~danilo/intel/Documentation.MarkDown/DocBook/drm/drm-memory-management.html#idp65510432 [6] https://people.collabora.com/~danilo/intel/Documentation.new/DocBook/drm/drm-memory-management.html#idp64227024 [7] https://people.collabora.com/~danilo/intel/wip.patch ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
[Intel-gfx] [PATCH v3] scripts/kernel-doc: Adding cross-reference links to html documentation.
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-ker...@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
Re: [Intel-gfx] [PATCH v2] scripts/kernel-doc: Adding cross-reference links to html documentation.
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 > ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
[Intel-gfx] [PATCH v2] scripts/kernel-doc: Adding cross-reference links to html documentation.
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-ker...@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 %hi
Re: [Intel-gfx] [PATCH] scripts/kernel-doc: Adding cross-reference links to html documentation.
On 06/24/2015 06:22 PM, Daniel Vetter wrote: > On Wed, Jun 24, 2015 at 04:10:24PM -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. >> >> [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: 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 > > Already discussed on irc With Danilo but here for the record: I really > like this since it massively improves the usefulness of the docbooks we > have. One small thing I noticed though while clicking a bit more through > the generated html: It also generates selflinks, i.e. drm_crtc_vblank_on > links to itself. That one is a bit confusing. Could we filter out > self-links somehow on the reference sections? Yes we could! I'm sending a reviewed patch in a few minutes. - Danilo Cesar > -Daniel > >> >> Documentation/DocBook/Makefile | 34 +--- >> scripts/kernel-doc-xml-ref | 176 >> + >> 2 files changed, 197 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)) \
[Intel-gfx] [PATCH] scripts/kernel-doc: Adding cross-reference links to html documentation.
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: 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 | 176 +
2 files changed, 197 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..756e897
--- /dev/null
+++ b/scripts/kernel-doc-xml-ref
@@ -0,0 +1,176 @@
+#!/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 = (
+ "(.*?)",
+ "\"\
