From 8c8972b7498eb8a864b34df3de6558fb4064ae0d Mon Sep 17 00:00:00 2001
From: Lars-Dominik Braun <lars@6xq.net>
Date: Sun, 1 Apr 2018 20:12:45 +0200
Subject: Support Pandoc 2
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Apparently the new major release broke its public API, but – thankfully
– added support for RST’s include directive.
---
 src/Doc.lhs | 78 +++++++++++++++++++++++++++----------------------------------
 1 file changed, 34 insertions(+), 44 deletions(-)

(limited to 'src/Doc.lhs')

diff --git a/src/Doc.lhs b/src/Doc.lhs
index 2f787d8..a0d5121 100644
--- a/src/Doc.lhs
+++ b/src/Doc.lhs
@@ -6,62 +6,32 @@ Building documentation
 > {-# LANGUAGE OverloadedStrings #-}
 > import Text.Pandoc
 > import Text.Pandoc.Error (handleError)
-> import Text.Highlighting.Kate.Styles (tango)
-> import Data.List (stripPrefix)
-> import System.FilePath (replaceFileName)
-> import qualified Data.Set as S
+> import Text.Pandoc.Extensions (extensionsFromList)
+> import Text.Pandoc.Highlighting (tango)
+> import qualified Data.Text.IO as TIO
+> import System.Directory (setCurrentDirectory)
 
-The HTML documentation is generated directly from the source code of
-Codec.Pesto by running ``cabal run pesto-doc``. That module serves as starting
-point and it includes the other modules in a sensible order. Pandoc_ renders
-the restructuredText_ to HTML. We use a slightly modified template.
+The documentation can be generated running ``cabal run pesto-doc``. It is
+exclusively based on the restructuredText inside this packages’ literal Haskell
+source code.
 
-.. _pandoc: http://www.pandoc.org/
 .. _restructuredText: http://docutils.sourceforge.net/rst.html
 
-> main = do
-> 	tpl <- readFile "template.html"
-> 	doc <- readWithInclude "src/Codec/Pesto.lhs"
-> 	writeFile "_build/index.html" $ rstToHtml tpl doc
-
-Since pandoc currently does not support restructured text’s include directive
-directly, emulate it by recursively replacing all lines starting with ``..
-include::`` with the referenced file’s contents.
-
-> readWithInclude f = do
-> 	c <- readFile f
-> 	let l = lines c
-> 	linc <- mapM (\line -> case stripPrefix ".. include:: " line of
->		Just incfile -> readWithInclude $ replaceFileName f incfile
->		Nothing -> return line) l
-> 	return $ unlines linc
-
-The resulting string is parsed as literate Haskell with restructuredText markup.
-
 > readDoc = readRST def {
-> 	  readerExtensions = S.fromList [
+> 	  readerExtensions = extensionsFromList [
 > 		  Ext_literate_haskell
 > 		, Ext_implicit_header_references
 > 		]
 > 	, readerStandalone = True }
 
-Module definitions and imports should not be visible in the final
-documentation. They are marked up with the class ``nodoc`` and removed from the
-doctree before transforming it into HTML.
+.. _Pandoc: http://www.pandoc.org/
 
-> dropNoDoc = topDown f
-> 	where
-> 		f (Div (_, classes, _) _) | "nodoc" `elem` classes = Null
-> 		f x = x
+Pandoc_ outputs a single HTML5 page with syntax highlighting and MathJax for
+formulas.
 
-> rstToHtml tpl = writeDoc tpl . dropNoDoc . handleError . readDoc
-
-> writeDoc tpl = writeHtmlString def {
-> 	  writerStandalone = True
-> 	, writerTemplate = tpl
-> 	, writerHtml5 = True
-> 	, writerHighlight = True
-> 	, writerHighlightStyle = tango
+> writeDoc tpl = writeHtml5String def {
+> 	  writerTemplate = Just tpl
+> 	, writerHighlightStyle = Just tango
 >	, writerNumberSections = True
 > 	, writerSectionDivs = True
 > 	, writerTabStop = 4
@@ -69,3 +39,23 @@ doctree before transforming it into HTML.
 > 	, writerVariables = [("css", "pesto.css"), ("lang", "en")]
 > 	}
 
+A slightly customized template is used.
+
+> main = do
+> 	tpl <- readFile "template.html"
+
+The module Codec.Pesto serves as starting point and it includes every other
+module in a sensible order. For the relative includes to work, we need to
+change our current working directory.
+
+>	setCurrentDirectory "src/Codec"
+> 	doc <- TIO.readFile "Pesto.lhs"
+> 	result <- runIO $ readDoc doc >>= writeDoc tpl
+>	setCurrentDirectory "../../"
+> 	html <- handleError result
+
+Output is written to the directory ``_build``, which contains the corresponding
+stylesheet.
+
+> 	TIO.writeFile "_build/index.html" html
+
-- 
cgit v1.2.3