=head1 Introduction to Latemp

Latemp is a content management system (CMS) for static HTML pages, based
on Website Meta Language (L<http://thewml.org/>). If you are not already
familiar with Website Meta Language (from now on - WML), please familiarize
yourself with it.

There are two ways to start working with Latemp. The first is to start an
entirely new site. That's what the command C<latemp-setup> is for. Just type
C<latemp-setup -man> and follow the instructions. The second is to convert
an existing WML-based site to Latemp. This is a matter of integrating the
relevant code snippets, makefile excerpets and build logic from an existing
Latemp project.

This document provides a reference to all the Latemp directives.

=head1 Overview of a Standard Latemp Workspace

This section will provide an overview of a standard latemp workspace. To
understand what is going here, invoke the following command:

    latemp-setup --theme=better-scm --dir=my-project \
        --remote-path=/tmp/my-project-dest

This will create a sample, mostly empty but still functional, Latemp project
in the my-project sub-directory of the current directory. You can build it by
cding to this directory and invoking the following commands:

    ./gen-helpers.pl
    make

Now, let's overview the files there:

=head2 gen-helpers.pl

This file searches for source files that should be used to generate the
site's contents, and the files C<include.mak> and C<rules.mak> that will
be included in the makefile. It uses the auxiliary module
L<HTML::Latemp::GenMakeHelpers> by default, but can be modified to have
a different logic, but with common results.

The most important modification that one can do to it is to add another host,
or rename an existing ones. To do that, just manipulate the following line:

    (qw(common mysite))

And add or remove hosts. Note that you should always keep the C<common>
meta-host.

This file should be run whenever files or directories are added or removed
from the working copy.

=head2 Makefile

This file contains the makefile used to build the project. It can be modified
as long as it includes C<include.mak> and C<rules.mak> and calls their
C<latemp_target> template.

=head2 lib/MyNavData.pm

This file contains the definition for the navigation menu and site-flow.
Latemp makes use of L<HTML::Widgets::NavMenu> for this, and this module serves
as an input to it. Read the online documentation of HTML::Widgets::NavMenu
for more information how to edit this file.

=head2 lib/MyNavLinks.pm

This is a module that is used to generate the HTML navigation links
("Previous", "Up" and "Next"). It can be customized by the user to create more
sophisticated rendering of them. It should be noted that generating navigation
links in the C<E<lt>headE<gt>> tag is not dependent on this.

=head2 unchanged

This is an empty file that is used to control the creation of directories
inside the destination folder.

=head2 template.wml

This is the Web Meta Language template that is used to control the site-wide
preferences. It includes the header "latemp/latemp-main.wml" which brings in
the Latemp logic.

Before and after it one can write other WML directives to control the page
generation.

=head2 src/common

This sub-directory contains files that are common to all the hosts on which
your site is spread. Generally, it should contain CSS stylesheets, images
that serve as backgrounds, buttons, logos, and so forth.

=head2 src/mysite

This sub-directory contains files that are generated for the host "mysite".
If the file ends with the C<.html.wml> extension it will be pre-processed
using the C<wml> WML processor. Else, it will be copied verbatim.

=head1 Overview of Latemp-Related Directives

This section provides an overview of the Latemp-related directives that the
Latemp-deployer can make use of.

=head2 Latemp mp4h tags.

=head3 <latemp_lang "en-US" />

This tag specifies the language as present in the <html> tag C<lang> and
C<xml:lang> attributes.

=head3 <latemp_encoding "utf-8" />

This tag controls the encoding of the page.

=head3 <latemp_subject "My Subject" />

This directive sets the subject of the page. Generally the subject appears
within the C<E<lt>titleE<gt>> tag within the HTML C<E<lt>headE<gt>> and
possibly also the first C<E<lt>h1E<gt>> tag.

=head3 <latemp_common_keywords "Keyword 1, other keyword" />

This directive sets site-wide keywords to be mentioned in the
C<E<lt>meta name="keywords" /E<gt>> tag of the HTML head tag.

=head3 <latemp_more_keywords "Foo, Bar" />

This sets additional (usually page specific keywords).

=head3 <latemp_version_control_id "$Id" />

This sets a version control ID (such as CVS' or Subversion's C<$Id$> string)
to be used to identify the timestamp of the page.

=head3 <latemp_author "Jonh Smith" />

This sets the name of the author within the head tag.

=head3 <latemp_webmaster>...</latemp_webmaster>

This sets an HTML portion to identify the webmaster of the site. Note that
this directive captures what comes between its start and end tags.

=head3 <latemp_license>...</latemp_license>

A License information for the page.

=head3 <latemp_affiliations_buttons>...</latemp_affiliations_buttons>

This sets out HTML code for various affiliations links that the site
maintainer would like to see in the side-bar.

=head3 <latemp_top_left_corner_logo>...<latemp_top_left_corner_logo>

An HTML for a Logo to come at the side bar, right before the navigation menu.

=head3 <latemp_meta_desc "My description" />

A description to put inside the appropriate C<E<lt>meta /E<gt>> tag.

=head3 <latemp_extra_head_elements>...</latemp_extra_head_elements>

More HTML to put between the opening and closing C<E<lt>headE<gt>> tags
at the end.

=head3 <latemp_after_title_head_elements>...</latemp_after_title_head_elements>

More HTML to put between the opening and closing C<E<lt>headE<gt>> tags,
at the beginning, right after the title.

=head3 <latemp_foot_image>.../<latemp_foot_image>

This sets the HTML for the image in the footer, which is typically the last
thing displayed on the page. Use it to define a bottom "Back to my Homepage"
or "Hosted at MyHosting" footer.

=head3 <latemp_news_get_news_box_contents />

This retrieves the HTML of a news box. The news box contains one HTML
C<E<lt>liE<gt>> tag for each news item, with summaries and links. See
"News Management" below.

=head3 <latemp_news_get_news_page_entries />

This retrieves the HTML of the entries for display in the news page. See "News
Management below".

=head3 <latemp_top_banner>...</latemp_to_banner>

This tag defines the HTML of a banner to put at the top of the page.

=head3 <latemp_before_main_title>...</latemp_before_main_title>

This tag defines text that will come after all the layout but before the
main title. (usually an C<E<lt>h1E<gt>> tag).

=head3 <latemp_after_main_title>...</latemp_before_main_title>

This tag defines text that will come after the
main title (usually an C<E<lt>h1E<gt>> tag), but before the main body.

=head3 <latemp_after_body>...</latemp_after_body>

This tag defines text that will come after the main body, so that it will
be appended to the end.

=head3 <latemp_html_doctype standard="MyStandard" />

This tag (that can be customised by the user after the prelude and before the
driver) is used to generate the text of the DOCTYPE.

=head2 Variables with special meaning

=head3 <set-var latemp_theme="better-scm" />

This variable specifies the theme to be used by Latemp. If it isn't specified
the theme defaults to the value of the C<$(LATEMP_THEME)> pre-processor macro.

=head3 <set-var latemp_filename="docs/index.html" />

This variable specifies the path of the file relative to the server's
root. If it is not specified, it defaults to C<$(LATEMP_FILENAME)>.

=head3 <set-var latemp_server="myhost" />

This variable specifies the server of the current file for input to
L<HTML::Widgets::NavMenu>. If not specified, it defaults to
C<$(LATEMP_SERVER)>.

=head3 <set-var latemp_with_favicon="1" />

The C<latemp_with_favicon> controls whether a link tag to a favicon should be
placed in the HTML head tag.

=head3 <set-var latemp_with_breadcrumbs_trail="1" />

This variable controls whether a breadcrumbs trail
(e.g: "Home -> Software -> Games -> Freecell") should be displayed at the
top of the page.

=head3 <set-var latemp_with_head_meta_tags="1" />

This variable controls whether the "author", "description" and "keywords"
C<<< <meta /> >>> tags should be inserted into the HTML head.

=head3 <set-var latemp_nav_links_allowed_places="top-left bottom-left" />

This should give a whitespace-separated list of places to render the HTML
visual navigation links in. Currently available positions are:

=over 8

=item top-left

Right below the logo and above the navigation menu (in the side bar).

=item bottom-left

In the bottom of the side bar.

=back

=head3 <set-var latemp_with_timestamp="1" />

This specifies that the timestamp for the page should be rendered.

=head3 <set-var latemp_supress_default_h1="1" />

This directive causes the default C<E<lt>h1E<gt>> tag with the contents of the
subject not to be displayed.

=head3 <set-var latemp_screen_stylesheet_url="http://www.myhost.foo/style.css" />

If set, overrides the standard stylesheet URL as placed in the HTML head tag.

=head3 <set-var latemp_print_stylesheet_url="http://www.myhost.foo/print.css" />

If set, overrides the URL of the print stylesheet.

=head3 <set-var latemp_with_xml_declaration="1" />

If set, includes an XML declaration:

    <?xml version="1.0" encoding="utf-8" ?>

at the beginning of the document.

=head3 <set-var latemp_html_standard="xhtml11" />

Sets the default HTML standard to be declared in the DOCTYPE. Valid options
are: "xhtml1.0-trans", "xhtml1.0-strict", "xhtml1.1-mathml" (XHTML 1.1 with
MathML), "xhmtl1.1-mathml-svg (XHTML 1.1 with MathML and SVG).
The DOCTYPE defaults to XHTML 1.1 Transitional if this variable is not
specified.

=head3 <set-var latemp_navmenu_object_class="My::NavMenu" />

Sets the class and module for the navigation menu. Defaults to the standard
"HTML::Widgets::NavMenu".

=head3 <set-var latemp_gen_plain_page="1" />

If set, will generate a page with only the body of the page, and not with a
sidebar, footer, breadcrumbs trail, etc. Useful for generating a version
for printing.

=head3 <set-var latemp_with_html_head_nav_links="1" />

If set, puts up <link rel="next" />, <link rel="prev" />, etc. navigation
links within the <head> ... </head> tag. These will appear in naviagtion
bars available for popular browsers, for easy navigation within the site.

=head3 <set-var latemp_with_html_head_stylesheets="1" />

This variable controls whether or not the default <link /> tags to the
stylesheets will be displayed within the <head>...</head> section of
the document.

=head2 Tags to be defined by the user:

=head3 <define-tag latemp_timestamp_wrapper endtag="required">...</define-tag>

C<%body> contains the version control ID as passed from
C<E<lt>latemp_version_control_id /E<gt>> and this wraps it in a display
for the user.

=head2 IPP Preprocessor Macros

=head3 $(LATEMP_THEME)

This specifies the default theme to be used if the C<latemp_theme> variable
is not specified.

=head3 $(LATEMP_FILENAME)

This specifies the default filename of the file relative to the root directory
of the host to be used if the C<latemp_filename> variable is not specified.

=head3 $(LATEMP_SERVER)

This specifies the default server to be used if the C<latemp_server> variable
is not set.

=head3 $(ROOT)

This variable gives a path to the root directory of the current server. It can
be used to construct relative links.

=head1 News Management

To manage news one populates the C<@news_items> array in the file
C<lib/MyManageNews.pm> in your distribution. Generall the fields C<'author'>
and C<'category'> will be common to all the items. (If not - specify them
explicitly in every item). Other items are specified in the
L<HTML::Latemp::News> man page. An example news item is brought here:

        {
            'title' => "Changes of 18-April-2005",
            'id' => "changes-2005-04-18",
            'description' => q{Around 18 April, 2005, Jane's Site has seen a
                lot of changes. Click the link for details on them.},
            'date' => "2005-04-18",
            'author' => "Jane Smith",
            'category' => "Jane's Site",
        },

This will propogate the news into the navigation menu, etc. See the
news-related tags above for embedding news related content into your pages.

If you want to build an RSS feed, you should add the C<news_feeds> target to
the C<dummy>-invoked  targets in the makefile.

