diff options
| -rw-r--r-- | Pesto.cabal | 2 | ||||
| -rw-r--r-- | _build/pesto.css | 4 | ||||
| -rw-r--r-- | src/Codec/Pesto.lhs | 20 | ||||
| -rw-r--r-- | src/Codec/Pesto/Graph.lhs | 2 | ||||
| -rw-r--r-- | src/Codec/Pesto/Lint.lhs | 4 | ||||
| -rw-r--r-- | src/Codec/Pesto/Parse.lhs | 2 | ||||
| -rw-r--r-- | src/Doc.lhs | 78 |
7 files changed, 58 insertions, 54 deletions
diff --git a/Pesto.cabal b/Pesto.cabal index 6c4d47a..ff13d20 100644 --- a/Pesto.cabal +++ b/Pesto.cabal @@ -41,6 +41,6 @@ executable pesto-doc main-is: Doc.lhs hs-source-dirs: src default-language: Haskell2010 - build-depends: base >=4.8 && <4.10, pandoc >=1.14, highlighting-kate, blaze-html, filepath, containers + build-depends: base >=4.8 && <4.10, pandoc >=2.1, text, directory ghc-options: -Werror -Wall -fno-warn-missing-signatures diff --git a/_build/pesto.css b/_build/pesto.css index 1994d67..b33890e 100644 --- a/_build/pesto.css +++ b/_build/pesto.css @@ -47,3 +47,7 @@ pre code { border-radius: 0.66em; } +.nodoc { + display: none; +} + diff --git a/src/Codec/Pesto.lhs b/src/Codec/Pesto.lhs index cf20105..5637059 100644 --- a/src/Codec/Pesto.lhs +++ b/src/Codec/Pesto.lhs @@ -18,13 +18,17 @@ About this document ------------------- This section contains various information about this document. The `second -section <motivation_>`_ motivates why inventing another file format is -necessary, followed by the goals_ of Pesto. After a short Pesto `primer -<introduction-by-example_>`_ intended for the casual user the language’s -`syntax <language-syntax_>`_ and `semantics <language-semantics_>`_ are -presented. The `linting section <linting_>`_ limits the language to useful -cooking recipes. Examples for user presentation of recipes and serialization -follow. +section`__ motivates why inventing another file format is necessary, followed +by the goals_ of Pesto. After a short Pesto primer__ intended for the casual +user the language’s syntax__ and semantics__ are presented. The `linting +section`__ limits the language to useful cooking recipes. Examples for user +presentation of recipes and serialization follow. + +__ motivation_ +__ introduction-by-example_ +__ language-syntax_ +__ language-semantics_ +__ linting_ Being a literate program this document is specification and reference implementation at the same time. The code is written in Haskell_ and uses the @@ -217,6 +221,8 @@ maintained in a separate database. Due to its minimal syntax Pesto is also not suitable for extensive guides on cooking or the usual chitchat found in cooking books. +.. _introduction-by-example: + Introduction by example ----------------------- diff --git a/src/Codec/Pesto/Graph.lhs b/src/Codec/Pesto/Graph.lhs index bcfd07b..316e593 100644 --- a/src/Codec/Pesto/Graph.lhs +++ b/src/Codec/Pesto/Graph.lhs @@ -1,3 +1,5 @@ +.. _language-semantics: + Language semantics ------------------ diff --git a/src/Codec/Pesto/Lint.lhs b/src/Codec/Pesto/Lint.lhs index 3d58ac8..81cb5d6 100644 --- a/src/Codec/Pesto/Lint.lhs +++ b/src/Codec/Pesto/Lint.lhs @@ -122,9 +122,9 @@ Both, title and description, are implicit. > "title" > , "description" -The recipe’s language, as 2 character code (`ISO 639-1`_). +The recipe’s language, as 2 character code (`ISO 639-1`__). -.. _ISO 639-1: http://www.loc.gov/standards/iso639-2/php/English_list.php +__ http://www.loc.gov/standards/iso639-2/php/English_list.php > , "language" diff --git a/src/Codec/Pesto/Parse.lhs b/src/Codec/Pesto/Parse.lhs index e72fc21..518b866 100644 --- a/src/Codec/Pesto/Parse.lhs +++ b/src/Codec/Pesto/Parse.lhs @@ -1,3 +1,5 @@ +.. _language-syntax: + Language syntax --------------- 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 + |