summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--Pesto.cabal2
-rw-r--r--_build/pesto.css4
-rw-r--r--src/Codec/Pesto.lhs20
-rw-r--r--src/Codec/Pesto/Graph.lhs2
-rw-r--r--src/Codec/Pesto/Lint.lhs4
-rw-r--r--src/Codec/Pesto/Parse.lhs2
-rw-r--r--src/Doc.lhs78
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
+