From: Jonathan Corbet <corbet@lwn.net>
To: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org, Jani Nikula <jani.nikula@intel.com>,
Daniel Vetter <daniel.vetter@ffwll.ch>,
Jonathan Corbet <corbet@lwn.net>, Daniel Vetter <daniel@ffwll.ch>
Subject: [PATCH 1/4] kernel-doc: add support for asciidoc output
Date: Mon, 25 Jan 2016 16:28:39 -0700 [thread overview]
Message-ID: <1453764522-29030-2-git-send-email-corbet@lwn.net> (raw)
In-Reply-To: <1453764522-29030-1-git-send-email-corbet@lwn.net>
From: Jani Nikula <jani.nikula@intel.com>
Add new -asciidoc option to produce asciidoc output from kernel-doc. The
output is formatted internally, with no dependencies on external
tools. Any asciidoc formatting present in kernel-doc will naturally be
present in the resulting asciidoc as well.
Highlighting of functions(), &struct structures, &enum enumerations,
@parameters, etc. will be done by means of asciidoc. Anchors and
cross-references are added as well, providing hyperlinking support in
the result processed by asciidoc(1).
This support is non-conflicting and orthogonal to the patches adding
asciidoc support to the kernel-doc DocBook output [1]. Those patches
bolt on to the current document generation pipeline; there is currently
none for native asciidoc in the kernel (though ideas have been discussed
[2]). At this time, this patch should be considered a worthwhile
standalone improvement to kernel-doc, independent of the rest.
[1] http://mid.gmane.org/1448471279-19748-1-git-send-email-daniel.vetter@ffwll.ch
[2] http://mid.gmane.org/20160114131823.2ff43a0c@lwn.net
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Daniel Vetter <daniel@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
scripts/kernel-doc | 237 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 237 insertions(+)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c37255b..06f1649 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -201,6 +201,8 @@ my $type_param = '\@(\w+)';
my $type_struct = '\&((struct\s*)*[_\w]+)';
my $type_struct_xml = '\\&((struct\s*)*[_\w]+)';
my $type_env = '(\$\w+)';
+my $type_enum_full = '\&(enum)\s*([_\w]+)';
+my $type_struct_full = '\&(struct)\s*([_\w]+)';
# Output conversion substitutions.
# One for each output format
@@ -266,6 +268,17 @@ my @highlights_text = (
);
my $blankline_text = "";
+# asciidoc-mode
+my @highlights_asciidoc = (
+ [$type_constant, "`\$1`"],
+ [$type_func, "<<func_\$1,`\$1()`>>"],
+ [$type_struct_full, "<<\$1_\$2,`\$1 \$2`>>"],
+ [$type_enum_full, "<<\$1_\$2,`\$1 \$2`>>"],
+ [$type_struct, "<<struct_\$1,`\$1`>>"],
+ [$type_param, "*\$1*"]
+ );
+my $blankline_asciidoc = "\n";
+
# list mode
my @highlights_list = (
[$type_constant, "\$1"],
@@ -402,6 +415,10 @@ while ($ARGV[0] =~ m/^-(.*)/) {
$output_mode = "text";
@highlights = @highlights_text;
$blankline = $blankline_text;
+ } elsif ($cmd eq "-asciidoc") {
+ $output_mode = "asciidoc";
+ @highlights = @highlights_asciidoc;
+ $blankline = $blankline_asciidoc;
} elsif ($cmd eq "-docbook") {
$output_mode = "xml";
@highlights = @highlights_xml;
@@ -1713,6 +1730,214 @@ sub output_blockhead_text(%) {
}
}
+##
+# output in asciidoc
+sub output_highlight_asciidoc {
+ my $contents = join "\n",@_;
+ my $line;
+
+ # undo the evil effects of xml_escape() earlier
+ $contents = xml_unescape($contents);
+
+ eval $dohighlight;
+ die $@ if $@;
+
+ foreach $line (split "\n", $contents) {
+ if ($line eq "") {
+ print $lineprefix, $blankline;
+ } else {
+ $line =~ s/\\\\\\/\&/g;
+ print $lineprefix, $line;
+ }
+ print "\n";
+ }
+}
+
+sub output_function_asciidoc(%) {
+ my %args = %{$_[0]};
+ my ($parameter, $section);
+ my $start;
+
+ print "[[func_$args{'function'}]]\n";
+ print "=== " . $args{'function'} . " ===\n";
+ print $args{'purpose'} . "\n\n";
+
+ print "----------\n";
+ if ($args{'functiontype'} ne "") {
+ $start = $args{'functiontype'} . " " . $args{'function'} . " (";
+ } else {
+ $start = $args{'function'} . " (";
+ }
+ print $start;
+
+ my $count = 0;
+ foreach my $parameter (@{$args{'parameterlist'}}) {
+ $type = $args{'parametertypes'}{$parameter};
+ if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
+ # pointer-to-function
+ print $1 . $parameter . ") (" . $2;
+ } else {
+ print $type . " " . $parameter;
+ }
+ if ($count != $#{$args{'parameterlist'}}) {
+ $count++;
+ print ",\n";
+ print " " x length($start);
+ } else {
+ print ");\n\n";
+ }
+ }
+ print "----------\n";
+
+ print ".Parameters\n";
+ print "[horizontal]\n";
+ foreach $parameter (@{$args{'parameterlist'}}) {
+ my $parameter_name = $parameter;
+ $parameter_name =~ s/\[.*//;
+ $type = $args{'parametertypes'}{$parameter};
+
+ print "`$type $parameter`::\n";
+ if ($args{'parameterdescs'}{$parameter_name} ne $undescribed) {
+ $blankline = "+";
+ output_highlight_asciidoc($args{'parameterdescs'}{$parameter_name});
+ $blankline = "\n";
+ } else {
+ print "_undescribed_\n";
+ }
+ print "\n";
+ }
+ output_section_asciidoc(@_);
+}
+
+sub output_section_asciidoc(%) {
+ my %args = %{$_[0]};
+ my $section;
+
+ foreach $section (@{$args{'sectionlist'}}) {
+ print ".$section\n\n";
+ output_highlight_asciidoc($args{'sections'}{$section});
+ print "\n";
+ }
+ print "\n";
+}
+
+sub output_enum_asciidoc(%) {
+ my %args = %{$_[0]};
+ my ($parameter);
+ my $count;
+
+ print "[[enum_$args{'enum'}]]\n";
+ print "=== enum " . $args{'enum'} . " ===\n";
+ print $args{'purpose'} . "\n\n";
+
+ print "----------\n";
+ print "enum " . $args{'enum'} . " {\n";
+ $count = 0;
+ foreach $parameter (@{$args{'parameterlist'}}) {
+ print "\t$parameter";
+ if ($count != $#{$args{'parameterlist'}}) {
+ $count++;
+ print ",";
+ }
+ print "\n";
+ }
+ print "};\n";
+ print "----------\n";
+
+ print ".Constants\n";
+ print "[horizontal]\n";
+ foreach $parameter (@{$args{'parameterlist'}}) {
+ print "`$parameter`::\n";
+ if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
+ $blankline = "+";
+ output_highlight_asciidoc($args{'parameterdescs'}{$parameter});
+ $blankline = "\n";
+ } else {
+ print "_undescribed_\n";
+ }
+ print "\n";
+ }
+
+ output_section_asciidoc(@_);
+}
+
+sub output_typedef_asciidoc(%) {
+ my %args = %{$_[0]};
+ my ($parameter);
+ my $count;
+
+ print "[[$args{'typedef'}]]\n";
+ print "=== typedef " . $args{'typedef'} . " ===\n";
+ print $args{'purpose'} . "\n\n";
+
+ output_section_asciidoc(@_);
+}
+
+sub output_struct_asciidoc(%) {
+ my %args = %{$_[0]};
+ my ($parameter);
+
+ print "[[$args{'type'}_$args{'struct'}]]\n";
+ print "=== " . $args{'type'} . " " . $args{'struct'} . " ===\n";
+ print $args{'purpose'} . "\n\n";
+
+ print "----------\n";
+ print $args{'type'} . " " . $args{'struct'} . " {\n";
+ foreach $parameter (@{$args{'parameterlist'}}) {
+ if ($parameter =~ /^#/) {
+ print "$parameter\n";
+ next;
+ }
+
+ my $parameter_name = $parameter;
+ $parameter_name =~ s/\[.*//;
+
+ ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
+ $type = $args{'parametertypes'}{$parameter};
+ if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
+ # pointer-to-function
+ print "\t$1 $parameter) ($2);\n";
+ } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
+ # bitfield
+ print "\t$1 $parameter$2;\n";
+ } else {
+ print "\t" . $type . " " . $parameter . ";\n";
+ }
+ }
+ print "};\n";
+ print "----------\n";
+
+ print ".Members\n";
+ print "[horizontal]\n";
+ foreach $parameter (@{$args{'parameterlist'}}) {
+ ($parameter =~ /^#/) && next;
+
+ my $parameter_name = $parameter;
+ $parameter_name =~ s/\[.*//;
+
+ ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
+ $type = $args{'parametertypes'}{$parameter};
+ print "`$type $parameter`" . "::\n";
+ $blankline = "+";
+ output_highlight_asciidoc($args{'parameterdescs'}{$parameter_name});
+ $blankline = "\n";
+ print "\n";
+ }
+ print "\n";
+ output_section_asciidoc(@_);
+}
+
+sub output_blockhead_asciidoc(%) {
+ my %args = %{$_[0]};
+ my ($parameter, $section);
+
+ foreach $section (@{$args{'sectionlist'}}) {
+ print "=== $section ===\n";
+ output_highlight_asciidoc($args{'sections'}{$section});
+ print "\n";
+ }
+}
+
## list mode output functions
sub output_function_list(%) {
@@ -2414,6 +2639,18 @@ sub xml_escape($) {
return $text;
}
+# xml_unescape: reverse the effects of xml_escape
+sub xml_unescape($) {
+ my $text = shift;
+ if (($output_mode eq "text") || ($output_mode eq "man")) {
+ return $text;
+ }
+ $text =~ s/\\\\\\amp;/\&/g;
+ $text =~ s/\\\\\\lt;/</g;
+ $text =~ s/\\\\\\gt;/>/g;
+ return $text;
+}
+
# convert local escape strings to html
# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
sub local_unescape($) {
--
2.7.0
next prev parent reply other threads:[~2016-01-25 23:29 UTC|newest]
Thread overview: 31+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-01-25 23:28 [RFC] A first shot at asciidoc-based formatted docs Jonathan Corbet
2016-01-25 23:28 ` Jonathan Corbet [this message]
2016-01-25 23:28 ` [PATCH 2/4] docproc: handle asciidoc templates Jonathan Corbet
2016-01-25 23:28 ` [PATCH 3/4] Docs: Makefile tweaks for " Jonathan Corbet
2016-01-25 23:28 ` [PATCH 4/4] Docs: add a sample asciidoc template Jonathan Corbet
2016-01-26 12:08 ` [RFC] A first shot at asciidoc-based formatted docs Jani Nikula
2016-01-26 12:08 ` [RFC 01/10] kernel-doc: rewrite usage description, remove duplicated comments Jani Nikula
2016-01-26 12:08 ` [RFC 02/10] kernel-doc: add support for asciidoc output Jani Nikula
2016-01-26 12:08 ` [RFC 03/10] kernel-doc: support printing exported and non-exported symbols Jani Nikula
2016-01-26 12:08 ` [RFC 04/10] kernel-doc: add support for printing DOC: comments with escaped names Jani Nikula
2016-01-26 12:08 ` [RFC 05/10] scripts: add asciidoc-includes to extract includes from asciidoc Jani Nikula
2016-01-26 12:08 ` [RFC 06/10] scripts: add a kernel-doc helper for special invocation Jani Nikula
2016-01-26 12:08 ` [RFC 07/10] scripts: add tool for generating asciidoc dependencies and rules Jani Nikula
2016-01-26 12:08 ` [RFC 08/10] scripts: add a crude converter from DocBook tmpl to asciidoc Jani Nikula
2016-01-26 12:08 ` [RFC 09/10] Documentation: convert gpu.tmpl to gpu.txt Jani Nikula
2016-01-26 12:08 ` [RFC 10/10] Documentation: build asciidoc documentation Jani Nikula
2016-01-26 12:17 ` [RFC] A first shot at asciidoc-based formatted docs Daniel Vetter
2016-01-26 12:38 ` Jani Nikula
2016-01-26 14:48 ` Jonathan Corbet
2016-01-26 14:52 ` Jonathan Corbet
2016-02-10 0:09 ` Jonathan Corbet
2016-02-10 8:07 ` Daniel Vetter
2016-02-10 14:03 ` Jani Nikula
2016-02-10 16:12 ` Jani Nikula
2016-02-10 20:56 ` Jonathan Corbet
2016-02-11 15:18 ` Keith Packard
2016-02-10 20:45 ` Jonathan Corbet
2016-02-10 23:01 ` Keith Packard
2016-02-11 13:44 ` Jani Nikula
2016-02-11 15:21 ` Keith Packard
2016-02-13 3:20 ` Keith Packard
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1453764522-29030-2-git-send-email-corbet@lwn.net \
--to=corbet@lwn.net \
--cc=daniel.vetter@ffwll.ch \
--cc=daniel@ffwll.ch \
--cc=jani.nikula@intel.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®