1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/wiki/FrontPage Tue Apr 09 16:30:39 2019 +0200
1.3 @@ -0,0 +1,115 @@
1.4 += MoinLight =
1.5 +
1.6 +MoinLight is a distribution of programs and libraries for working with content
1.7 +encoded in the [[https://moinmo.in/|MoinMoin]] wiki markup format. This markup
1.8 +format is generally concise and supports many kinds of HTML document features
1.9 +using intelligible plain text representations.
1.10 +
1.11 +########## The graph below shows the architecture of the system...
1.12 +
1.13 +{{{#!graphviz
1.14 +#format svg
1.15 +#transform notugly
1.16 +digraph architecture {
1.17 + node [shape=box,fontsize="13.0",fontname="Helvetica"];
1.18 + rankdir=LR;
1.19 +
1.20 + subgraph {
1.21 + rank=same;
1.22 + input [label="Input context",URL="Input"];
1.23 + markup [label="Moin content",shape=folder,style=filled,fillcolor=cyan];
1.24 + }
1.25 +
1.26 + parser [label="Parser",URL="Parsers"];
1.27 +
1.28 + subgraph {
1.29 + rank=same;
1.30 + tree [label="Document tree",shape=folder,style=filled,fillcolor=cyan];
1.31 + evaluation [label="Macro evaluation",shape=ellipse];
1.32 + }
1.33 +
1.34 + serialiser [label="Serialiser",URL="Serialisers"];
1.35 +
1.36 + theme [label="Theme",URL="Themes"];
1.37 +
1.38 + subgraph {
1.39 + rank=same;
1.40 + output [label="Output context",URL="Output"];
1.41 + pages [label="Web content",shape=folder,style=filled,fillcolor=cyan];
1.42 + }
1.43 +
1.44 + markup -> input -> parser -> tree -> evaluation -> tree -> serialiser ->
1.45 + theme -> output -> pages;
1.46 +}
1.47 +}}}
1.48 +
1.49 +##########
1.50 +
1.51 +Although it is obviously possible to use the MoinMoin software (hereafter
1.52 +referred to as Moin) to work such such content, there are a few advantages in
1.53 +developing independent tools instead:
1.54 +
1.55 + * To eliminate any dependency on the Moin code, its bundled libraries, or on
1.56 + its external dependencies (of which there are many for Moin 2.0)
1.57 +
1.58 + * To focus on areas of functionality that are considered priorities, such as
1.59 + the publishing of content as static Web sites, which may not be adequately
1.60 + or optimally supported by Moin
1.61 +
1.62 + * To provide other implementations of parsers and serialisers for the markup
1.63 + format, thus establishing it as more genuinely interoperable markup
1.64 + standard
1.65 +
1.66 + * To be able to work with the content more easily and to develop tools for
1.67 + doing so
1.68 +
1.69 +== Getting Started ==
1.70 +
1.71 +To convert a collection of wiki pages in a directory (with `pages` containing
1.72 +the original pages and `htdocs` being the desired output directory), run the
1.73 +`moinconvert` program as follows:
1.74 +
1.75 +{{{
1.76 +moinconvert --input-dir pages --output-dir htdocs --all
1.77 +}}}
1.78 +
1.79 +To convert a single file from such a collection (such as `FrontPage`), run the
1.80 +program as follows:
1.81 +
1.82 +{{{
1.83 +moinconvert --input-dir pages FrontPage
1.84 +}}}
1.85 +
1.86 +This will produce the serialised page on standard output rather than writing
1.87 +it to a file.
1.88 +
1.89 +Other options are typically useful when running the program, such as `--theme`
1.90 +for styling and wrapping the output, `--macros` for expanding macros in
1.91 +documents, and `--format` for choosing alternative output formats.
1.92 +
1.93 +== Abstractions and Architecture ==
1.94 +
1.95 +MoinLight provides a number of abstractions for working with Moin wiki content:
1.96 +
1.97 + * [[/Parsers]] interpret various forms of markup-related content, producing a
1.98 + document tree representation that can be inspected and processed
1.99 +
1.100 + * [[/Serialisers]] convert the document tree representation into other
1.101 + content formats such as HTML or even back into Moin format
1.102 +
1.103 + * [[/Themes]] augment serialised content with additional details and
1.104 + resources
1.105 +
1.106 + * [[/Macros]] define locations in documents where content is to be inserted
1.107 + or expanded
1.108 +
1.109 + * [[/Input]] contexts permit the interpretation of existing content in
1.110 + certain ways so that a collection of text files can be treated like a wiki
1.111 +
1.112 + * [[/Output]] contexts permit the publishing of content in certain
1.113 + ways so that wiki content can be shared on the Web
1.114 +
1.115 +A major objective with MoinLight is to be able to produce static files that
1.116 +can be served using a typical Web server without any need for scripts,
1.117 +applications or other kinds of dynamic content. Other objectives are described
1.118 +in the [[/Roadmap]] document.