# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1555450604 -7200
# Node ID 55a7e02c39aed2e7fcb85ba05b5c1d4c9e790dfe
# Parent  ccd1ac4d68999ac8c2df36ea85c3af6db472b807
Expanded the documentation, providing initial versions of most pages.

diff -r ccd1ac4d6899 -r 55a7e02c39ae README.txt
--- a/README.txt	Tue Apr 16 23:36:14 2019 +0200
+++ b/README.txt	Tue Apr 16 23:36:44 2019 +0200
@@ -12,8 +12,9 @@
 format to other formats. For example, the supplied documentation can be
 converted as follows:
 
-./moinconvert --all --input-dir docs/wiki --format html \
-              --output-dir docs/html --macros --document-index index.html
+./moinconvert --input-dir docs/wiki --output-dir docs/html \
+              --document-index index.html \
+              --macros --all
 
 This converts all documents in the indicated input directory to HTML format,
 storing the converted documents in the indicated output directory, evaluating
@@ -32,11 +33,20 @@
 See the bundled documentation for more details of the software and how it can
 be used:
 
- * docs/wiki/FrontPage (and accompanying files) are the documentation files in
+ * docs/wiki/MoinLight (and accompanying files) are the documentation files in
                        Moin format
 
- * docs/html/index.html is the front page of the documentation converted to HTML
-                        format
+ * docs/html/index.html is the front page of the documentation converted to
+                        HTML format
+
+A more convenient way of generating the documentation is to use the following
+command:
+
+docs/tools/make_docs.sh
+
+For Web server deployment, add the --web option for cleaner links:
+
+docs/tools/make_docs.sh --web
 
 Test Suite
 ==========
diff -r ccd1ac4d6899 -r 55a7e02c39ae docs/wiki/Input
--- a/docs/wiki/Input	Tue Apr 16 23:36:14 2019 +0200
+++ b/docs/wiki/Input	Tue Apr 16 23:36:44 2019 +0200
@@ -1,22 +1,26 @@
 = Input =
 
-Input contexts determine how content provided for processing should be interpreted.
-Typically, wiki content will either be provided as a single file containing a
-single wiki page or as collections of such files arranged within a directory
-hierarchy.
+Input contexts determine how content provided for processing should be
+interpreted. Typically, wiki content will either be provided as a single file
+containing a single wiki page or as collections of such files arranged within a
+directory hierarchy.
 
-The following input contexts are supported:
+The supported input contexts are described below.
+
+== Directory ==
+
+A directory containing wiki page files.
 
-{{{#!table
-'''Name''' || '''Format''' || '''Details'''
-==
-directory
-|| A directory containing wiki page files
-|| Each file contains a different wiki page with its filename indicating the
-.. page name, and with any configured `input_separator` being used in
-.. filenames to construct hierarchical page relationships
-==
-standalone
-|| A standalone wiki page file
-|| A single file containing a single wiki page
-}}}
+[[Metadata#input_context|input_context]]: `directory`
+
+Each file contains a different wiki page with its filename indicating the page
+name, and with any configured `input_separator` being used in filenames to
+construct hierarchical page relationships.
+
+== Standalone ==
+
+A standalone wiki page file.
+
+[[Metadata#input_context|input_context]]: `standalone`
+
+A single file containing a single wiki page.
diff -r ccd1ac4d6899 -r 55a7e02c39ae docs/wiki/Macros
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/wiki/Macros	Tue Apr 16 23:36:44 2019 +0200
@@ -0,0 +1,15 @@
+= Macros =
+
+As [[MoinMoin:HelpOnMacros|in MoinMoin]], macros are instructions that are
+replaced or expanded to produce content within documents. A number of macros
+are provided in MoinLight, some of which are provided for compatibility with
+Moin, including the following:
+
+|| '''Name'''        || '''Purpose'''                   ||
+|| `Anchor`          || Insert a link anchor            ||
+|| `AttachList`      || Show a list of page attachments ||
+|| `BR`              || Insert a line break             ||
+|| `MailTo`          || Encode a `mailto:` link         ||
+|| `PageList`        || Show a list of pages            ||
+|| `TableOfContents` || Show a table of contents        ||
+|| `Verbatim`        || Insert text without formatting  ||
diff -r ccd1ac4d6899 -r 55a7e02c39ae docs/wiki/Metadata
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/wiki/Metadata	Tue Apr 16 23:36:44 2019 +0200
@@ -0,0 +1,111 @@
+= Metadata =
+
+The metadata abstraction is used in MoinLight to control the conversion of
+wiki content from its [[Input|input]] form to its eventual [[Output|output]]
+form.
+
+The settings or properties retained by the conversion metadata are described
+below.
+
+<<TableOfContents(2)>>
+
+== attachments ==
+
+ Default:: `attachments`
+
+The name used for attachment directories.
+
+== document_index ==
+
+ Default:: (none)
+
+The filename to be incorporated into page links so that such links reference a
+particular file instead of the page directory containing the file. This is
+useful when generating HTML content to be browsed as local files.
+
+== input_context ==
+
+ Default:: `standalone`
+ Alternative:: `directory`
+
+The form of the [[Input|input]] to be processed.
+
+== input_encoding ==
+
+ Default:: `utf-8`
+
+The character encoding used in the input documents.
+
+== input_filename ==
+
+ Default:: (none)
+
+The location of the input document or directory of documents.
+
+== input_format ==
+
+ Default:: `moin`
+
+The default format of input documents.
+
+== input_separator ==
+
+ Default:: (none)
+
+The separator used to structure hierarchical pagenames.
+
+== link_format ==
+
+ Default:: (depends on the [[#output_format| output format]])
+
+The format of encoded links in converted documents. Typically, this will
+conform to the general output format of the documents.
+
+== mapping ==
+
+ Default:: (none)
+
+A mapping of identifiers to URLs, used to generate interwiki links.
+
+== output_context ==
+
+ Default:: `standalone`
+ Alternative:: `directory`
+
+The form of the [[Output|output]] to be processed.
+
+== output_encoding ==
+
+ Default:: `utf-8`
+
+The character encoding used in the output documents.
+
+== output_format ==
+
+ Default:: `moin`
+
+The default format of output documents.
+
+== output_filename ==
+
+ Default:: (none)
+
+The location of the output document or directory of documents.
+
+== root_pagename ==
+
+ Default:: `FrontPage`
+
+The pagename of the root document in a collection of documents.
+
+== theme_name ==
+
+ Default:: (none)
+ Alternatives:: (see below)
+
+Required for applying themes to output. The names combine a theme name with an
+output format. For example:
+
+|| '''Alternative''' || '''Theme''' || '''Format''' ||
+|| `default.html`    || `default`   || `html`       ||
+|| `mercurial.html`  || `mercurial` || `html`       ||
diff -r ccd1ac4d6899 -r 55a7e02c39ae docs/wiki/MoinSyntax
--- a/docs/wiki/MoinSyntax	Tue Apr 16 23:36:14 2019 +0200
+++ b/docs/wiki/MoinSyntax	Tue Apr 16 23:36:44 2019 +0200
@@ -47,6 +47,26 @@
 
 The {{{<<BR>>}}} macro has the same function.
 
+== Links ==
+
+Link syntax remains largely compatible with Moin, but it is possible to break
+links across lines. For example:
+
+[[MoinSyntax|a description of a link to the Moin format syntax
+wrapped across multiple lines]]
+
+=== Syntax ===
+
+{{{
+[[MoinSyntax|a description of a link to the Moin format syntax
+wrapped across multiple lines]]
+}}}
+
+=== Related ===
+
+The [[MoinMoin:HelpOnLinking|Moin link syntax]] applies, including the
+transclusion syntax.
+
 == Table Regions ==
 
 Provides a more readable and convenient way of describing tables. For example:
diff -r ccd1ac4d6899 -r 55a7e02c39ae docs/wiki/Output
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/wiki/Output	Tue Apr 16 23:36:44 2019 +0200
@@ -0,0 +1,32 @@
+= Output =
+
+Output contexts determine the form of converted wiki content. As with [[Input|
+input contexts]], typical forms will include a single file representing a wiki
+page or collections of files arranged within a directory hierarchy.
+
+The supported output contexts are described below.
+
+== Directory ==
+
+A directory containing wiki page resources in a hierarchy.
+
+[[Metadata#output_context|output_context]]: `directory`
+
+Each converted wiki page will reside at a path within the hierarchy
+corresponding to the page name, with top-level pages residing directly within
+the top-level output directory, and with subpages residing within the
+directories of their parents.
+
+Page content is stored in index files within each page
+directory, typically `index.html` (defined by the [[Metadata#index_name|
+index_name]] metadata property), with the designated [[Metadata#root|root]]
+page content appearing in the index file directly inside the top-level output
+directory.
+
+== Standalone ==
+
+A standalone wiki page file.
+
+[[Metadata#output_context|output_context]]: `standalone`
+
+A single file containing a single wiki page.
diff -r ccd1ac4d6899 -r 55a7e02c39ae docs/wiki/Parsers
--- a/docs/wiki/Parsers	Tue Apr 16 23:36:14 2019 +0200
+++ b/docs/wiki/Parsers	Tue Apr 16 23:36:44 2019 +0200
@@ -5,17 +5,16 @@
 {{{#!table
 '''Name''' || '''Format''' || '''Details'''
 ==
-graphviz
+`graphviz`
 || [[http://graphviz.org/|Graphviz]] DOT language
 || A complete graph description with optional processing directives
 ==
-moin
+`moin`
 || [[https://moinmo.in/|Moin]] markup
-|| Plain text with additional
-.. [[https://moinmo.in/HelpOnMoinWikiSyntax|syntax]] for formatting
+|| Plain text with additional [[MoinSyntax|syntax]] for formatting
 ==
-table
+`table`
 || Multiline table
 || Moin markup with multiline table
-.. [[https://moinmo.in/ParserMarket/ImprovedTableParser|syntax enhancements]]
+.. [[MoinSyntax#Table Regions|syntax enhancements]]
 }}}
diff -r ccd1ac4d6899 -r 55a7e02c39ae docs/wiki/Serialisers
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/wiki/Serialisers	Tue Apr 16 23:36:44 2019 +0200
@@ -0,0 +1,21 @@
+= Serialisers =
+
+Serialisers convert page content, producing output in a particular format.
+The following serialisers are currently supported:
+
+{{{#!table
+'''Name''' || '''Format''' || '''Details'''
+==
+`html`
+|| HTML markup format
+|| Without a [[Themes|theme]] applied to the output, only a document fragment
+.. is produced; otherwise, a complete document should be produced
+==
+`moin`
+|| [[MoinSyntax|Moin]] markup format
+|| The output should correspond to the input provided to the
+.. [[Parsers|parser]]
+}}}
+
+Within each serialiser's package, parser-specific modules handle the document
+nodes created by each different [[Parsers|parser]].
diff -r ccd1ac4d6899 -r 55a7e02c39ae docs/wiki/Themes
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/wiki/Themes	Tue Apr 16 23:36:44 2019 +0200
@@ -0,0 +1,16 @@
+= Themes =
+
+For certain [[Output|output]] formats, themes can be applied to the converted
+documents to produce content that can be usefully published. Typically, this
+applies only to HTML format documents.
+
+Currently, the following themes are defined:
+
+{{{#!table
+'''Name'''  || '''Description'''
+==
+`default`   || A simple HTML document theme with minimal decoration
+==
+`mercurial` || A relatively clean theme resembling that of the Mercurial Web
+            .. site
+}}}
diff -r ccd1ac4d6899 -r 55a7e02c39ae docs/wiki/moinconvert
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/wiki/moinconvert	Tue Apr 16 23:36:44 2019 +0200
@@ -0,0 +1,11 @@
+= moinconvert =
+
+The `moinconvert` program is the principal means of converting content using
+MoinLight. Its help message can be obtained as follows:
+
+{{{
+moinconvert --help
+}}}
+
+The program employs command options to configure the conversion [[Metadata|
+metadata]], then converts the indicated content to the desired form.