From ed218eeaec4d57723647a223acd2e39f068ebd53 Mon Sep 17 00:00:00 2001
From: Lars-Dominik Braun <lars@6xq.net>
Date: Sat, 11 Jul 2015 17:38:41 +0200
Subject: Improve documentation documentation

---
 src/Doc.lhs | 26 ++++++++++++++++----------
 1 file changed, 16 insertions(+), 10 deletions(-)

(limited to 'src')

diff --git a/src/Doc.lhs b/src/Doc.lhs
index 5cba5c1..0d3f1cd 100644
--- a/src/Doc.lhs
+++ b/src/Doc.lhs
@@ -11,16 +11,22 @@ Building documentation
 > import System.FilePath (replaceFileName)
 > import qualified Data.Set as S
 
-The documentation is created from the source module Codec.Pesto, which includes
-the other modules. We use a slightly modified template.
+The HTML documentation is generated directly from the source code of
+Codec.Pesto. 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.
+
+.. _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,
-emulate it.
+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
@@ -30,10 +36,7 @@ emulate it.
 >		Nothing -> return line) l
 > 	return $ unlines linc
 
-The pass the resulting string to pandoc that builds a doctree, remove unwanted
-content and build a HTML page.
-
-> rstToHtml tpl = writeDoc tpl . dropNoDoc . handleError . readDoc
+The resulting string is parsed as literate Haskell with restructuredText markup.
 
 > readDoc = readRST def {
 > 	  readerExtensions = S.fromList [
@@ -42,14 +45,17 @@ content and build a HTML page.
 > 		]
 > 	, readerStandalone = True }
 
-Drop blocks that should not be visible in the documentation, like module
-definitions and imports.
+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.
 
 > dropNoDoc = topDown f
 > 	where
 > 		f (Div (_, classes, _) _) | "nodoc" `elem` classes = Null
 > 		f x = x
 
+> rstToHtml tpl = writeDoc tpl . dropNoDoc . handleError . readDoc
+
 > writeDoc tpl = writeHtmlString def {
 > 	  writerStandalone = True
 > 	, writerTemplate = tpl
-- 
cgit v1.2.3