[PATCH 04/25] scripts/kernel-doc: Use asciidoc instead of markdown

[Ander Conselvan de Oliveira]

From: Daniel Vetter <daniel.vetter at ffwll.ch>

When discussing with Dave at KS whether we could do some kind of markup
for drm only he asked me to use asciidoc instead of pandoc. Both to
avoid "oh noes, Haskell" backlash due to pandoc, and as a bonus
asciidoc also has more powerful table support. Otherwise the markup is
really similar (no fixups needed for current DRM docs), so this is
just a tooling change.

This needs some adjustment/fixups after feeding snippets to asciidoc
since compared to markdown asciidown escapes xml markup and doesn't
just let it through.

The other noticeable change is that build times increase a lot - we
need to launch the markup process per-snippet, there's a few thousand
of them and asciidoc (python) has a substantial higher overhead per
invocation than pandoc (haskell).

v2: More fine-tuning:

- Use unixe newlines, not the default dos ones. Only results in
  ugliness in the intermediate gpu.xml, but still.

- Resurrect the hack to remove paragraphs for the one-line references.
  Like markdown asciidoc insists to wrap everything.

v3: Improve commit message a bit (Jani).

v4: Unescape harder in markdown_unescape. This is a bugfix for
Danilo's patch, which I only noticed now that I tried using some
quotes with < and > in them.

Cc: Danilo Cesar Lemes de Paula <danilo.cesar at collabora.co.uk>
Cc: Thomas Wood <thomas.wood at intel.com>
Cc: Jonathan Corbet <corbet at lwn.net>
Cc: Jani Nikula <jani.nikula at linux.intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
---
 Documentation/DocBook/Makefile |  6 +++---
 scripts/kernel-doc             | 23 ++++++++++++++++++-----
 2 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 246ad38..5335955 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -104,8 +104,8 @@ define rule_docproc
 endef
 
 %.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
-	@(which pandoc > /dev/null 2>&1) || \
-	(echo "*** To get propper documentation you need to install pandoc ***";)
+	@(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
@@ -116,7 +116,7 @@ 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)
+ifneq ($(shell which asciidoc >/dev/null 2>&1 && echo found),found)
 	MARKDOWNREADY := "";
 endif
 
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e01e74f..cc4bfbe 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -524,7 +524,7 @@ sub dump_doc_section {
 sub markdown_to_docbook {
 	my $orig_content = $_[0];
 
-	my $pid = open3( \*CHLD_IN, \*CHLD_OUT, \*CHLD_ERR, "pandoc  --columns=80 -f markdown -t docbook" );
+	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);
@@ -540,9 +540,9 @@ sub markdown_to_docbook {
 	close(CHLD_ERR);
 
 	if ($output_markdown_nopara) {
-		# pandoc insists in adding Main <para></para>, sometimes we
-		# want to remove them.
-		$content =~ s:\A\s*<para>\s*\n(.*)\n</para>\Z$:$1:egsm;
+		# asciidoc insists in adding Main <simpara></simpara>, sometimes
+		# we want to remove them.
+		$content =~ s:\A\s*<simpara>(.*)</simpara>\Z:$1:egsm;
 	}
 
 	return $content;
@@ -550,6 +550,7 @@ sub markdown_to_docbook {
 
 # Markdown->Docbook conversion by pandoc requires unescaped text
 # Kernel-doc converts every & to "&", we need to convert it back.
+# This essentially does the inverse of xml_escape()
 sub markdown_unescape
 {
 	my $text = shift;
@@ -558,7 +559,9 @@ sub markdown_unescape
 	my @result;
 	foreach my $line (@lines) {
 		if ( $line =~ m /^    /s ) {
-			$line =~ s:\&:\&:gs
+			$line =~ s:\&:\&:gs;
+			$line =~ s:\<:\<:gs;
+			$line =~ s:\>:\>:gs;
 		}
 		push @result, $line;
 	}
@@ -605,6 +608,16 @@ sub output_highlight {
 #   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/<quote>(\S*)<\/quote>/<quote>$1<\/quote>/g;
+	$contents =~ s/<constant>(\S*)<\/constant>/<constant>$1<\/constant>/g;
+	$contents =~ s/<structname>(\S*)<\/structname>/<structname>$1<\/structname>/g;
+	$contents =~ s/<parameter>(\S*)<\/parameter>/<parameter>$1<\/parameter>/g;
+	$contents =~ s/<function>(\S*)<\/function>/<function>$1<\/function>/g;
+	$contents =~ s/<envar>(\S*)<\/envar>/<envar>$1<\/envar>/g;
     }
 
 #   strip whitespaces when generating html5
-- 
2.5.5