summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJani Nikula <jani.nikula@intel.com>2016-04-13 16:00:41 +0300
committerJani Nikula <jani.nikula@intel.com>2016-04-13 16:00:41 +0300
commitaf0885c704cd696937b2a1e59bfa37f597de98ba (patch)
tree1a733e8ae77e3812aa5c95273139596d4c981a0a
parent165ef8f5bc84f51c22d9156b7b9b039e9a61506f (diff)
parent418645fdcc72b92df6817ec249e216700baa757a (diff)
Merge remote-tracking branch 'origin/topic/kerneldoc' into drm-intel-nightly
-rw-r--r--Documentation/DocBook/Makefile25
-rw-r--r--scripts/docproc.c54
-rwxr-xr-xscripts/kernel-doc123
3 files changed, 164 insertions, 38 deletions
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index d70f9b68174e..30f01e65ce1c 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -17,6 +17,8 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
tracepoint.xml gpu.xml media_api.xml w1.xml \
writing_musb_glue_layer.xml crypto-API.xml iio.xml
+MARKDOWNREADY := gpu.xml
+
include Documentation/DocBook/media/Makefile
###
@@ -86,18 +88,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 asciidoc > /dev/null 2>&1) || \
+ (echo "*** To get propper documentation you need to install asciidoc ***";)
$(call if_changed_rule,docproc)
# Tell kbuild to always build the programs
@@ -108,6 +115,10 @@ notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \
db2xtemplate = db2TYPE -o $(dir $@) $<
xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
+ifneq ($(shell which asciidoc >/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 e267e621431a..7c6b225a6a50 100644
--- a/scripts/docproc.c
+++ b/scripts/docproc.c
@@ -73,12 +73,15 @@ FILELINE * docsection;
#define NOFUNCTION "-nofunction"
#define NODOCSECTIONS "-no-doc-sections"
#define SHOWNOTFOUND "-show-not-found"
+#define USEMARKDOWN "-use-markdown"
static char *srctree, *kernsrctree;
static char **all_list = NULL;
static int all_list_len = 0;
+static int use_markdown = 0;
+
static void consume_symbol(const char *sym)
{
int i;
@@ -95,10 +98,11 @@ static void consume_symbol(const char *sym)
static void usage (void)
{
- fprintf(stderr, "Usage: docproc {doc|depend} file\n");
+ fprintf(stderr, "Usage: docproc {doc|depend} [-use-markdown] file\n");
fprintf(stderr, "Input is read from file.tmpl. Output is sent to stdout\n");
fprintf(stderr, "doc: frontend when generating kernel documentation\n");
fprintf(stderr, "depend: generate list of files referenced within file\n");
+ fprintf(stderr, "-use-markdown: pass -use-markdown to kernel-doc\n");
fprintf(stderr, "Environment variable SRCTREE: absolute path to sources.\n");
fprintf(stderr, " KBUILD_SRC: absolute path to kernel source tree.\n");
}
@@ -257,12 +261,15 @@ static void docfunctions(char * filename, char * type)
for (i=0; i <= symfilecnt; i++)
symcnt += symfilelist[i].symbolcnt;
- vec = malloc((2 + 2 * symcnt + 3) * sizeof(char *));
+ vec = malloc((2 + 2 * symcnt + 4) * sizeof(char *));
if (vec == NULL) {
perror("docproc: ");
exit(1);
}
vec[idx++] = KERNELDOC;
+ if (use_markdown)
+ vec[idx++] = USEMARKDOWN;
+
vec[idx++] = DOCBOOK;
vec[idx++] = NODOCSECTIONS;
for (i=0; i < symfilecnt; i++) {
@@ -294,6 +301,9 @@ static void singfunc(char * filename, char * line)
int i, idx = 0;
int startofsym = 1;
vec[idx++] = KERNELDOC;
+ if (use_markdown)
+ vec[idx++] = USEMARKDOWN;
+
vec[idx++] = DOCBOOK;
vec[idx++] = SHOWNOTFOUND;
@@ -328,8 +338,9 @@ static void singfunc(char * filename, char * line)
static void docsect(char *filename, char *line)
{
/* kerneldoc -docbook -show-not-found -function "section" file NULL */
- char *vec[7];
+ char *vec[8];
char *s;
+ int idx = 0;
for (s = line; *s; s++)
if (*s == '\n')
@@ -342,30 +353,37 @@ static void docsect(char *filename, char *line)
consume_symbol(s);
free(s);
- vec[0] = KERNELDOC;
- vec[1] = DOCBOOK;
- vec[2] = SHOWNOTFOUND;
- vec[3] = FUNCTION;
- vec[4] = line;
- vec[5] = filename;
- vec[6] = NULL;
+ vec[idx++] = KERNELDOC;
+ if (use_markdown)
+ vec[idx++] = USEMARKDOWN;
+
+ vec[idx++] = DOCBOOK;
+ vec[idx++] = SHOWNOTFOUND;
+ vec[idx++] = FUNCTION;
+ vec[idx++] = line;
+ vec[idx++] = filename;
+ vec[idx] = NULL;
exec_kernel_doc(vec);
}
static void find_all_symbols(char *filename)
{
- char *vec[4]; /* kerneldoc -list file NULL */
+ char *vec[5]; /* kerneldoc -list file NULL */
pid_t pid;
int ret, i, count, start;
char real_filename[PATH_MAX + 1];
int pipefd[2];
char *data, *str;
size_t data_len = 0;
+ int idx = 0;
+
+ vec[idx++] = KERNELDOC;
+ if (use_markdown)
+ vec[idx++] = USEMARKDOWN;
- vec[0] = KERNELDOC;
- vec[1] = LIST;
- vec[2] = filename;
- vec[3] = NULL;
+ vec[idx++] = LIST;
+ vec[idx++] = filename;
+ vec[idx] = NULL;
if (pipe(pipefd)) {
perror("pipe");
@@ -509,7 +527,7 @@ int main(int argc, char *argv[])
kernsrctree = getenv("KBUILD_SRC");
if (!kernsrctree || !*kernsrctree)
kernsrctree = srctree;
- if (argc != 3) {
+ if (argc < 3 || argc > 4) {
usage();
exit(1);
}
@@ -521,6 +539,10 @@ int main(int argc, char *argv[])
exit(2);
}
+ if (argc == 4 && strcmp("-use-markdown", argv[3]) == 0) {
+ use_markdown = 1;
+ }
+
if (strcmp("doc", argv[1]) == 0) {
/* Need to do this in two passes.
* First pass is used to collect all symbols exported
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c37255bb620d..96182cdc2233 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1,6 +1,7 @@
#!/usr/bin/perl -w
use strict;
+use IPC::Open3;
## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
@@ -282,10 +283,12 @@ if ($#ARGV == -1) {
my $kernelversion;
my $dohighlight = "";
+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;
@@ -424,6 +427,8 @@ while ($ARGV[0] =~ m/^-(.*)/) {
$function_only = 2;
$function = shift @ARGV;
$function_table{$function} = 1;
+ } elsif ($cmd eq "-use-markdown") {
+ $use_markdown = 1;
} elsif ($cmd eq "-v") {
$verbose = 1;
} elsif (($cmd eq "-h") || ($cmd eq "--help")) {
@@ -442,6 +447,7 @@ sub usage {
print " [ -no-doc-sections ]\n";
print " [ -function funcname [ -function funcname ...] ]\n";
print " [ -nofunction funcname [ -nofunction funcname ...] ]\n";
+ print " [ -use-markdown ]\n";
print " [ -v ]\n";
print " c source file(s) > outputfile\n";
print " -v : verbose output, more warnings & other info listed\n";
@@ -515,6 +521,55 @@ sub dump_doc_section {
}
}
+sub markdown_to_docbook {
+ my $orig_content = $_[0];
+
+ my $pid = open3( \*CHLD_IN, \*CHLD_OUT, \*CHLD_ERR, "asciidoc -a 'newline=\\n' --no-header-footer --backend=docbook45 -" );
+
+ print CHLD_IN "$orig_content";
+ close(CHLD_IN);
+
+ waitpid($pid, 0);
+
+ my $content = "";
+ chomp(my @lines = <CHLD_OUT>);
+ foreach my $line (@lines) {
+ $content .= $line . "\n";
+ }
+ close(CHLD_OUT);
+ close(CHLD_ERR);
+
+ if ($output_markdown_nopara) {
+ # asciidoc insists in adding Main <simpara></simpara>, sometimes
+ # we want to remove them.
+ $content =~ s:\A\s*<simpara>(.*)</simpara>\Z:$1:egsm;
+ }
+
+ return $content;
+}
+
+# Markdown->Docbook conversion by pandoc requires unescaped text
+# Kernel-doc converts every & to "&amp;", we need to convert it back.
+# This essentially does the inverse of xml_escape()
+sub markdown_unescape
+{
+ my $text = shift;
+ my @lines = split /\n/, $text;
+
+ my @result;
+ foreach my $line (@lines) {
+ if ( $line =~ m /^ /s ) {
+ $line =~ s:\&amp;:\&:gs;
+ $line =~ s:\&lt;:\<:gs;
+ $line =~ s:\&gt;:\>:gs;
+ }
+ push @result, $line;
+ }
+
+ return join "\n",@result;
+
+}
+
##
# output function
#
@@ -541,11 +596,29 @@ sub output_highlight {
$contents = local_unescape($contents);
# convert data read & converted thru xml_escape() into &xyz; format:
$contents =~ s/\\\\\\/\&/g;
+
+ if ($use_markdown) {
+ $contents = markdown_unescape($contents);
+ }
}
+
# print STDERR "contents b4:$contents\n";
eval $dohighlight;
die $@ if $@;
# print STDERR "contents af:$contents\n";
+ if ($use_markdown) {
+ $contents = markdown_to_docbook($contents);
+
+ # Compared to markdown asciidoc doesn't let through arbitrary xml
+ # markup. We need to un-escape the kerneldoc markup for functions,
+ # structures, ...
+ $contents =~ s/&lt;quote&gt;(\S*)&lt;\/quote&gt;/<quote>$1<\/quote>/g;
+ $contents =~ s/&lt;constant&gt;(\S*)&lt;\/constant&gt;/<constant>$1<\/constant>/g;
+ $contents =~ s/&lt;structname&gt;(\S*)&lt;\/structname&gt;/<structname>$1<\/structname>/g;
+ $contents =~ s/&lt;parameter&gt;(\S*)&lt;\/parameter&gt;/<parameter>$1<\/parameter>/g;
+ $contents =~ s/&lt;function&gt;(\S*)&lt;\/function&gt;/<function>$1<\/function>/g;
+ $contents =~ s/&lt;envar&gt;(\S*)&lt;\/envar&gt;/<envar>$1<\/envar>/g;
+ }
# strip whitespaces when generating html5
if ($output_mode eq "html5") {
@@ -553,11 +626,12 @@ sub output_highlight {
$contents =~ s/\s+$//;
}
foreach $line (split "\n", $contents) {
- if (! $output_preformatted) {
+ if (! $output_preformatted &&
+ !($use_markdown && $line =~ m /^ /s)) {
$line =~ s/^\s*//;
}
if ($line eq ""){
- if (! $output_preformatted) {
+ if (! $output_preformatted && ! $use_markdown) {
print $lineprefix, local_unescape($blankline);
}
} else {
@@ -974,16 +1048,19 @@ sub output_section_xml(%) {
print "<refsect1>\n";
print "<title>$section</title>\n";
if ($section =~ m/EXAMPLE/i) {
- print "<informalexample><programlisting>\n";
+ print "<informalexample>\n";
+ # programlisting is already included by pandoc
+ print "<programlisting>\n" unless $use_markdown;
$output_preformatted = 1;
- } else {
+ } elsif (! $use_markdown) {
print "<para>\n";
}
output_highlight($args{'sections'}{$section});
$output_preformatted = 0;
if ($section =~ m/EXAMPLE/i) {
- print "</programlisting></informalexample>\n";
- } else {
+ print "</programlisting>\n" unless $use_markdown;
+ print "</informalexample>\n";
+ } elsif (! $use_markdown) {
print "</para>\n";
}
print "</refsect1>\n";
@@ -1015,7 +1092,9 @@ sub output_function_xml(%) {
print " <refname>" . $args{'function'} . "</refname>\n";
print " <refpurpose>\n";
print " ";
+ $output_markdown_nopara = 1;
output_highlight ($args{'purpose'});
+ $output_markdown_nopara = 0;
print " </refpurpose>\n";
print "</refnamediv>\n";
@@ -1053,10 +1132,12 @@ sub output_function_xml(%) {
$parameter_name =~ s/\[.*//;
print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
- print " <listitem>\n <para>\n";
+ print " <listitem>\n";
+ print " <para>\n" unless $use_markdown;
$lineprefix=" ";
output_highlight($args{'parameterdescs'}{$parameter_name});
- print " </para>\n </listitem>\n </varlistentry>\n";
+ print " </para>\n" unless $use_markdown;
+ print " </listitem>\n </varlistentry>\n";
}
print " </variablelist>\n";
} else {
@@ -1092,7 +1173,9 @@ sub output_struct_xml(%) {
print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n";
print " <refpurpose>\n";
print " ";
+ $output_markdown_nopara = 1;
output_highlight ($args{'purpose'});
+ $output_markdown_nopara = 0;
print " </refpurpose>\n";
print "</refnamediv>\n";
@@ -1145,9 +1228,11 @@ sub output_struct_xml(%) {
($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
print " <varlistentry>";
print " <term>$parameter</term>\n";
- print " <listitem><para>\n";
+ print " <listitem>\n";
+ print " <para>\n" unless $use_markdown;
output_highlight($args{'parameterdescs'}{$parameter_name});
- print " </para></listitem>\n";
+ print " </para>\n" unless $use_markdown;
+ print " </listitem>\n";
print " </varlistentry>\n";
}
print " </variablelist>\n";
@@ -1186,7 +1271,9 @@ sub output_enum_xml(%) {
print " <refname>enum " . $args{'enum'} . "</refname>\n";
print " <refpurpose>\n";
print " ";
+ $output_markdown_nopara = 1;
output_highlight ($args{'purpose'});
+ $output_markdown_nopara = 0;
print " </refpurpose>\n";
print "</refnamediv>\n";
@@ -1216,9 +1303,11 @@ sub output_enum_xml(%) {
print " <varlistentry>";
print " <term>$parameter</term>\n";
- print " <listitem><para>\n";
+ print " <listitem>\n";
+ print " <para>\n" unless $use_markdown;
output_highlight($args{'parameterdescs'}{$parameter_name});
- print " </para></listitem>\n";
+ print " </para>\n" unless $use_markdown;
+ print " </listitem>\n";
print " </varlistentry>\n";
}
print " </variablelist>\n";
@@ -1284,14 +1373,14 @@ sub output_blockhead_xml(%) {
if ($section =~ m/EXAMPLE/i) {
print "<example><para>\n";
$output_preformatted = 1;
- } else {
+ } elsif (! $use_markdown) {
print "<para>\n";
}
output_highlight($args{'sections'}{$section});
$output_preformatted = 0;
if ($section =~ m/EXAMPLE/i) {
print "</para></example>\n";
- } else {
+ } elsif (! $use_markdown) {
print "</para>";
}
if (!$args{'content-only'}) {
@@ -2664,7 +2753,11 @@ sub process_file($) {
{
if ( $1 eq "" )
{
- $contents .= $blankline;
+ if ($use_markdown) {
+ $contents .= "\n";
+ } else {
+ $contents .= $blankline;
+ }
}
else
{