From 1769baa06c2b79c0423119096e1be784f6b7a80a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9gis=20D=C3=A9camps?= Date: Sat, 13 Oct 2018 02:41:49 +0200 Subject: [PATCH] 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 | 2 +- WORKSPACE | 44 ++++++++++++++-- docs/BUILD | 91 +++++++++++++++++++++++++++++++++ docs/manual.tex | 83 ++++++++++++++++++++++++++++++ docs/manual_end.tex | 2 + docs/manual_start.tex | 10 ++++ docs/md/head.md | 3 +- scripts/bazel.sh | 1 - third_party/de/jflex/.gitignore | 0 9 files changed, 228 insertions(+), 8 deletions(-) create mode 100644 docs/BUILD create mode 100644 docs/manual.tex create mode 100644 docs/manual_end.tex create mode 100644 docs/manual_start.tex create mode 100644 third_party/de/jflex/.gitignore diff --git a/.travis.yml b/.travis.yml index df6bf6980..b18cbb064 100644 --- a/.travis.yml +++ b/.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 diff --git a/WORKSPACE b/WORKSPACE index 6ad0a1ee7..b17bc9e3e 100644 --- a/WORKSPACE +++ b/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/", ) + diff --git a/docs/BUILD b/docs/BUILD new file mode 100644 index 000000000..fd8a1ae95 --- /dev/null +++ b/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, +) diff --git a/docs/manual.tex b/docs/manual.tex new file mode 100644 index 000000000..f22380b3e --- /dev/null +++ b/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} diff --git a/docs/manual_end.tex b/docs/manual_end.tex new file mode 100644 index 000000000..1aad1859f --- /dev/null +++ b/docs/manual_end.tex @@ -0,0 +1,2 @@ + +\end{document} \ No newline at end of file diff --git a/docs/manual_start.tex b/docs/manual_start.tex new file mode 100644 index 000000000..455843755 --- /dev/null +++ b/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} diff --git a/docs/md/head.md b/docs/md/head.md index 1fbc4cb34..87094a07d 100644 --- a/docs/md/head.md +++ b/docs/md/head.md @@ -3,8 +3,9 @@ title: JFlex User's Manual bibliography: manual.bib --- +TODO: Restore image +
-![](fig/jflex-black.png) The Fast Lexical Analyser Generator diff --git a/scripts/bazel.sh b/scripts/bazel.sh index 01cc7937e..eeade1798 100755 --- a/scripts/bazel.sh +++ b/scripts/bazel.sh @@ -16,7 +16,6 @@ fi logi "Start Bazel" logi "===========" -cd "$BASEDIR"/jflex/examples $BAZEL info logi "Build everything" diff --git a/third_party/de/jflex/.gitignore b/third_party/de/jflex/.gitignore new file mode 100644 index 000000000..e69de29bb