= MoinLight =

{{{#!table
[[/Downloads|Downloads]] || [[#GettingStarted|Getting Started]] ||
[[#Architecture|Architecture]] || [[/Roadmap|Roadmap]]
}}}

MoinLight is a distribution of programs and libraries for working with content
encoded in the [[https://moinmo.in/|MoinMoin]] wiki markup format. This markup
format is generally concise and supports many kinds of HTML document features
using intelligible plain text representations.

########## The graph below shows the architecture of the system...

{{{#!graphviz
#format svg
#transform notugly
digraph architecture {
  node [shape=box,fontsize="13.0",fontname="sans-serif"];
  rankdir=LR;

  subgraph {
    rank=same;
    input [label="Input context",URL="Input"];
    markup [label="Moin content",shape=folder,style=filled,fillcolor=cyan];
  }

  parser [label="Parser",URL="Parsers"];

  subgraph {
    rank=same;
    tree [label="Document tree",shape=folder,style=filled,fillcolor=cyan];
    evaluation [label="Macro evaluation",URL="Macros",shape=ellipse];
  }

  serialiser [label="Serialiser",URL="Serialisers"];

  theme [label="Theme",URL="Themes"];

  subgraph {
    rank=same;
    output [label="Output context",URL="Output"];
    pages [label="Web content",shape=folder,style=filled,fillcolor=cyan];
  }

  markup -> input -> parser -> tree -> evaluation -> tree -> serialiser ->
            theme -> output -> pages;
}
}}}

##########

Although it is obviously possible to use the MoinMoin software (hereafter
referred to as Moin) to work with such content, there are a few advantages in
developing independent tools instead:

 * To eliminate any dependency on the Moin code, its bundled libraries, or on
   its external dependencies (of which there are many for Moin 2.0)

 * To focus on areas of functionality that are considered priorities, such as
   the publishing of content as static Web sites, which may not be adequately
   or optimally supported by Moin

 * To provide other implementations of parsers and serialisers for the markup
   format, thus establishing it as more genuinely interoperable markup
   standard

 * To be able to work with the content more easily and to develop tools for
   doing so

The wiki format is described in the [[/MoinSyntax|syntax documentation]].

<<Anchor(GettingStarted)>>
== Getting Started ==

To convert a collection of wiki pages in a directory (with `pages` containing
the original pages and `htdocs` being the desired output directory), run the
`moinconvert` program as follows:

{{{
moinconvert --input-dir pages --output-dir htdocs --all
}}}

To convert a single file from such a collection (such as `FrontPage`), run the
program as follows:

{{{
moinconvert --input-dir pages FrontPage
}}}

This will produce the serialised page on standard output rather than writing
it to a file.

Other options are typically useful when running the program, such as `--theme`
for styling and wrapping the output, `--macros` for expanding macros in
documents, and `--format` for choosing alternative output formats.

See [[/moinconvert]] for more information on the `moinconvert` program.

<<Anchor(Architecture)>>
== Abstractions and Architecture ==

MoinLight provides a number of abstractions for working with Moin wiki content:

 * [[/Input]] contexts permit the interpretation of existing content in
   certain ways so that a collection of text files can be treated like a wiki

 * [[/Output]] contexts permit the publishing of content in certain
   ways so that wiki content can be shared on the Web

 * [[/Macros]] define locations in documents where content is to be inserted
   or expanded

 * [[/Metadata]] is used to configure the processing of content by defining
   the different abstractions involved

 * [[/Parsers]] interpret various forms of markup-related content, producing a
   document tree representation that can be inspected and processed

 * [[/Serialisers]] convert the document tree representation into other
   content formats such as HTML or even back into Moin format

 * [[/Themes]] augment serialised content with additional details and
   resources

A major objective with MoinLight is to be able to produce static files that
can be served using a typical Web server without any need for scripts,
applications or other kinds of dynamic content. Other objectives are described
in the [[/Roadmap]] document.
