Build Manual with Bazel (#439)

* Build the concatenated manual.mdx with Bazel
  - Do variable substirtution in manual.mdx

* Build manual.html with pandoc
  - Generate manual.html with Bazel rule
  - using my fork version of bazel_pandoc because the orginal one doesn't allow to sepcifiy the output.

* Try to add the pandoc options. All failed :-/

* Add pandoc target to generate manual.tex
  - Split xmanual.tex in two, because I can't make \include{} to work
  -  Remove image inclusion, because I can't resolve the path in the runtime dir.

* Add \tightlist macro in yemplate
  - Latest version of pandoc uses \tightlist defined in template https://github.com/jgm/pandoc-templates/blob/master/default.latex

* Build the PDF with Bazel
(first pass)
  - Comment out scrartcl
     The Bazel rule doesn't know about https://ctan.org/pkg/scrartcl
  - I can't make \include{} work with latex_document{} either.
  Instead, concatenate the files
- Many packages missing ; I rewrote a trivial document.

* Can't use pandoc template
  - this is not supported yet by the bazel rule.
  - concatenate manual_star.tex manual_content.tex manual_end.tex

* Remove useless cd jflex/examples in bazel.sh

.travis.yml

@@ -37,7 +37,7 @@ matrix:
   - name: "👴 Examples (mvn, ant, make) — JDK7"
     script: scripts/test-examples.sh
     jdk: openjdk7
-  - name: "😎 Examples (with Bazel)"
+  - name: "💚 Bazel (Examples and documentation)"
     language: generic
     script:
     - scripts/mvn-install-fastbuild.sh

WORKSPACE

@@ -1,9 +1,7 @@
-#
-# For your own project, please see https://jflex-de.github.io/bazel_rules/
-#
-# This workspace is mostly to test that the examples build with the SNAPSHOT version of JFLex.
-#
+# Workspace file for the Bazel build system
+# https://bazel.build/
 
+# JFlex itself is not built with Bazel, but some examples and the documentation are.
 load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
 
 git_repository(
@@ -16,6 +14,41 @@ load("@jflex_rules//jflex:deps.bzl", "jflex_deps")
 
 jflex_deps()
 
+# pandoc used to build the documentatoin
+
+# TODO(regisd) Take upstream when they have accepted my PR to allow specifying output
+# https://github.com/ProdriveTechnologies/bazel-pandoc/pull/1
+#http_archive(
+#    name = "bazel_pandoc",
+#    strip_prefix = "bazel-pandoc-0.1",
+#    url = "https://github.com/ProdriveTechnologies/bazel-pandoc/archive/v0.1.tar.gz",
+#)
+http_archive(
+    name = "bazel_pandoc",
+    strip_prefix = "bazel_pandoc-0.1.1",
+    url = "https://github.com/regisd/bazel_pandoc/archive/v0.1.1.tar.gz",
+    sha256 = "0dd9d0d44658d46a96c36caba25f7ce9f119a6883c3219f61b76c11cfdc83c8f",
+)
+
+
+load("@bazel_pandoc//:repositories.bzl", "pandoc_repositories")
+
+pandoc_repositories()
+
+# latex rule to build PDF from tex files
+
+http_archive(
+    name = "bazel_latex",
+    strip_prefix = "bazel-latex-0.9",
+    url = "https://github.com/ProdriveTechnologies/bazel-latex/archive/v0.9.tar.gz",
+)
+
+load("@bazel_latex//:repositories.bzl", "latex_repositories")
+
+latex_repositories()
+
+# Third-party depenencies
+
 maven_jar(
     name = "com_google_truth_truth",
     artifact = "com.google.truth:truth:0.36",
@@ -27,3 +60,4 @@ maven_jar(
     artifact = "com.google.guava:guava:jar:26.0-jre",
     repository = "http://jcenter.bintray.com/",
 )
+

docs/BUILD

@@ -0,0 +1,91 @@
+# Build the user manual
+
+load("@bazel_pandoc//:pandoc.bzl", "pandoc")
+load("@bazel_latex//:latex.bzl", "latex_document")
+
+VERSION = "1.7.1-SNAPSHOT"
+
+RELEASE_DATE = "21 September 2018"
+
+UNICODE_VER = "9.0"
+
+GENRULE_CONCATENATE = "cat $(SRCS) > $@"
+
+pandoc(
+    name = "html",
+    src = ":manual_mdx",
+    from_format = "markdown",
+    # TODO: Add "--css manual.css" when the rule accepts data files
+    #
+    # TODO: Add "+smart" when the toolchain supports it
+    #
+    # TODO: Add ["--filter", "pandoc-citeproc"] when #2 is fixed
+    # https://github.com/ProdriveTechnologies/bazel-pandoc/issues/2
+    options = [],
+    output = "manual.html",
+    to_format = "html",
+)
+
+pandoc(
+    name = "latex_content",
+    src = ":manual_mdx",
+    from_format = "markdown",
+    output = "content.tex",  # If changed, then change \include{} in manual.tex
+    to_format = "latex",
+)
+
+genrule(
+    name = "manual_full_tex",
+    srcs = [
+        "manual_start.tex",
+        ":latex_content",
+        "manual_end.tex",
+    ],
+    outs = ["manual_full.tex"],
+    cmd = GENRULE_CONCATENATE,
+)
+
+latex_document(
+    name = "manual",
+    srcs = [
+        #"manual.tex",
+        # "minimal.tex",
+        # "manual_full.tex",
+        "@bazel_latex//packages:graphicx",
+        "@bazel_latex//packages:hyperref",
+        "@bazel_latex//packages:microtype",
+    ],
+    main = "manual_full.tex",
+)
+
+# Replaces placeholders by their respective value.
+genrule(
+    name = "manual_mdx",
+    srcs = [":concatenated_manual"],
+    outs = ["manual.mdx"],
+    cmd = "sed -e 's/\$$VERSION/" + VERSION + "/g'" +
+          " -e 's/\$${project.version}/" + VERSION + "/g'" +
+          " -e 's/\$$RELEASE_DATE/" + RELEASE_DATE + "/g'" +
+          " -e 's/\$$UNICODE_VER/" + UNICODE_VER + "/g'" +
+          " $< > $@",
+)
+
+# Concatenates all pages in a single document.
+genrule(
+    name = "concatenated_manual",
+    srcs = [
+        "md/head.md",
+        "md/intro.md",
+        "md/installing.md",
+        "md/maven-plugin.md",
+        "md/ant-task.md",
+        "md/example.md",
+        "md/lex-specs.md",
+        "md/encodings.md",
+        "md/performance.md",
+        "md/porting-and-parsers.md",
+        "md/end.md",
+    ],
+    outs = ["concatenated_manual.md"],
+    cmd = GENRULE_CONCATENATE,
+)

docs/manual.tex

@@ -0,0 +1,83 @@
+% The Latex template for the manual, when doc built with bazel
+
+\documentclass[11pt]
+%{scrartcl}
+%\usepackage{a4wide}
+%\usepackage{verbatim}
+%\usepackage{graphicx} % "@bazel_latex//packages:graphicx"
+%\usepackage{upquote}
+%\usepackage{microtype} % "@bazel_latex//packages:microtype"
+
+%\usepackage{color}
+\definecolor{lcol}{rgb}{0,0,0.5}
+%\usepackage[unicode=true,bookmarks,
+%            colorlinks=true,linkcolor=lcol,citecolor=lcol,
+%            filecolor=lcol,urlcolor=lcol,
+%            pdfauthor={Gerwin Klein, Steve Rowe, Regis Decamps},
+%            pdftitle={JFlex User's Manual},
+%            pdfkeywords={Java, scanner, lexer, scanner generator},
+%            plainpages=false]{hyperref}
+
+
+% pandoc packages
+\usepackage{lmodern}
+\usepackage{fixltx2e} % provides \textsubscript
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+
+\newcommand{\textcite}[1]{\cite{#1}}
+\newcommand{\autocite}[1]{\cite{#1}}
+
+\renewcommand{\textquotesingle}{'}
+
+\let\orighyperref\hyperref
+\renewcommand{\hyperref}[2][]{\orighyperref[#1]{#2} (\autoref{#1})}
+
+\let\ttf\ttfamily
+\renewcommand{\ttfamily}{\small\ttf}
+
+\renewcommand{\sectionautorefname}{Section}
+\renewcommand{\subsectionautorefname}{Section}
+\renewcommand{\subsubsectionautorefname}{Section}
+\renewcommand{\Hfootnoteautorefname}{Footnote}
+
+\setlength{\parindent}{0pt}
+\setlength{\parskip}{1ex plus 0.5ex minus 0.2ex}
+
+% pandoc now uses \tightlist
+\providecommand{\tightlist}{%
+  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+
+\begin{document}
+
+% TODO Find real bath of image
+% can't find file fix.jflex-black.png
+%\centerline{\includegraphics[width=0.6\textwidth]{fig/jflex-black.png}}
+
+\begin{center}
+\sffamily
+{\Large The Fast Lexical Analyser Generator}\\
+\smallskip\smallskip
+Copyright \copyright\ 1998--2018
+by \href{http://www.doclsf.de}{Gerwin Klein},
+Steve Rowe,
+and \href{http://regis.decamps.info/}{R\'egis D\'ecamps}.
+
+\vspace*{15ex}
+{\Huge \sffamily \bfseries JFlex User's Manual}\\
+\bigskip
+Version 1.7.1-SNAPSHOT, {\today}
+\end{center}
+
+\newpage
+\tableofcontents
+\newpage
+
+\include{content}
+
+\newpage
+
+\bibliographystyle{plain}
+\bibliography{manual}
+
+\end{document}

docs/manual_end.tex

@@ -0,0 +1,2 @@
+
+\end{document}

docs/manual_start.tex

@@ -0,0 +1,10 @@
+\documentclass{article}
+\usepackage{hyperref}
+
+% pandoc now uses \tightlist
+\providecommand{\tightlist}{%
+  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+
+\newcommand{\textquotesingle}{'}
+
+\begin{document}

docs/md/head.md

@@ -3,8 +3,9 @@ title: JFlex User's Manual
 bibliography: manual.bib
 ---
 
+TODO: Restore image
+
 <center>
-![](fig/jflex-black.png)
 
 The Fast Lexical Analyser Generator
 

scripts/bazel.sh

@@ -16,7 +16,6 @@ fi
 
 logi "Start Bazel"
 logi "==========="
-cd "$BASEDIR"/jflex/examples
 $BAZEL info
 
 logi "Build everything"