diff mbox

[07/10] sphinx: cheesy script to convert .tmpl files

Message ID 258eebc2e71c28bf6aaf6ac5a45a6318b3a9419d.1463748027.git.jani.nikula@intel.com
State Superseded
Headers show

Commit Message

Jani Nikula May 20, 2016, 1:39 p.m. UTC 
From: Jonathan Corbet <corbet@lwn.net>


This script uses pandoc to convert existing DocBook template files to RST
templates.  A couple of sed scripts are need to massage things both before
and after the conversion, but the result is then usable with no hand
editing.

[Jani: Change usage to tmplcvt <in> <out>. Fix escaping for docproc
directives. Add support the new kernel-doc extension.]

Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Signed-off-by: Jani Nikula <jani.nikula@intel.com>

---
 Documentation/sphinx/convert_template.sed | 14 ++++++++++++++
 Documentation/sphinx/post_convert.sed     | 19 +++++++++++++++++++
 Documentation/sphinx/tmplcvt              | 19 +++++++++++++++++++
 3 files changed, 52 insertions(+)
 create mode 100644 Documentation/sphinx/convert_template.sed
 create mode 100644 Documentation/sphinx/post_convert.sed
 create mode 100755 Documentation/sphinx/tmplcvt

-- 
2.1.4
diff mbox

Patch

diff --git a/Documentation/sphinx/convert_template.sed b/Documentation/sphinx/convert_template.sed
new file mode 100644
index 000000000000..d53bb8220a26
--- /dev/null
+++ b/Documentation/sphinx/convert_template.sed
@@ -0,0 +1,14 @@ 
+#
+# Pandoc doesn't grok <function> or <structname>, so convert them
+# ahead of time.
+#
+# Use "$bq" instead of "`" so that pandoc won't mess with it.
+#
+s%<function>\([^<(]\+\)()</function>%:c:func:$bq\1$bq%g
+s%<function>\([^<(]\+\)</function>%:c:func:$bq\1$bq%g
+s%<structname>struct *\([^<]\+\)</structname>%:ref:$bqstruct \1$bq%g
+s%<structname>\([^<]\+\)</structname>%:ref:$bqstruct \1$bq%g
+#
+# Wrap docproc directives in para and code blocks.
+#
+s%^\(!.*\)$%<para><code>DOCPROC: \1</code></para>%
diff --git a/Documentation/sphinx/post_convert.sed b/Documentation/sphinx/post_convert.sed
new file mode 100644
index 000000000000..ce17049f6a8e
--- /dev/null
+++ b/Documentation/sphinx/post_convert.sed
@@ -0,0 +1,19 @@ 
+#
+# pandoc thinks that both "_" needs to be escaped.  Remove the extra
+# backslashes.  Also put in proper backquotes now that pandoc won't quote
+# them.
+#
+s/$bq/`/g
+s/\\_/_/g
+#
+# Unwrap docproc directives.
+#
+s/^``DOCPROC: !E\(.*\)``$/.. kernel-doc:: \1\n   :export:/
+s/^``DOCPROC: !I\(.*\)``$/.. kernel-doc:: \1\n   :internal:/
+s/^``DOCPROC: !F\([^ ]*\) \(.*\)``$/.. kernel-doc:: \1\n   :functions: \2/
+s/^``DOCPROC: !P\([^ ]*\) \(.*\)``$/.. kernel-doc:: \1\n   :doc: \2/
+s/^``DOCPROC: \(!.*\)``$/.. WARNING: DOCPROC directive not supported: \1/
+#
+# Trim trailing whitespace.
+#
+s/[[:space:]]*$//
diff --git a/Documentation/sphinx/tmplcvt b/Documentation/sphinx/tmplcvt
new file mode 100755
index 000000000000..909a73065e0a
--- /dev/null
+++ b/Documentation/sphinx/tmplcvt
@@ -0,0 +1,19 @@ 
+#!/bin/bash
+#
+# Convert a template file into something like RST
+#
+# fix <function>
+# feed to pandoc
+# fix \_
+# title line?
+#
+
+in=$1
+rst=$2
+tmp=$rst.tmp
+
+cp $in $tmp
+sed --in-place -f convert_template.sed $tmp
+pandoc -s -S -f docbook -t rst -o $rst $tmp
+sed --in-place -f post_convert.sed $rst
+rm $tmp