view release on metacpan or  search on metacpan

script/mowyw  view on Meta::CPAN

mowyw is a text processor for building static websites. It supports includes,
menus, external datasources (like XML files or databases) and syntax
hilighting.

To use mowyw you need three directories called B<source>, B<online> and
B<includes>. C<source> holds the source files that are to be interpreted by
mowyw. When you run mowyw, it will walk (recursively) through the source dir,
and for each file it either copies it verbatimely to C<online>, or, if the file
looks like HTML (ends on .html, .shtml, .htm etc.) it is processed by mowyw,
and the output is written into the online dir.

In C<includes/> are include files (how surprising), header, footer, global
include files, and optionally data source files.

You should always execute mowyw from the parent directory of these three
directories.

The name of these three directories can be overridden with command line
options.

=head1 COMMAND LINE OPTIONS

=over

=item --make

Only process files with a newer timestamp than the corresponding C<online/>
file. Note that this does not account for dependencies on include files and menu
files.

=item --quiet

Don't produce diagnostics or progress output

=item --postfix

Append the given postfix to the filename of all included file names (and
menu files). Defaults to the empty string.

=item --includes-prefix

Change the search path for include files. Defaults to C<includes/>.

=item --menu-prefix

Change the search for menu files. Defaults to C<includes/menu->.

=item --destination-prefix

Change the path for the output files. Defaults to C<online/>.

=item --source-prefix

Change the search path for source files. Defaults to C<source/>. Must be a
directory.

=item --encoding

Interpret all input files to have that encoding. Defaults to UTF-8.
(Conjecture: should default to the current locale... what to do?).

=back

All options except C<--make> can be specified in a config file, with more
customization options.

=head1 PROCESSING ORDER

mowyw processes files in several steps:

=over

=item

The file *mowyw.conf* is read (if it exists)

=item

The source directory is traversed

=item

For all source file that is actually processed

=over 8

=item -

the file C<includes/global> is read, if it exists

=item -

the current file is read, all markup is processed
     
=item -

the file C<includes/header> is processed and prepended to the current
output file

=item -

the file C<includes/footer> is processed and appended to the current
output file

=back

=back


=head1 MARKUP

Normal text (including HTML markup) is copied verbatimely to the output file.

Special directives are delimited either with C<[% ... %]> (preferred) or with
C<[[[ ... ]]]> (deprecated, but still supported for compatibility). 

Many elements take options, which are usually whitespace delimited, for
example C<[% include includefile.html %]>.

Inline elements consist only of one tag, while block elements run until the

script/mowyw  view on Meta::CPAN

language or configuration as its only argument. Example: `<pre>[%syntax
perl%]print "Hello, world\n";[%endsyntax%]</pre>`. The pseudo-syntax
C<escape> HTML-escapes the string and doesn't to any other syntax
hilighting.

=item

C<for> iterates of a datasource. See section <<datasource,DATA SOURCES>> 
below.

=item

C<ifvar> executes the block only if the variable is defined.
Example: C<[% ifvar title %]<h1>[%readvar title%]</h1>[% endifvar %]>.

=back
   

=head1 MENUES

mowyw has special menu support. To define a menu named C<foo>, create a file
C<source/menu-foo> with the following contents:

   <h2>Your menu title</h2>
   <ul>
       [% item home  <li><a {{class="active"}} href="/">Home</a></li>       %]
       [% item first <li><a {{class="active"}} href="/first">First</a></li> %]
       [% item sec   <li><a {{class="active"}} href="/sec/">First</a> 
           {{
                [% comment this is a sub menu that will only be visible
                    inside the `sec' menu                     %]
                [% item subitem1 <p>More menu markup</p>      %]
                [% item subitem2 <p>Even more menu markup</p> %]
           }}
       </li>   %]
   </ul>

(The menu name is purely for your internal use, it will appear nowhere in the
output)

Now in your index page you can include that menu with the directive 
C<[% menu home %]>. This will produce the menu contents with the markup
stripped, and insde the C<home> all of the contents will appear, the other menu
items only contribute the parts that are B<not> enclosed in double curly
braces.

Menus can ben nested, a nested menu entry can be accessed for example with
C<[% menu sec subitem1 %]>.

It's best to take a look at the examples in the distribution, which should
nicely illustrate the menu mechanism.


=head1 SYNTAX HILIGHTING

Syntax hilighting requires vim (see L<http://www.vim.org/>) and
L<Text::VimColor> to be installed
(otherwise the code is just HTML escaped, not hilighted).

Since you can't tell vim which encoding a source file is in,
non-ASCII-characters might not survive the round trip to vim if the locales
don't fit. On my systems UTF-8 locales worked, everything else didn't. So use
with caution.

=head1 OPTIONS

Currently only two options are supported, C<no-header> and C<no-footer>.
If they are set in a file via C<[% option no-header %]>, the inclusion of
header or footer files will be omitted.


=head1 DATA SOURCES

You can access external data sources by first C<bind>'ing a variable to a
data source, and then iterating with a C<for> loop over that source.

This is best illustrated with a short example.

File C<includes/news.xml>:
        
    <rootTag>
        <item>
            <headline>China buys Google</headline>
            <status>April's fool joke</stoke>
            <date>2007</date>
        </item>
        <item>
            <headline>Perl and Python join forces: Larry Wall and Guido von
            Rossum announce 'parrot'</headline>
            <status>April's fool joke</stoke>
            <date>Very old</date>
        </item>
    </rootTag>

Now you can access the contents of this XML file in your source files:

    [% bind news_variable type:xml file:news.xml root:item %]
    [% comment and iterate over news_variable %]
    [% for i in news_variable %]
        <h2>Breaking news: [% readvar i.headline %]</h2>
        <p>Status: [% readvar i.status %]</p>
    [% endfor %]

Data sources are handled via plugins. Currently XML and DBI are supported.

The XML source is explained by the example above. The only additional option
is 'limit', which can be set to a positive number and which limits the number
of iterations. This plugin is quite limited in that the file structure always
has be the
same: one root tag that contains a list of secondary tags, each of which many
only contain distinct tags. Nested tags might work, but aren't officially
supported.

DBI is perls generic database interface. You can use it to access a database.
This has some limitations, for example you can't reuse database connections,
so every C<bind> statement actually opens a database connection on its own.

For the brave, here is an example of how to use it:

    [% bind my_db type:dbi dsn:DBI:mysql:database=yourdatabse;host=dbhost
       username:your_db_user password:you_db_password encoding:latin1
       sql:'SELECT headline, status FROM news LIMIT 10'