paul@211 | 1 | = MoinLight = |
paul@211 | 2 | |
paul@211 | 3 | MoinLight is a distribution of programs and libraries for working with content |
paul@211 | 4 | encoded in the [[https://moinmo.in/|MoinMoin]] wiki markup format. This markup |
paul@211 | 5 | format is generally concise and supports many kinds of HTML document features |
paul@211 | 6 | using intelligible plain text representations. |
paul@211 | 7 | |
paul@211 | 8 | ########## The graph below shows the architecture of the system... |
paul@211 | 9 | |
paul@211 | 10 | {{{#!graphviz |
paul@211 | 11 | #format svg |
paul@211 | 12 | #transform notugly |
paul@211 | 13 | digraph architecture { |
paul@211 | 14 | node [shape=box,fontsize="13.0",fontname="Helvetica"]; |
paul@211 | 15 | rankdir=LR; |
paul@211 | 16 | |
paul@211 | 17 | subgraph { |
paul@211 | 18 | rank=same; |
paul@211 | 19 | input [label="Input context",URL="Input"]; |
paul@211 | 20 | markup [label="Moin content",shape=folder,style=filled,fillcolor=cyan]; |
paul@211 | 21 | } |
paul@211 | 22 | |
paul@211 | 23 | parser [label="Parser",URL="Parsers"]; |
paul@211 | 24 | |
paul@211 | 25 | subgraph { |
paul@211 | 26 | rank=same; |
paul@211 | 27 | tree [label="Document tree",shape=folder,style=filled,fillcolor=cyan]; |
paul@211 | 28 | evaluation [label="Macro evaluation",shape=ellipse]; |
paul@211 | 29 | } |
paul@211 | 30 | |
paul@211 | 31 | serialiser [label="Serialiser",URL="Serialisers"]; |
paul@211 | 32 | |
paul@211 | 33 | theme [label="Theme",URL="Themes"]; |
paul@211 | 34 | |
paul@211 | 35 | subgraph { |
paul@211 | 36 | rank=same; |
paul@211 | 37 | output [label="Output context",URL="Output"]; |
paul@211 | 38 | pages [label="Web content",shape=folder,style=filled,fillcolor=cyan]; |
paul@211 | 39 | } |
paul@211 | 40 | |
paul@211 | 41 | markup -> input -> parser -> tree -> evaluation -> tree -> serialiser -> |
paul@211 | 42 | theme -> output -> pages; |
paul@211 | 43 | } |
paul@211 | 44 | }}} |
paul@211 | 45 | |
paul@211 | 46 | ########## |
paul@211 | 47 | |
paul@211 | 48 | Although it is obviously possible to use the MoinMoin software (hereafter |
paul@211 | 49 | referred to as Moin) to work such such content, there are a few advantages in |
paul@211 | 50 | developing independent tools instead: |
paul@211 | 51 | |
paul@211 | 52 | * To eliminate any dependency on the Moin code, its bundled libraries, or on |
paul@211 | 53 | its external dependencies (of which there are many for Moin 2.0) |
paul@211 | 54 | |
paul@211 | 55 | * To focus on areas of functionality that are considered priorities, such as |
paul@211 | 56 | the publishing of content as static Web sites, which may not be adequately |
paul@211 | 57 | or optimally supported by Moin |
paul@211 | 58 | |
paul@211 | 59 | * To provide other implementations of parsers and serialisers for the markup |
paul@211 | 60 | format, thus establishing it as more genuinely interoperable markup |
paul@211 | 61 | standard |
paul@211 | 62 | |
paul@211 | 63 | * To be able to work with the content more easily and to develop tools for |
paul@211 | 64 | doing so |
paul@211 | 65 | |
paul@211 | 66 | == Getting Started == |
paul@211 | 67 | |
paul@211 | 68 | To convert a collection of wiki pages in a directory (with `pages` containing |
paul@211 | 69 | the original pages and `htdocs` being the desired output directory), run the |
paul@211 | 70 | `moinconvert` program as follows: |
paul@211 | 71 | |
paul@211 | 72 | {{{ |
paul@211 | 73 | moinconvert --input-dir pages --output-dir htdocs --all |
paul@211 | 74 | }}} |
paul@211 | 75 | |
paul@211 | 76 | To convert a single file from such a collection (such as `FrontPage`), run the |
paul@211 | 77 | program as follows: |
paul@211 | 78 | |
paul@211 | 79 | {{{ |
paul@211 | 80 | moinconvert --input-dir pages FrontPage |
paul@211 | 81 | }}} |
paul@211 | 82 | |
paul@211 | 83 | This will produce the serialised page on standard output rather than writing |
paul@211 | 84 | it to a file. |
paul@211 | 85 | |
paul@211 | 86 | Other options are typically useful when running the program, such as `--theme` |
paul@211 | 87 | for styling and wrapping the output, `--macros` for expanding macros in |
paul@211 | 88 | documents, and `--format` for choosing alternative output formats. |
paul@211 | 89 | |
paul@211 | 90 | == Abstractions and Architecture == |
paul@211 | 91 | |
paul@211 | 92 | MoinLight provides a number of abstractions for working with Moin wiki content: |
paul@211 | 93 | |
paul@211 | 94 | * [[/Parsers]] interpret various forms of markup-related content, producing a |
paul@211 | 95 | document tree representation that can be inspected and processed |
paul@211 | 96 | |
paul@211 | 97 | * [[/Serialisers]] convert the document tree representation into other |
paul@211 | 98 | content formats such as HTML or even back into Moin format |
paul@211 | 99 | |
paul@211 | 100 | * [[/Themes]] augment serialised content with additional details and |
paul@211 | 101 | resources |
paul@211 | 102 | |
paul@211 | 103 | * [[/Macros]] define locations in documents where content is to be inserted |
paul@211 | 104 | or expanded |
paul@211 | 105 | |
paul@211 | 106 | * [[/Input]] contexts permit the interpretation of existing content in |
paul@211 | 107 | certain ways so that a collection of text files can be treated like a wiki |
paul@211 | 108 | |
paul@211 | 109 | * [[/Output]] contexts permit the publishing of content in certain |
paul@211 | 110 | ways so that wiki content can be shared on the Web |
paul@211 | 111 | |
paul@211 | 112 | A major objective with MoinLight is to be able to produce static files that |
paul@211 | 113 | can be served using a typical Web server without any need for scripts, |
paul@211 | 114 | applications or other kinds of dynamic content. Other objectives are described |
paul@211 | 115 | in the [[/Roadmap]] document. |