1.1 --- a/README.txt Tue Apr 16 23:36:14 2019 +0200
1.2 +++ b/README.txt Tue Apr 16 23:36:44 2019 +0200
1.3 @@ -12,8 +12,9 @@
1.4 format to other formats. For example, the supplied documentation can be
1.5 converted as follows:
1.6
1.7 -./moinconvert --all --input-dir docs/wiki --format html \
1.8 - --output-dir docs/html --macros --document-index index.html
1.9 +./moinconvert --input-dir docs/wiki --output-dir docs/html \
1.10 + --document-index index.html \
1.11 + --macros --all
1.12
1.13 This converts all documents in the indicated input directory to HTML format,
1.14 storing the converted documents in the indicated output directory, evaluating
1.15 @@ -32,11 +33,20 @@
1.16 See the bundled documentation for more details of the software and how it can
1.17 be used:
1.18
1.19 - * docs/wiki/FrontPage (and accompanying files) are the documentation files in
1.20 + * docs/wiki/MoinLight (and accompanying files) are the documentation files in
1.21 Moin format
1.22
1.23 - * docs/html/index.html is the front page of the documentation converted to HTML
1.24 - format
1.25 + * docs/html/index.html is the front page of the documentation converted to
1.26 + HTML format
1.27 +
1.28 +A more convenient way of generating the documentation is to use the following
1.29 +command:
1.30 +
1.31 +docs/tools/make_docs.sh
1.32 +
1.33 +For Web server deployment, add the --web option for cleaner links:
1.34 +
1.35 +docs/tools/make_docs.sh --web
1.36
1.37 Test Suite
1.38 ==========
2.1 --- a/docs/wiki/Input Tue Apr 16 23:36:14 2019 +0200
2.2 +++ b/docs/wiki/Input Tue Apr 16 23:36:44 2019 +0200
2.3 @@ -1,22 +1,26 @@
2.4 = Input =
2.5
2.6 -Input contexts determine how content provided for processing should be interpreted.
2.7 -Typically, wiki content will either be provided as a single file containing a
2.8 -single wiki page or as collections of such files arranged within a directory
2.9 -hierarchy.
2.10 +Input contexts determine how content provided for processing should be
2.11 +interpreted. Typically, wiki content will either be provided as a single file
2.12 +containing a single wiki page or as collections of such files arranged within a
2.13 +directory hierarchy.
2.14
2.15 -The following input contexts are supported:
2.16 +The supported input contexts are described below.
2.17 +
2.18 +== Directory ==
2.19 +
2.20 +A directory containing wiki page files.
2.21
2.22 -{{{#!table
2.23 -'''Name''' || '''Format''' || '''Details'''
2.24 -==
2.25 -directory
2.26 -|| A directory containing wiki page files
2.27 -|| Each file contains a different wiki page with its filename indicating the
2.28 -.. page name, and with any configured `input_separator` being used in
2.29 -.. filenames to construct hierarchical page relationships
2.30 -==
2.31 -standalone
2.32 -|| A standalone wiki page file
2.33 -|| A single file containing a single wiki page
2.34 -}}}
2.35 +[[Metadata#input_context|input_context]]: `directory`
2.36 +
2.37 +Each file contains a different wiki page with its filename indicating the page
2.38 +name, and with any configured `input_separator` being used in filenames to
2.39 +construct hierarchical page relationships.
2.40 +
2.41 +== Standalone ==
2.42 +
2.43 +A standalone wiki page file.
2.44 +
2.45 +[[Metadata#input_context|input_context]]: `standalone`
2.46 +
2.47 +A single file containing a single wiki page.
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/docs/wiki/Macros Tue Apr 16 23:36:44 2019 +0200
3.3 @@ -0,0 +1,15 @@
3.4 += Macros =
3.5 +
3.6 +As [[MoinMoin:HelpOnMacros|in MoinMoin]], macros are instructions that are
3.7 +replaced or expanded to produce content within documents. A number of macros
3.8 +are provided in MoinLight, some of which are provided for compatibility with
3.9 +Moin, including the following:
3.10 +
3.11 +|| '''Name''' || '''Purpose''' ||
3.12 +|| `Anchor` || Insert a link anchor ||
3.13 +|| `AttachList` || Show a list of page attachments ||
3.14 +|| `BR` || Insert a line break ||
3.15 +|| `MailTo` || Encode a `mailto:` link ||
3.16 +|| `PageList` || Show a list of pages ||
3.17 +|| `TableOfContents` || Show a table of contents ||
3.18 +|| `Verbatim` || Insert text without formatting ||
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/docs/wiki/Metadata Tue Apr 16 23:36:44 2019 +0200
4.3 @@ -0,0 +1,111 @@
4.4 += Metadata =
4.5 +
4.6 +The metadata abstraction is used in MoinLight to control the conversion of
4.7 +wiki content from its [[Input|input]] form to its eventual [[Output|output]]
4.8 +form.
4.9 +
4.10 +The settings or properties retained by the conversion metadata are described
4.11 +below.
4.12 +
4.13 +<<TableOfContents(2)>>
4.14 +
4.15 +== attachments ==
4.16 +
4.17 + Default:: `attachments`
4.18 +
4.19 +The name used for attachment directories.
4.20 +
4.21 +== document_index ==
4.22 +
4.23 + Default:: (none)
4.24 +
4.25 +The filename to be incorporated into page links so that such links reference a
4.26 +particular file instead of the page directory containing the file. This is
4.27 +useful when generating HTML content to be browsed as local files.
4.28 +
4.29 +== input_context ==
4.30 +
4.31 + Default:: `standalone`
4.32 + Alternative:: `directory`
4.33 +
4.34 +The form of the [[Input|input]] to be processed.
4.35 +
4.36 +== input_encoding ==
4.37 +
4.38 + Default:: `utf-8`
4.39 +
4.40 +The character encoding used in the input documents.
4.41 +
4.42 +== input_filename ==
4.43 +
4.44 + Default:: (none)
4.45 +
4.46 +The location of the input document or directory of documents.
4.47 +
4.48 +== input_format ==
4.49 +
4.50 + Default:: `moin`
4.51 +
4.52 +The default format of input documents.
4.53 +
4.54 +== input_separator ==
4.55 +
4.56 + Default:: (none)
4.57 +
4.58 +The separator used to structure hierarchical pagenames.
4.59 +
4.60 +== link_format ==
4.61 +
4.62 + Default:: (depends on the [[#output_format| output format]])
4.63 +
4.64 +The format of encoded links in converted documents. Typically, this will
4.65 +conform to the general output format of the documents.
4.66 +
4.67 +== mapping ==
4.68 +
4.69 + Default:: (none)
4.70 +
4.71 +A mapping of identifiers to URLs, used to generate interwiki links.
4.72 +
4.73 +== output_context ==
4.74 +
4.75 + Default:: `standalone`
4.76 + Alternative:: `directory`
4.77 +
4.78 +The form of the [[Output|output]] to be processed.
4.79 +
4.80 +== output_encoding ==
4.81 +
4.82 + Default:: `utf-8`
4.83 +
4.84 +The character encoding used in the output documents.
4.85 +
4.86 +== output_format ==
4.87 +
4.88 + Default:: `moin`
4.89 +
4.90 +The default format of output documents.
4.91 +
4.92 +== output_filename ==
4.93 +
4.94 + Default:: (none)
4.95 +
4.96 +The location of the output document or directory of documents.
4.97 +
4.98 +== root_pagename ==
4.99 +
4.100 + Default:: `FrontPage`
4.101 +
4.102 +The pagename of the root document in a collection of documents.
4.103 +
4.104 +== theme_name ==
4.105 +
4.106 + Default:: (none)
4.107 + Alternatives:: (see below)
4.108 +
4.109 +Required for applying themes to output. The names combine a theme name with an
4.110 +output format. For example:
4.111 +
4.112 +|| '''Alternative''' || '''Theme''' || '''Format''' ||
4.113 +|| `default.html` || `default` || `html` ||
4.114 +|| `mercurial.html` || `mercurial` || `html` ||
5.1 --- a/docs/wiki/MoinSyntax Tue Apr 16 23:36:14 2019 +0200
5.2 +++ b/docs/wiki/MoinSyntax Tue Apr 16 23:36:44 2019 +0200
5.3 @@ -47,6 +47,26 @@
5.4
5.5 The {{{<<BR>>}}} macro has the same function.
5.6
5.7 +== Links ==
5.8 +
5.9 +Link syntax remains largely compatible with Moin, but it is possible to break
5.10 +links across lines. For example:
5.11 +
5.12 +[[MoinSyntax|a description of a link to the Moin format syntax
5.13 +wrapped across multiple lines]]
5.14 +
5.15 +=== Syntax ===
5.16 +
5.17 +{{{
5.18 +[[MoinSyntax|a description of a link to the Moin format syntax
5.19 +wrapped across multiple lines]]
5.20 +}}}
5.21 +
5.22 +=== Related ===
5.23 +
5.24 +The [[MoinMoin:HelpOnLinking|Moin link syntax]] applies, including the
5.25 +transclusion syntax.
5.26 +
5.27 == Table Regions ==
5.28
5.29 Provides a more readable and convenient way of describing tables. For example:
6.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
6.2 +++ b/docs/wiki/Output Tue Apr 16 23:36:44 2019 +0200
6.3 @@ -0,0 +1,32 @@
6.4 += Output =
6.5 +
6.6 +Output contexts determine the form of converted wiki content. As with [[Input|
6.7 +input contexts]], typical forms will include a single file representing a wiki
6.8 +page or collections of files arranged within a directory hierarchy.
6.9 +
6.10 +The supported output contexts are described below.
6.11 +
6.12 +== Directory ==
6.13 +
6.14 +A directory containing wiki page resources in a hierarchy.
6.15 +
6.16 +[[Metadata#output_context|output_context]]: `directory`
6.17 +
6.18 +Each converted wiki page will reside at a path within the hierarchy
6.19 +corresponding to the page name, with top-level pages residing directly within
6.20 +the top-level output directory, and with subpages residing within the
6.21 +directories of their parents.
6.22 +
6.23 +Page content is stored in index files within each page
6.24 +directory, typically `index.html` (defined by the [[Metadata#index_name|
6.25 +index_name]] metadata property), with the designated [[Metadata#root|root]]
6.26 +page content appearing in the index file directly inside the top-level output
6.27 +directory.
6.28 +
6.29 +== Standalone ==
6.30 +
6.31 +A standalone wiki page file.
6.32 +
6.33 +[[Metadata#output_context|output_context]]: `standalone`
6.34 +
6.35 +A single file containing a single wiki page.
7.1 --- a/docs/wiki/Parsers Tue Apr 16 23:36:14 2019 +0200
7.2 +++ b/docs/wiki/Parsers Tue Apr 16 23:36:44 2019 +0200
7.3 @@ -5,17 +5,16 @@
7.4 {{{#!table
7.5 '''Name''' || '''Format''' || '''Details'''
7.6 ==
7.7 -graphviz
7.8 +`graphviz`
7.9 || [[http://graphviz.org/|Graphviz]] DOT language
7.10 || A complete graph description with optional processing directives
7.11 ==
7.12 -moin
7.13 +`moin`
7.14 || [[https://moinmo.in/|Moin]] markup
7.15 -|| Plain text with additional
7.16 -.. [[https://moinmo.in/HelpOnMoinWikiSyntax|syntax]] for formatting
7.17 +|| Plain text with additional [[MoinSyntax|syntax]] for formatting
7.18 ==
7.19 -table
7.20 +`table`
7.21 || Multiline table
7.22 || Moin markup with multiline table
7.23 -.. [[https://moinmo.in/ParserMarket/ImprovedTableParser|syntax enhancements]]
7.24 +.. [[MoinSyntax#Table Regions|syntax enhancements]]
7.25 }}}
8.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
8.2 +++ b/docs/wiki/Serialisers Tue Apr 16 23:36:44 2019 +0200
8.3 @@ -0,0 +1,21 @@
8.4 += Serialisers =
8.5 +
8.6 +Serialisers convert page content, producing output in a particular format.
8.7 +The following serialisers are currently supported:
8.8 +
8.9 +{{{#!table
8.10 +'''Name''' || '''Format''' || '''Details'''
8.11 +==
8.12 +`html`
8.13 +|| HTML markup format
8.14 +|| Without a [[Themes|theme]] applied to the output, only a document fragment
8.15 +.. is produced; otherwise, a complete document should be produced
8.16 +==
8.17 +`moin`
8.18 +|| [[MoinSyntax|Moin]] markup format
8.19 +|| The output should correspond to the input provided to the
8.20 +.. [[Parsers|parser]]
8.21 +}}}
8.22 +
8.23 +Within each serialiser's package, parser-specific modules handle the document
8.24 +nodes created by each different [[Parsers|parser]].
9.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
9.2 +++ b/docs/wiki/Themes Tue Apr 16 23:36:44 2019 +0200
9.3 @@ -0,0 +1,16 @@
9.4 += Themes =
9.5 +
9.6 +For certain [[Output|output]] formats, themes can be applied to the converted
9.7 +documents to produce content that can be usefully published. Typically, this
9.8 +applies only to HTML format documents.
9.9 +
9.10 +Currently, the following themes are defined:
9.11 +
9.12 +{{{#!table
9.13 +'''Name''' || '''Description'''
9.14 +==
9.15 +`default` || A simple HTML document theme with minimal decoration
9.16 +==
9.17 +`mercurial` || A relatively clean theme resembling that of the Mercurial Web
9.18 + .. site
9.19 +}}}
10.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
10.2 +++ b/docs/wiki/moinconvert Tue Apr 16 23:36:44 2019 +0200
10.3 @@ -0,0 +1,11 @@
10.4 += moinconvert =
10.5 +
10.6 +The `moinconvert` program is the principal means of converting content using
10.7 +MoinLight. Its help message can be obtained as follows:
10.8 +
10.9 +{{{
10.10 +moinconvert --help
10.11 +}}}
10.12 +
10.13 +The program employs command options to configure the conversion [[Metadata|
10.14 +metadata]], then converts the indicated content to the desired form.