Re: [PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an array
Hi, On Sun, Sep 13, 2015 at 02:36:47PM -0600, Jonathan Corbet wrote: > On Mon, 7 Sep 2015 17:01:59 -0300 > Danilo Cesar Lemes de Paula wrote: > > 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. > OK, I've spent a bunch of time with this, comparing the results before > and after. The output you mention is clearly wrong, but there might be > room to differ over what the root cause is. > > That output is caused by @device_for_each_child() in the comments. This > happens for a few other functions as well, and I think it's wrong. @ is > used to indicate parameters (or structure fields); I'm not sure why > people are using it for functions that are *not* one of the above. > Formatting the function names as a parameter doesn't seem right either. Shouldn't kernel-doc print a warning for syntactic mistakes like this rather than silently accomodating to it in whatever way? As to the usage of markdown in general, there's documentation coming up for vga_switcheroo which makes use of that so I'd love to see it merged: https://github.com/l1k/linux/commit/d1476d748b5f1adf5bffe8e0a8bafad1e879d22f https://github.com/l1k/linux/commit/11c55ae65788162970d8fa23cd1fd2518af55d34 The large set of dependencies pulled in on Fedora is likely to be blamed on the RedHat packaging being notoriously coarse-grained. By comparison, Debian is extremely fine-grained, kind of the opposite extreme, and therefore has comparatively few prerequisites: https://packages.debian.org/jessie/pandoc I do agree however that alternative tools with fewer dependencies should be supported and it would be great if the markdown patches were amended to that end. Best regards, Lukas -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an array
On Mon, 7 Sep 2015 17:01:59 -0300 Danilo Cesar Lemes de Paula wrote: > 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. OK, I've spent a bunch of time with this, comparing the results before and after. The output you mention is clearly wrong, but there might be room to differ over what the root cause is. That output is caused by @device_for_each_child() in the comments. This happens for a few other functions as well, and I think it's wrong. @ is used to indicate parameters (or structure fields); I'm not sure why people are using it for functions that are *not* one of the above. Formatting the function names as a parameter doesn't seem right either. There is the occasional case where the parameter *is* a function and the text uses the () notation (threadfn(), for example). Having the "parameter" style win out over the "function" style in such cases is OK, I guess, but it would be good to format the parentheses along with the name. The function patterns there now drop the parentheses entirely, which seems a bit strange to me. I guess I'll apply the patch; determinism is good, and it doesn't make anything screwy that wasn't already that way. But I think we should fix the misapplied @s and sort out function formatting in general. One of these days... Thanks, jon -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
[PATCH 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-kernel@vger.kernel.org Cc: linux-...@vger.kernel.org Cc: intel-gfx Cc: dri-devel --- scripts/kernel-doc | 104 ++--- 1 file changed, 60 insertions(+), 44 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 9a08fb5..0affe4f 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -206,59 +206,73 @@ my $type_env = '(\$\w+)'; # One for each output format # these work fairly well -my %highlights_html = ( $type_constant, "\$1", - $type_func, "\$1", - $type_struct_xml, "\$1", - $type_env, "\$1", - $type_param, "\$1" ); +my @highlights_html = ( + [$type_constant, "\$1"], + [$type_func, "\$1"], + [$type_struct_xml, "\$1"], + [$type_env, "\$1"], + [$type_param, "\$1"] + ); my $local_lt = "lt:"; my $local_gt = "gt:"; my $blankline_html = $local_lt . "p" . $local_gt; # was "" # html version 5 -my %highlights_html5 = ( $type_constant, "\$1", - $type_func, "\$1", - $type_struct_xml, "\$1", - $type_env, "\$1", - $type_param, "\$1" ); +my @highlights_html5 = ( +[$type_constant, "\$1"], +[$type_func, "\$1"], +[$type_struct_xml, "\$1"], +[$type_env, "\$1"], +[$type_param, "\$1]"] + ); my $blankline_html5 = $local_lt . "br /" . $local_gt; # XML, docbook format -my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2", - $type_constant, "\$1", - $type_func, "\$1", - $type_struct_xml, "\$1", - $type_env, "\$1", - $type_param, "\$1" ); +my @highlights_xml = ( + ["([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2"], + [$type_constant, "\$1"], + [$type_struct_xml, "\$1"], + [$type_param, "\$1"], + [$type_func, "\$1"], + [$type_env, "\$1"] +); my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n"; # gnome, docbook format -my %highlights_gnome = ( $type_constant, "\$1", -$type_func, "\$1", -$type_struct, "\$1", -$type_env, "\$1", -$type_param, "\$1" ); +my @highlights_gnome = ( +[$type_constant, "\$1"], +[$type_func, "\$1"], +[$type_struct, "\$1"], +[$type_env, "\$1"], +[$type_param, "\$1" ] + ); my $blankline_gnome = "\n"; # these are pretty rough -my %highlights_man = ( $type_constant, "\$1", - $type_func, "fB\$1fP", - $type_struct, "fI\$1fP", - $type_param, "fI\$1fP" ); +my @highlights_man = ( + [$type_constant, "\$1"], + [$type_func, "fB\$1fP"], + [$type_struct, "fI\$1fP"], + [$type_param, "fI\$1fP"] +); my $blankline_man = ""; # text-mode -my %highlights_text = ( $type_constant, "\$1", - $type_func, "\$1", - $type_struct, "\$1", - $type_param, "\$1" ); +my @highlights_text = ( + [$type_constant, "\$1"], + [$type_func, "\$1"], + [$type_struct, "\$1"], + [$type_param, "\$1"] + ); my $blankline_text = ""; # list mode -my %highlights_list = ( $type_constant, "\$1", - $type_func, "\$1", - $type_struct, "\$1", - $type_param, "\$1" ); +my @highlights_list = ( + [$type_constant, "\$1"], + [$type_func, "\$1"], + [$type_struct, "\$1"], + [$ty
