snm 0.0.2 → 0.0.3
raw patch · 2 files changed
+3/−3 lines, 2 files
Files
- snm.cabal +2/−2
- snm_help.html +1/−1
snm.cabal view
@@ -1,5 +1,5 @@ Name: snm -Version: 0.0.2+Version: 0.0.3 License: GPL-3 License-File: COPYING Author: John Morrice <spoon@killersmurf.com>@@ -15,7 +15,7 @@ . snm is a generator of small, valid xhtml files. .- Read the snm manual online: http://www.killersmurf.com/static/snm_help.html+ Read the snm manual online: http:\/\/www.killersmurf.com\/static\/snm_help.html Build-type: Simple Homepage: http://github.com/elginer/snm
snm_help.html view
@@ -8,4 +8,4 @@ .example {font-family: monospace; font-size: x-large;} body {font: arial; font-family: sans;} .boring {font-weight: bold}-</style></head><body><h1 class="intro_banner">The Simple Nice-Looking Manual Generator</h1><h2 class="intro_banner">Copyright John Morrice 2010</h2><h2 class="intro_banner">Contact spoon@killersmurf.com</h2><p class="boring">This document is released under the terms of the GNU Free Documentation License. See the file <a href="DOC-COPYING">DOC-COPYING</a> for details</p><p class="boring">All snm source code is released under the terms of the GNU General Public Licence Version 3. See the file <a href="COPYING">COPYING</a> for details.</p><p class="">The Simple Nice-Looking Manual Generator - A.K.A 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 class="">snm is <a href="http://github.com/elginer/snm">hosted on github</a></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="#build">3. Building snm</a><br /> <a href="#easy">3.1. The Easy Way</a><br /> <a href="#hard">3.2. The Hard Way</a><br /> <a href="#install">3.3. Install snm to /usr/bin</a><br /><a href="#invoke">4. Invoking snm</a><br /><a href="#how">5. How to use snm</a><br /> <a href="#header">5.1. header.yaml</a><br /> <a href="#sections">5.2. Sections</a><br /> <a href="#subsections">5.2.1. Subsections</a><br /> <a href="#paragraphs">5.3. Paragraphs</a><br /> <a href="#banners">5.4. Banners</a><br /> <a href="#inline">5.5. Inline Elements</a><br /> <a href="#links">5.5.1. Hyperlinks</a><br /> <a href="#literal">5.5.2. Literal text</a><br /> <a href="#style">5.6. Style: CSS</a><br /><a href="#abuse">6. Further help, misuse and shortfalls</a><br /></p><h2 class="banner"><a name="what">1. What snm does and is</a></h2><p class="">snm allows you to write clean, web-friendly reports, user guides and manuals without having to edit fickle html.</p><p class="">snm allows you to structure your document in a modular fashion.</p><p class="">snm document sections are written in yaml and are easy to write and understand.</p><p class="">snm is a generator of small, valid xhtml files.</p><h2 class="banner"><a name="whatnot">2. What snm does not do and is not</a></h2><p class="">snm is not (currently) 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 class="banner"><a name="build">3. Building snm</a></h2><p class="">First, install <a href="http://yaml.kwiki.org/index.cgi?LibSyck">libsyck</a>.</p><p class="">Then choose to proceed to build snm in either <a href="#easy">The Easy Way</a> or <a href="#hard">The Hard Way</a>.</p><p class="">The hard way is presented to give more information to people who may need it. The Easy Way is recommended for absolutely everyone else!</p><h2 class="banner"><a name="easy">3.1. The Easy Way</a></h2><p class="">First install <a href="http://hackage.haskell.org/platform/">The Haskell Platform</a>.</p><p class="">Then just do:</p><p class="">cabal install snm</p><p class="">Now <a href="#install">install snm to /usr/bin</a></p><h2 class="banner"><a name="hard">3.2. The Hard Way</a></h2><p class="">To build snm the hard way, you must install:</p><p class=""><a href="http://haskell.org/ghc/">The Glasgow Haskell Compiler</a>. snm has been tested with GHC 6.10.4</p><p class="">And from <a href="http://hackage.haskell.org">Hackage</a>, the following libraries</p><p class="">base>=4, parsec>=3, filepath, directory, containers, HsSyck, safe, SpoonsUtilities, xhtml</p><p class="">Download the source distribution of snm from github</p><p class="">cd into its directory.</p><p class="">Run:</p><p class="example"> cabal install</p><p class="">Now <a href="#install">install snm to /usr/bin</a></p><h2 class="banner"><a name="install">3.3. Install snm to /usr/bin</a></h2><p class="">cabal install typically installs snm into your local cabal directory, usually ~/.cabal/bin/snm</p><p class="">So you'll probably need to:</p><p class="example"> sudo cp ~/.cabal/bin/snm /usr/bin</p><p class="">Now, try to <a href="#invoke">invoke</a> snm</p><h2 class="banner"><a name="invoke">4. Invoking snm</a></h2><p class="">Once it is <a href="#install">installed</a>, try invoking snm with</p><p class="example"> snm --help</p><p class="">If it was successfully installed, you will see some helpful information and a list of snm's command line options:</p><p class="example"> snm: The Simple Nice-Looking Manual Generator <br /> <br /> usage: <br /> snm documentation_source_directory options* <br /> <br /> Where options* stands for zero or more of the options below. <br /> <br /> Note: <br /> Only one output format is permitted per invocation. <br /> If -d or --dump is used, snm will not write a file unless -o or <br /> --output is used. <br /> There can be no whitespace between -o and its argument, nor can <br /> there be whitespace between --output= and its argument. <br /> If no arguments are given to -o, then the file written will have <br /> the same filename as the documentation source directory, with an <br /> appropriate extension added. <br /> snm will always add an appropriate extension to output files. <br /> By default, snm will produce snm, and act as if the user had <br /> specified -o without an argument. <br /> <br /> -d --dump Print output to stdout. <br /> -o[A file name] --output[=A file name] Write output to a file. <br /> Multiple outputs ignored, <br /> printing warning to <br /> stderr. <br /> -h --help Print usage information <br /> -t --text, --txt Text output. <br /> -x --xhtml, --html Output in xhtml format.</p><h2 class="banner"><a name="how">5. How to use snm</a></h2><p class="">snm generates a manual from a number of yaml files, held in a documentation source directory. In the snm source distribution, this directory is called 'snm_help'.</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 class="banner"><a name="header">5.1. header.yaml</a></h2><p class="">The header file has 1 required field:</p><p class="example"> title: A <a href="#banners">banner</a>, the title of the manual.</p><p class="">The header file has 2 optional fields:</p><p class="example"> banners: Zero or more <a href="#banners">banners</a>, used to announce important things at the start of a manual, for example, its author. <br /> 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 a slightly simplified version of the header.yaml file for this document:</p><p class="example"> title: "The Simple Nice-Looking Manual Generator" <br /> banners: <br /> - "Copyright John Morrice 2010" <br /> - "Contact spoon@killersmurf.com" <br /> preamble: <br /> - "This document is released under the terms of the GNU Free Documentation License. See the file <a href="DOC-COPYING">DOC-COPYING</a> for details" <br /> - "All snm source code is released under the terms of the GNU General Public Licence Version 3. See the file <a href="COPYING">COPYING</a> for details." <br /> - "The Simple Nice-Looking Manual Generator - A.K.A snm - generates nice looking manuals from <a href="http://www.yaml.org/">YAML</a> files." <br /> - "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><p class="">When emitting xhtml, the notices displayed at the top of the page are automatically given the css class 'banner'.</p><h2 class="banner"><a name="sections">5.2. Sections</a></h2><p class="">An snm manual, much like other structured documents, is arranged into heirarchical sections and <a href="#subsections">subsections</a>.</p><p class="">Top level sections are described by yaml files in the documentation source directory.</p><p class="">A section file in the top directory can be given any filename, other than <a href="#header">header.yaml</a> and <a href="#style">style.css</a> which are reserved. This restriction does not apply to subsections.</p><p class="">Each section has 4 required fields:</p><p class="example"> title: A <a href="#banners">banner</a>, the title of the section. This section's title is 'Sections' <br /> number: the number of the section. This section's number is 2. <br /> unique: A one-word, unique identifier for this section. This is used in constructing <a href="#links">hyperlinks</a>. <br /> text: Zero or more <a href="#paragraphs">paragraphs</a>.</p><p class="">For a concrete example, here is the beginning of the section file for this section.</p><p class="example"> title: Sections <br /> number: 2 <br /> unique: sections <br /> text: <br /> - 'An snm manual, much like other structured documents, is arranged into heirarchical sections...</p><h2 class="banner"><a name="subsections">5.2.1. Subsections</a></h2><p class="">A section is associated with subsections when the subsection files are located in a directory which has the same filename (excluding extensions) as its section file, in its same directory.</p><p class="">For example, here is a partial listing of this manual's source directory, snm_help:</p><p class="example"> snm_help: <br /> header.yaml <br /> how <br /> how.yaml <br /> ...more files</p><p class="">Note the file 'how.yaml'. This is the file describing <a href="#how">section 3, How to use snm,</a> of this document.</p><p class="">Note also the directory called how. This directory contains the subsections associated with how.yaml. Inside the how directory:</p><p class="example"> snm_help/how: <br /> section <br /> section.yaml <br /> ...more files</p><p class="">Note the 'section.yaml' file, which describes <a href="#sections">section 3.2, Sections</a> and its associated subsection directory 'section'.</p><p class="">Inside the section directory:</p><p class="example"> snm_help/how/section: <br /> subsection.yaml</p><p class="">how/section/subsection.yaml is the file describing this section.</p><p class="">A subsection's number is automatically computed by snm. Hence, according to the file describing this section, this section's number is 1. snm has discovered it is nested within section 3.2. It is an error to specify a subsection's whole number within a section file. Specify one number only!</p><h2 class="banner"><a name="paragraphs">5.3. Paragraphs</a></h2><p class="">When a sequence of paragraphs is called for in a manual yaml file, either a single text element, or a yaml <a href="http://yaml.kwiki.org/index.cgi?YamlInFiveMinutesMinuteOne">sequence</a> is expected.</p><p class="">Paragraphs are not just plain text: they may contain <a href="#inline">inline elements</a> like hyperlinks or literal text.</p><p class="">In a produced manual, a series of paragraphs are rendered with two line breaks between each of them. This corresponds to two newline characters in a text document, and being within a <p> tag in an html document. An example:</p><p class="example"> This is a valid, although boring, paragraph.</p><p class="">Paragraphs can be associated with a class, using a yaml <a href="http://yaml.kwiki.org/index.cgi?YamlInFiveMinutesMinuteTwo">map</a>. When rendering xhtml documents, this class is becomes the value of the class attribute for the paragraph produced. This is useful when working using a <a href="#style">style sheet</a>. An example:</p><p class="example"> class: curved_corner <br /> text: This paragraph is a bit more exciting, because it is being given curved corners by css!</p><p class="">Word wrapping can be turned on or off on a paragraph basis, by setting wrap to True or false in a map paragraph. When emitting xhtml, if wrap is off, then all spaces are replaced by &nbsp; and all new-lines replaced by <br/>. By default wrapping is on. Example:</p><p class="">This paragraph...</p><p class="example"> wrap: False <br /> text: "Hey ho, <br /> \n let's go!"</p><p class="">Is rendered as:</p><p class="example"> "Hey ho, <br /> \n let's go!"</p><p class="">But this paragraph...</p><p class="example"> wrap: True <br /> text: "Hey ho, <br /> \n let's go!"</p><p class="">And this paragraph...</p><p class="example"> "Hey ho, <br /> \n let's go!"</p><p class="">Are rendered as:</p><p class="example"> Hey ho, let's go!</p><h2 class="banner"><a name="banners">5.4. Banners</a></h2><p class="">Banners appear at the top of the manual, and at the beginning of sections.</p><p class="">Banners may contain inline elements in the same manner as a paragraph.</p><p class="">Banner defined in the <a href="#header">header</a> file are, by default, given the class 'intro_banner'. Banners defined in <a href="#sections">sections</a> are given the class 'banner'.</p><p class="">The default banner classes can be replaced by user defined classes, in the same manner that a class can be assigned to a paragraph.</p><h2 class="banner"><a name="inline">5.5. Inline Elements</a></h2><p class="">Inline elements within paragraphs and banners allow more expressive text. The idea of an inline snm element is roughly equivalent to an inline HTML element. Much as an xhtml anchor can only appear within an xhtml block element, an inline element can only appear within an snm paragraph or banner.</p><p class="">Inline elements appear within curly braces { }.</p><p class="">If you need to actually write an opening brace in your document, the opening brace may be escaped with a backslash \.</p><p class="">The following inline elements are available: section links, external links and literal text.</p><h2 class="banner"><a name="links">5.5.1. Hyperlinks</a></h2><p class="">snm supports two types of links.</p><p class="">Section links are hyperlinks to a <a href="#sections">section of the document</a>, using that section's unique name.</p><p class="">External links are a more traditional link to a URL.</p><p class="">As an inline element, links begin with an opening curly brace {.</p><p class="">Then either the word 'section', which indicates a section link, or the word 'external' which indicates an external link.</p><p class="">Then the link text. This may consist of a number of words separated by whitespace.</p><p class="">Then the destination. No explicit syntax separates the link text from the destination - the last word is taken to be the destination. Obviously, section links expect a section's unique name, whereas external links expect a URL.</p><p class="">As with all inline elements, a link is closed with a curly brace }.</p><p class="">Whitespace is optional throughout links.</p><p class="">Examples:</p><p class="">The link above, which is a section link to the unique identifier 'sections':</p><p class="example"> {section section of the document sections}</p><p class="">The external link in <a href="#paragraphs">section 3.3 Paragraphs</a>, to the 'YAML in Five Minutes' tutorial</p><p class="example"> {external sequence http://yaml.kwiki.org/index.cgi?YamlInFiveMinutesMinuteOne}</p><h2 class="banner"><a name="literal">5.5.2. Literal text</a></h2><p class="">Literal text can be specified through the literal inline element.</p><p class="">Literal text is not processed or transformed by snm: it is output directly into the output document.</p><p class="">This is risky because allows it you to write invalid xhtml, for instance; but it does allow you to write html that snm does not generate.</p><p class="">However, this approach suffers from many problems and is very much a working solution for current needs. Problems are discussed <a href="#abuse">below</a>.</p><p class="">Example:</p><p class="example"> {literal <table><td>Embed a html table</td></table>}</p><h2 class="banner"><a name="style">5.6. Style: CSS</a></h2><p class="">When generating xhtml, snm will look for a file called 'style.css' in the documentation source directory, and embed the contents of that file into the document's header as a CSS style sheet.</p><h2 class="banner"><a name="abuse">6. Further help, misuse and shortfalls</a></h2><p class="">If you use snm and need more help than is available in this manual then do not hesitate to contact the author at spoon@killersmurf.com.</p><p class="">Please note that snm suffers from a number of shortfalls:</p><p class="">Invalid xhtml can be generated through manipulation of the <a href="#style">style sheet</a>, <a href="#literal">literal text</a>, <a href="#links">link destinations</a>, and the <a href="#sections">unique names of sections</a>.</p><p class="">While I regret that this is possible, attempting xhtml kludges through these means ill-fitting means is misuse of snm and may result in generation shoddy manuals, a telling off and early bed-times all around. You have been warned!</p></body></html>+</style></head><body><h1 class="intro_banner">The Simple Nice-Looking Manual Generator</h1><h2 class="intro_banner">Copyright John Morrice 2010</h2><h2 class="intro_banner">Contact spoon@killersmurf.com</h2><p class="boring">This document is released under the terms of the GNU Free Documentation License. See the file <a href="DOC-COPYING">DOC-COPYING</a> for details</p><p class="boring">All snm source code is released under the terms of the GNU General Public Licence Version 3. See the file <a href="COPYING">COPYING</a> for details.</p><p class="">The Simple Nice-Looking Manual Generator - A.K.A 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 class="">snm is <a href="http://github.com/elginer/snm">hosted on github</a></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="#build">3. Building snm</a><br /> <a href="#easy">3.1. The Easy Way</a><br /> <a href="#hard">3.2. The Hard Way</a><br /> <a href="#install">3.3. Install snm to /usr/bin</a><br /><a href="#invoke">4. Invoking snm</a><br /><a href="#how">5. How to use snm</a><br /> <a href="#header">5.1. header.yaml</a><br /> <a href="#sections">5.2. Sections</a><br /> <a href="#subsections">5.2.1. Subsections</a><br /> <a href="#paragraphs">5.3. Paragraphs</a><br /> <a href="#banners">5.4. Banners</a><br /> <a href="#inline">5.5. Inline Elements</a><br /> <a href="#links">5.5.1. Hyperlinks</a><br /> <a href="#literal">5.5.2. Literal text</a><br /> <a href="#style">5.6. Style: CSS</a><br /><a href="#abuse">6. Further help, misuse and shortfalls</a><br /></p><h2 class="banner"><a name="what">1. What snm does and is</a></h2><p class="">snm allows you to write clean, web-friendly reports, user guides and manuals without having to edit fickle html.</p><p class="">snm allows you to structure your document in a modular fashion.</p><p class="">snm document sections are written in yaml and are easy to write and understand.</p><p class="">snm is a generator of small, valid xhtml files.</p><h2 class="banner"><a name="whatnot">2. What snm does not do and is not</a></h2><p class="">snm is not (currently) 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 class="banner"><a name="build">3. Building snm</a></h2><p class="">First, install <a href="http://yaml.kwiki.org/index.cgi?LibSyck">libsyck</a>.</p><p class="">Then choose to proceed to build snm in either <a href="#easy">The Easy Way</a> or <a href="#hard">The Hard Way</a>.</p><p class="">The hard way is presented to give more information to people who may need it. The Easy Way is recommended for absolutely everyone else!</p><h2 class="banner"><a name="easy">3.1. The Easy Way</a></h2><p class="">First install <a href="http://hackage.haskell.org/platform/">The Haskell Platform</a>.</p><p class="">Then just do:</p><p class="">cabal install snm</p><p class="">Now <a href="#install">install snm to /usr/bin</a></p><h2 class="banner"><a name="hard">3.2. The Hard Way</a></h2><p class="">To build snm the hard way, you must install:</p><p class=""><a href="http://haskell.org/ghc/">The Glasgow Haskell Compiler</a>. snm has been tested with GHC 6.10.4</p><p class="">And from <a href="http://hackage.haskell.org">Hackage</a>, the following libraries</p><p class="">base>=4, parsec>=3, filepath, directory, containers, HsSyck, safe, SpoonsUtilities, xhtml</p><p class="">Download the source distribution of snm from github</p><p class="">cd into its directory.</p><p class="">Run:</p><p class="example"> cabal install</p><p class="">Now <a href="#install">install snm to /usr/bin</a></p><h2 class="banner"><a name="install">3.3. Install snm to /usr/bin</a></h2><p class="">cabal install typically installs snm into your local cabal directory, usually ~/.cabal/bin/snm</p><p class="">So you'll probably need to:</p><p class="example"> sudo cp ~/.cabal/bin/snm /usr/bin</p><p class="">Now, try to <a href="#invoke">invoke</a> snm</p><h2 class="banner"><a name="invoke">4. Invoking snm</a></h2><p class="">Once it is <a href="#install">installed</a>, try invoking snm with</p><p class="example"> snm --help</p><p class="">If it was successfully installed, you will see some helpful information and a list of snm's command line options:</p><p class="example"> snm: The Simple Nice-Looking Manual Generator <br /> <br /> usage: <br /> snm documentation_source_directory options* <br /> <br /> Where options* stands for zero or more of the options below. <br /> <br /> Note: <br /> Only one output format is permitted per invocation. <br /> If -d or --dump is used, snm will not write a file unless -o or <br /> --output is used. <br /> There can be no whitespace between -o and its argument, nor can <br /> there be whitespace between --output= and its argument. <br /> If no arguments are given to -o, then the file written will have <br /> the same filename as the documentation source directory, with an <br /> appropriate extension added. <br /> snm will always add an appropriate extension to output files. <br /> By default, snm will produce xhtml, and act as if the user had <br /> specified -o without an argument. <br /> <br /> -d --dump Print output to stdout. <br /> -o[A file name] --output[=A file name] Write output to a file. <br /> Multiple outputs ignored, <br /> printing warning to <br /> stderr. <br /> -h --help Print usage information <br /> -t --text, --txt Text output. <br /> -x --xhtml, --html Output in xhtml format.</p><h2 class="banner"><a name="how">5. How to use snm</a></h2><p class="">snm generates a manual from a number of yaml files, held in a documentation source directory. In the snm source distribution, this directory is called 'snm_help'.</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 class="banner"><a name="header">5.1. header.yaml</a></h2><p class="">The header file has 1 required field:</p><p class="example"> title: A <a href="#banners">banner</a>, the title of the manual.</p><p class="">The header file has 2 optional fields:</p><p class="example"> banners: Zero or more <a href="#banners">banners</a>, used to announce important things at the start of a manual, for example, its author. <br /> 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 a slightly simplified version of the header.yaml file for this document:</p><p class="example"> title: "The Simple Nice-Looking Manual Generator" <br /> banners: <br /> - "Copyright John Morrice 2010" <br /> - "Contact spoon@killersmurf.com" <br /> preamble: <br /> - "This document is released under the terms of the GNU Free Documentation License. See the file <a href="DOC-COPYING">DOC-COPYING</a> for details" <br /> - "All snm source code is released under the terms of the GNU General Public Licence Version 3. See the file <a href="COPYING">COPYING</a> for details." <br /> - "The Simple Nice-Looking Manual Generator - A.K.A snm - generates nice looking manuals from <a href="http://www.yaml.org/">YAML</a> files." <br /> - "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><p class="">When emitting xhtml, the notices displayed at the top of the page are automatically given the css class 'banner'.</p><h2 class="banner"><a name="sections">5.2. Sections</a></h2><p class="">An snm manual, much like other structured documents, is arranged into heirarchical sections and <a href="#subsections">subsections</a>.</p><p class="">Top level sections are described by yaml files in the documentation source directory.</p><p class="">A section file in the top directory can be given any filename, other than <a href="#header">header.yaml</a> and <a href="#style">style.css</a> which are reserved. This restriction does not apply to subsections.</p><p class="">Each section has 4 required fields:</p><p class="example"> title: A <a href="#banners">banner</a>, the title of the section. This section's title is 'Sections' <br /> number: the number of the section. This section's number is 2. <br /> unique: A one-word, unique identifier for this section. This is used in constructing <a href="#links">hyperlinks</a>. <br /> text: Zero or more <a href="#paragraphs">paragraphs</a>.</p><p class="">For a concrete example, here is the beginning of the section file for this section.</p><p class="example"> title: Sections <br /> number: 2 <br /> unique: sections <br /> text: <br /> - 'An snm manual, much like other structured documents, is arranged into heirarchical sections...</p><h2 class="banner"><a name="subsections">5.2.1. Subsections</a></h2><p class="">A section is associated with subsections when the subsection files are located in a directory which has the same filename (excluding extensions) as its section file, in its same directory.</p><p class="">For example, here is a partial listing of this manual's source directory, snm_help:</p><p class="example"> snm_help: <br /> header.yaml <br /> how <br /> how.yaml <br /> ...more files</p><p class="">Note the file 'how.yaml'. This is the file describing <a href="#how">section 3, How to use snm,</a> of this document.</p><p class="">Note also the directory called how. This directory contains the subsections associated with how.yaml. Inside the how directory:</p><p class="example"> snm_help/how: <br /> section <br /> section.yaml <br /> ...more files</p><p class="">Note the 'section.yaml' file, which describes <a href="#sections">section 3.2, Sections</a> and its associated subsection directory 'section'.</p><p class="">Inside the section directory:</p><p class="example"> snm_help/how/section: <br /> subsection.yaml</p><p class="">how/section/subsection.yaml is the file describing this section.</p><p class="">A subsection's number is automatically computed by snm. Hence, according to the file describing this section, this section's number is 1. snm has discovered it is nested within section 3.2. It is an error to specify a subsection's whole number within a section file. Specify one number only!</p><h2 class="banner"><a name="paragraphs">5.3. Paragraphs</a></h2><p class="">When a sequence of paragraphs is called for in a manual yaml file, either a single text element, or a yaml <a href="http://yaml.kwiki.org/index.cgi?YamlInFiveMinutesMinuteOne">sequence</a> is expected.</p><p class="">Paragraphs are not just plain text: they may contain <a href="#inline">inline elements</a> like hyperlinks or literal text.</p><p class="">In a produced manual, a series of paragraphs are rendered with two line breaks between each of them. This corresponds to two newline characters in a text document, and being within a <p> tag in an html document. An example:</p><p class="example"> This is a valid, although boring, paragraph.</p><p class="">Paragraphs can be associated with a class, using a yaml <a href="http://yaml.kwiki.org/index.cgi?YamlInFiveMinutesMinuteTwo">map</a>. When rendering xhtml documents, this class is becomes the value of the class attribute for the paragraph produced. This is useful when working using a <a href="#style">style sheet</a>. An example:</p><p class="example"> class: curved_corner <br /> text: This paragraph is a bit more exciting, because it is being given curved corners by css!</p><p class="">Word wrapping can be turned on or off on a paragraph basis, by setting wrap to True or false in a map paragraph. When emitting xhtml, if wrap is off, then all spaces are replaced by &nbsp; and all new-lines replaced by <br/>. By default wrapping is on. Example:</p><p class="">This paragraph...</p><p class="example"> wrap: False <br /> text: "Hey ho, <br /> \n let's go!"</p><p class="">Is rendered as:</p><p class="example"> "Hey ho, <br /> let's go!"</p><p class="">But this paragraph...</p><p class="example"> wrap: True <br /> text: "Hey ho, <br /> \n let's go!"</p><p class="">And this paragraph...</p><p class="example"> "Hey ho, <br /> \n let's go!"</p><p class="">Are rendered as:</p><p class="example"> Hey ho, let's go!</p><h2 class="banner"><a name="banners">5.4. Banners</a></h2><p class="">Banners appear at the top of the manual, and at the beginning of sections.</p><p class="">Banners may contain inline elements in the same manner as a paragraph.</p><p class="">Banner defined in the <a href="#header">header</a> file are, by default, given the class 'intro_banner'. Banners defined in <a href="#sections">sections</a> are given the class 'banner'.</p><p class="">The default banner classes can be replaced by user defined classes, in the same manner that a class can be assigned to a paragraph.</p><h2 class="banner"><a name="inline">5.5. Inline Elements</a></h2><p class="">Inline elements within paragraphs and banners allow more expressive text. The idea of an inline snm element is roughly equivalent to an inline HTML element. Much as an xhtml anchor can only appear within an xhtml block element, an inline element can only appear within an snm paragraph or banner.</p><p class="">Inline elements appear within curly braces { }.</p><p class="">If you need to actually write an opening brace in your document, the opening brace may be escaped with a backslash \.</p><p class="">The following inline elements are available: section links, external links and literal text.</p><h2 class="banner"><a name="links">5.5.1. Hyperlinks</a></h2><p class="">snm supports two types of links.</p><p class="">Section links are hyperlinks to a <a href="#sections">section of the document</a>, using that section's unique name.</p><p class="">External links are a more traditional link to a URL.</p><p class="">As an inline element, links begin with an opening curly brace {.</p><p class="">Then either the word 'section', which indicates a section link, or the word 'external' which indicates an external link.</p><p class="">Then the link text. This may consist of a number of words separated by whitespace.</p><p class="">Then the destination. No explicit syntax separates the link text from the destination - the last word is taken to be the destination. Obviously, section links expect a section's unique name, whereas external links expect a URL.</p><p class="">As with all inline elements, a link is closed with a curly brace }.</p><p class="">Whitespace is optional throughout links.</p><p class="">Examples:</p><p class="">The link above, which is a section link to the unique identifier 'sections':</p><p class="example"> {section section of the document sections}</p><p class="">The external link in <a href="#paragraphs">section 3.3 Paragraphs</a>, to the 'YAML in Five Minutes' tutorial</p><p class="example"> {external sequence http://yaml.kwiki.org/index.cgi?YamlInFiveMinutesMinuteOne}</p><h2 class="banner"><a name="literal">5.5.2. Literal text</a></h2><p class="">Literal text can be specified through the literal inline element.</p><p class="">Literal text is not processed or transformed by snm: it is output directly into the output document.</p><p class="">This is risky because allows it you to write invalid xhtml, for instance; but it does allow you to write html that snm does not generate.</p><p class="">However, this approach suffers from many problems and is very much a working solution for current needs. Problems are discussed <a href="#abuse">below</a>.</p><p class="">Example:</p><p class="example"> {literal <table><td>Embed a html table</td></table>}</p><h2 class="banner"><a name="style">5.6. Style: CSS</a></h2><p class="">When generating xhtml, snm will look for a file called 'style.css' in the documentation source directory, and embed the contents of that file into the document's header as a CSS style sheet.</p><h2 class="banner"><a name="abuse">6. Further help, misuse and shortfalls</a></h2><p class="">If you use snm and need more help than is available in this manual then do not hesitate to contact the author at spoon@killersmurf.com.</p><p class="">Please note that snm suffers from a number of shortfalls:</p><p class="">Invalid xhtml can be generated through manipulation of the <a href="#style">style sheet</a>, <a href="#literal">literal text</a>, <a href="#links">link destinations</a>, and the <a href="#sections">unique names of sections</a>.</p><p class="">While I regret that this is possible, attempting xhtml kludges through these means ill-fitting means is misuse of snm and may result in generation shoddy manuals, a telling off and early bed-times all around. You have been warned!</p></body></html>