tutorial: update build as needed for newer pandoc

Unfortunately, pandoc 2 (which is available, for example, on Fedora 28)
broke some old features and changed formatting details a bit, so I needed
to modify the pandoc options, and also to change the HTML splitting code and
the stylesheet to support both old and new versions (I tested Pandoc 1.19
and Pandoc 2.0.6).

I moved the commands to convert MD to HTML and PDF, which have now grown
even longer, to separate scripts - doc/md2html and doc/md2pdf.
These scripts can also be used for the Cmake-based build, so we
don't need to repeat these commands.

Signed-off-by: Nadav Har'El <[email protected]>
Message-Id: <[email protected]>

configure.py

@@ -1064,10 +1064,10 @@ def have_hwloc():
             description = CSCOPE
         build cscope: cscope
         rule md2html
-            command = pandoc --self-contained --smart --toc -c doc/template.css -V documentclass=report --chapters --number-sections -f markdown_github+pandoc_title_block+implicit_header_references --highlight-style tango $in -o $out
+            command = doc/md2html "$in" "$out"
             description = PANDOC $out
         rule md2pdf
-            command = pandoc -f markdown_github+pandoc_title_block+implicit_header_references --highlight-style tango --template=doc/template.tex $in -o $out
+            command = doc/md2pdf "$in" "$out"
             description = PANDOC $out
         rule htmlsplit
             command = cd doc; ./htmlsplit.py

doc/htmlsplit.py

@@ -55,7 +55,7 @@ def flush(chapter, header, chunk):
     # numbers > 0 while reading a chapter
     chapter = None
     for line in f:
-        if line == '<div id="TOC">\n':
+        if line == '<div id="TOC">\n' or line =='<nav id="TOC">\n':
             header = chunk
             chapter = 0
             chunk = ""

doc/md2html

@@ -0,0 +1,29 @@
+#!/bin/sh
+# This file is open source software, licensed to you under the terms
+# of the Apache License, Version 2.0 (the "License").  See the NOTICE file
+# distributed with this work for additional information regarding copyright
+# ownership.  You may not use this file except in compliance with the License.
+#
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Copyright (C) 2018 ScyllaDB
+
+case `pandoc --version` in
+"pandoc 1."*)
+    SMART_OPT=--smart
+    SMART_EXT=
+    ;;
+*)
+    SMART_OPT=
+    SMART_EXT=+smart
+esac
+pandoc --self-contained $SMART_OPT --toc -c doc/template.css --number-sections -f markdown+pandoc_title_block+implicit_header_references$SMART_EXT --highlight-style tango "$1" -o "$2"

doc/md2pdf

@@ -0,0 +1,21 @@
+#!/bin/sh
+# This file is open source software, licensed to you under the terms
+# of the Apache License, Version 2.0 (the "License").  See the NOTICE file
+# distributed with this work for additional information regarding copyright
+# ownership.  You may not use this file except in compliance with the License.
+#
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Copyright (C) 2018 ScyllaDB
+
+pandoc -f markdown+pandoc_title_block+implicit_header_references --highlight-style tango --template=doc/template.tex "$1" -o "$2"
+

doc/template.css

@@ -16,9 +16,10 @@ body {
 	text-align: justify;
 }
 
-/* Pandoc puts the title, author and date, if any, in its own div id="header".
+/* In older versions, Pandoc puts the title, author and date, if any, in its
+ * own div id="header". In recent versions, it uses a "header" tag instead.
 */
-div#header {
+div#header, header {
 	border-top: 1px solid #aaa;
 	border-bottom: 1px solid #aaa;
 	background: #F0F0C0;	
@@ -46,8 +47,9 @@ div#header {
 	font-size: 16pt;
 }
 
-/* table of contents is in div id="TOC" */
-div#TOC {
+/* table of contents is in div id="TOC" in older versions, or a nav id="TOC"
+ * in newer versions */
+div#TOC, nav#TOC {
 	border-top: 1px solid #aaa;
 	border-bottom: 1px solid #aaa;
 	background: #F9F9F9;