Written some user documentation with snm itself

Manual/Emit/Text.hs

@@ -89,3 +89,6 @@ instance Pretty Inline where
          IText str -> mock_shows str
          ISectionLink text dest -> mock_shows text
          IExternLink text dest -> mock_shows text . mock_shows "(see " . mock_shows dest . mock_shows ")"
+         IIndent -> mock_shows "   "
+         ILine -> nl
+         ILiteral t -> mock_shows t

Manual/Emit/XHTML.hs

@@ -103,6 +103,9 @@ instance HTML Inline where
          IText str -> stringToHtml $ str ++ " "
          ISectionLink text dest -> section_link text dest
          IExternLink text dest  -> extern_link text dest
+         IIndent -> concatHtml $ replicate 3 nbsp
+         ILine -> br
+         ILiteral t -> primHtml t
 
 -- | Internal link to elsewhere in the document
 section_link :: String -> URL -> Html

Manual/Reader.hs

@@ -51,8 +51,30 @@ import Control.Monad
 -- | Parse an inline element
 inline :: Parser Inline
 inline =
-   try text <|> try section_link <|> extern_link
+   try text <|> try section_link <|> try extern_link <|> try iindent <|> try iliteral <|> iline
    where
+   iliteral = do
+      char '{'
+      spaces
+      string "literal"
+      spaces
+      text <- many1 $ noneOf "\n\t\r}"
+      spaces
+      char '}'
+      return $ ILiteral text
+
+   iindent = simple "indent" IIndent
+
+   iline = simple "line" ILine
+
+   simple id val = do
+      char '{'
+      spaces
+      string id
+      spaces
+      char '}'
+      return val
+
    text :: Parser Inline
    text = fmap (IText . concat) $ many1 itext
    itext :: Parser String
@@ -205,7 +227,7 @@ instance Yamlable Header where
       copyright = read_key (herror "copyright") $ yookup "copyright" y
       license = read_key (herror "license") $ yookup "license" y
       license_file = read_key (herror "license_file") $ yookup "license_file" y
-      preamble = fromMaybe (herror "preamble") $ paras $ yookup "preamble" y
+      preamble = fromMaybe [] $ paras $ yookup "preamble" y
       herror nm = error $ pretty $ 
          error_line "Error while reading Header:" $
             error_section $ error_line ("Header did not have valid '" ++ nm ++ "' field.") $ error_section $ 

Manual/Structure.hs

@@ -66,6 +66,12 @@ data Inline =
      , -- | The link destination.
        ldest :: String
      }
+   | -- | Literal text
+     ILiteral String
+   | -- | A three space indent
+     IIndent
+   | -- | A new line
+     ILine
    deriving Show
 
 -- | A text paragraph

doc_src/header.yaml

@@ -2,3 +2,6 @@ title: The Simple Nice-Looking Manual Generator
 copyright: "John Morrice 2010"
 license: GNU Free Documentation License
 license_file: "DOC-COPYING"
+preamble:
+   - "The Simple Nice-Looking Manual Generator - aka snm - generates nice looking manuals from {external YAML http://www.yaml.org/} files."
+   - "Currently, it can produce XHTML and text manuals."

doc_src/how.yaml

@@ -0,0 +1,6 @@
+title: How to use snm
+unique: how
+number: 3
+text:
+   - "snm generates a manual from a number of yaml files, held in your documentation source directory.  In the snm source distribution, this directory is called 'doc_src'."
+   - "This source directory must contain a file called 'header.yaml'.  The next sub-section deals with what you put in header.yaml, and what it means."

doc_src/how/header.yaml

@@ -0,0 +1,26 @@
+# Note... note a header file for snm!
+title: header.yaml
+number: 1
+unique: header
+text:
+   - "The header file has 1 required field:"
+   - text: "{indent}title: The title of the manual"
+     class: example
+   - "The header file has 4 optional fields:"
+   - text:
+      "{indent}copyright: The name of the person or people holding copyright over the document, and the year it was copyright.{line}
+      {indent}license: The name of the license by which the document is being distributed{line}
+      {indent}license_file: The file containing the license{line}
+      {indent}preamble: Zero or more {section paragraphs paragraph}, which are not included in the manual's {section contents contents}."
+     class: example
+   - "For example, here is the header.yaml file for this document:"
+   - text:
+        "{indent}title: The Simple Nice-Looking Manual Generator{line}
+         {indent}copyright: 'John Morrice 2010'{line}
+         {indent}license: GNU Free Documentation License{line}
+         {indent}license_file: 'DOC-COPYING'{line}
+         {indent}preamble:{line}
+         {indent}{indent}- 'The Simple Nice-Looking Manual Generator - aka snm - generates nice looking manuals from {external YAML http://www.yaml.org/} files.'{line}
+         {indent}{indent}- 'Currently, it can produce XHTML and text manuals.'"
+     class: example
+   - "You can see how snm processes this by looking at the {literal <a href='#'>top</a>} of the document."

doc_src/style.css

@@ -0,0 +1,3 @@
+.banner {text-align: center;}
+.example {font-family: monospace; font-size: x-large;}
+body {font: arial; font-family: sans;}

doc_src/what.yaml

@@ -0,0 +1,7 @@
+title: What snm does and is
+unique: what
+number: 1
+text:
+   - "snm allows you to write clean, web-friendly reports without having to edit fickle html"
+   - "snm allows you to structure your document in a modular fashion."
+   - "snm is a generator of valid xhtml, as long as you don't kludge {section style.css style}"

doc_src/whatnot.yaml

@@ -0,0 +1,8 @@
+title: What snm does not do and is not
+number: 2
+unique: whatnot
+text:
+   - "snm is not a man-page generator."
+   - "snm is not a web-page creator"
+   - "snm is not a gui based tool"
+   - "snm is not an adult activity."

snm_help.html

@@ -0,0 +1,4 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html;charset=utf-8" /><title>The Simple Nice-Looking Manual Generator</title><style type="text/css">.banner {text-align: center;}
+.example {font-family: monospace; font-size: x-large;}
+body {font: arial; font-family: sans;}
+</style></head><body><h1 class="banner">The Simple Nice-Looking Manual Generator</h1><h2 class="banner">Copyright John Morrice 2010</h2><h2 class="banner">Distributed under terms of the GNU Free Documentation License.</h2><h2 class="banner">See the file <a href="DOC-COPYING">DOC-COPYING</a> for copying conditions.</h2><p class="">The Simple Nice-Looking Manual Generator - aka snm - generates nice looking manuals from  <a href="http://www.yaml.org/">YAML</a> files. </p><p class="">Currently, it can produce XHTML and text manuals. </p><p><a href="#what">1 What snm does and is</a><br /><a href="#whatnot">2 What snm does not do and is not</a><br /><a href="#how">3 How to use snm</a><br />&nbsp;&nbsp;&nbsp;<a href="#header">3.1 header.yaml</a><br /></p><h2><a name="what">1 What snm does and is</a></h2><p class="">snm allows you to write clean, web-friendly reports without having to edit fickle html </p><p class="">snm allows you to structure your document in a modular fashion. </p><p class="">snm is a generator of valid xhtml, as long as you don't kludge  <a href="#style">style.css</a></p><h2><a name="whatnot">2 What snm does not do and is not</a></h2><p class="">snm is not a man-page generator. </p><p class="">snm is not a web-page creator </p><p class="">snm is not a gui based tool </p><p class="">snm is not an adult activity. </p><h2><a name="how">3 How to use snm</a></h2><p class="">snm generates a manual from a number of yaml files, held in your documentation source directory.  In the snm source distribution, this directory is called 'doc_src'. </p><p class="">This source directory must contain a file called 'header.yaml'.  The next sub-section deals with what you put in header.yaml, and what it means. </p><h2><a name="header">3.1 header.yaml</a></h2><p class="">The header file has 1 required field: </p><p class="example">&nbsp;&nbsp;&nbsp;title: The title of the manual </p><p class="">The header file has 4 optional fields: </p><p class="example">&nbsp;&nbsp;&nbsp;copyright: The name of the person or people holding copyright over the document, and the year it was copyright. <br />  &nbsp;&nbsp;&nbsp;license: The name of the license by which the document is being distributed <br />  &nbsp;&nbsp;&nbsp;license_file: The file containing the license <br />  &nbsp;&nbsp;&nbsp;preamble: Zero or more  <a href="#paragraph">paragraphs</a>, which are not included in the manual's  <a href="#contents">contents</a>. </p><p class="">For example, here is the header.yaml file for this document: </p><p class="example">&nbsp;&nbsp;&nbsp;title: The Simple Nice-Looking Manual Generator <br />  &nbsp;&nbsp;&nbsp;copyright: 'John Morrice 2010' <br />  &nbsp;&nbsp;&nbsp;license: GNU Free Documentation License <br />  &nbsp;&nbsp;&nbsp;license_file: 'DOC-COPYING' <br />  &nbsp;&nbsp;&nbsp;preamble: <br />  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;- 'The Simple Nice-Looking Manual Generator - aka snm - generates nice looking manuals from  <a href="http://www.yaml.org/">YAML</a> files.' <br />  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;- 'Currently, it can produce XHTML and text manuals.' </p><p class="">You can see how snm processes this by looking at the  <a href='#'>top</a> of the document. </p></body></html>