== TAHCHEE MANUAL
-- Author: Sbastien Pierre
-- Version: 0.9.8


1. Quick setup
==============

First, you will need a Unix-based machine, or a Windows machine with an
available shell (using MinGW or Cygwin), with Python 2.4+ installed.

    1) [Download Tahchee](http://www.ivy.fr/tahchee), and decompress the tarball
    2) Ensure that [Cheetah](http://www.cheetahtemplate.org) (starting from version 0.9.7) is installed
    3) Optionally install the [Python Imaging Library](http://www.pythonware.com/products/pil/) (PIL)
    4) Optionally install [HTML tidy](http://www.w3.org/People/Raggett/tidy/)

Once this preliminary setup is done, go into the uncompressed Tahchee directory
and do

>   python setup.py install

You now have the `tahchee` command available in your path, and should be ready
to start using Tahchee.

    Note ______________________________________________________________________
    You can alternatively install Tahchee by copying the `tahchee` directory within the
    `Sources` directory of Tahchee within your Python `site-packages` directory,
    and running tahchee with the following command:
    `python -c "import sys, tahchee.main ; tahchee.main.run(sys.argv[1:])"`


2. First run
============

To test your installation, go into Tahchee `Documentation/Example` directory and
type `make`. The process should run, and output lines similar to those lines:

>   [ ] Mode is 'local', generating in 'Site/Local'
>   [ ] Precompiling template 'Example/Templates/Base'
>   [ ] Precompiling template 'Example/Templates/Page'
>   [ ] Generating file 'index.html'

This process will create the example HTML site in the `Site/Local` subdirectory.
You will find the resulting HTML there. If you want to know what other
options are available, type `make info`.

3. How the stuff works
======================

Tahchee is best described as a "website compiler". You design your site with
_templates_, which contain the common parts between all your pages in your
website. Once you have written your templates, you can start writing _pages_ which ''fill in the
blanks'' of your templates. The main difference between a template and a page is
that a template needs the data provided by a page to render to an HTML (or
whatever format) file. In other words, templates are incomplete pages, and pages
complete templates.

To get a better idea of this, let's look at a subset of the example data (I've
omitted some files which are not relevant in our explanation):

>   |-- build.py
>   |-- Makefile
>   |-- Pages
>   |   |-- index.html.tmpl
>   |   `-- screen.css
>   |-- Site
>   |-- Templates
>   |   |-- Base.tmpl
>   |   `-- Page.tmpl

Running `make` will populate your website project directory:


>   |-- build.py
>   |-- Makefile
>   |-- site.checksums            (created by build.py)
>   |-- Pages
>   |   |-- index.html.tmpl
>   |   `-- screen.css
>   |-- Site
>   |   `-- Local                 (this is the directory created by tahchee)
>   |       |-- index.html
>   |       |-- restpage.html
>   |       `-- screen.css
>   |-- Templates
>   |   |-- Base.py               (these are 'compiled' versions of your templates)
>   |   |-- Base.tmpl
>   |   |-- Page.py
>   |   |-- Page.tmpl

We see that the `Site/Local` was populated with the same content as the `Pages`
directory, excepted files ending in `.tmpl` were stripped of their extension. Before
being stripped of their extensions, the `.tmpl` files were actually processed with
Tahchee to generate the resulting file (which can be HTML, or any other file,
such as CSS, PHP, etc).

There are also some `.py` files in the `Templates` directory, which are 
the result of Cheetah compiling the templates files (`.tmpl`) in the `Templates`
directory into executable Python code.

Tahchee works as follows:

    1) Compiles the `tmpl` files in the `Templates` directory
    2) Compiles the `tmpl` files in the `Pages` directory and copies them in
    the `Site/Local` subdirectory, stripping them of the `tmpl` extension
    3) Copies other files from 'Pages' to the appropriate location in the
    `Site/Local` directory.

4. More about templates
=======================

You can learn the basics of using templates simply by looking at the files in
the example. You will see that in our example, we have a template hierarchy:

>   Base
>   `-- Page
>       `-- index.html

This means that a change in `Base` will affect `Page` as well as 'index.html`.
By making new templates that "extend" other templates, you can build a whole
set of specific templates for your site sections:

>   Base
>   `-- Page
>       `-- SectionPage
>           |-- FAQPage
>           |-- UserPage
>           `-- ProjectPage

If you look closer at the provided templates, you will see that some
variables (like `$site`) are already available. Tahchee actually provides access
to Python object representing the current page and the website as a whole, using
the following keywords:

    - `$page` refers to the current page, and is a Page object
    - `$site` refers to the current site, and is a Site object

The Page and Site objects are defined in the Tahchee Python API, available 
with this documentation (see `Documentation/tahchee-api.html`). For instance, the
'site' object provides a `link` method that allows to link to a path or URL, and
ensure that the link target exists.

Since Tahchee 0.9.7 a plugin system allows to make additional variables
available to templates. This allows you to write your custom Python class and
functions, and easily bind them to your templates.

    Notes ___________________________________________________________________

    Starting from Tahchee 0.9.8, you can use extensions like `.tmpl.html` as
    well, instead of `html.tmpl`. This will make it easier for some editors
    to get the proper syntax highlighting.

    This is however only available to `Pages`. General templates (those in
    `Templates`) have to stay as `.tmpl`. There are syntax coloring modes
    for Cheetah templates available in many text editors.

4.1 Templates and the build process
-----------------------------------

Templates are "applied" (which means that they generate a file in the `Site`
directory) under a set of conditions:

  - They are not filtered out (see `ACCEPT` and `IGNORE` in site configuration)
  - The template or its parents were modified
  - The template was flagged with `ALWAYS_REBUILD`
  - A file state in a `DEPENDS` directive has changed

If you want a template to be *always applied*, you should simply add the
following line to the top of your template:

>   ## ALWAYS_REBUILD
>   #extends Templates.Page
>   ...

If you want to state an explicit dependency between your template and another
file, simply put its absolute path or path from the template parent directory as
follows:

>   ## DEPENDS = ../../path/to/my/file.data
>   #extends Templates.Page
>   ...

These indications will allow Tahchee to decide when something should be rebuilt
or not. In case you would like to do that from the `Makefile`, you can invoke
the `build.py` script directly with the page you want to rebuild:

>   python build.py Pages/index.html.tmpl

5. Plugins
==========


Kiwi Markup
-----------

Since version 0.9.7, "Tahchee" comes integrated with the _Kiwi_ markup language.
Kiwi is a simple, expressive text markup language that allows to create XML/HTML
documents without actually writing all the HTML tag. For instance

>   Here is a paragraph, followed by a list:
>   
>   1) The list is numbered
>   2) Here is the second item
>      - Here is an unnumbered sublist
>   3) And the third item

generates the following HTML code:

>   <p>Here is a paragraph, followed by a list:</p>
>   <ul>
>       <li>The l ist is numbered </li>
>       <li>Here is the second item
>           <ul><li>Here is an unnumbered sublist</li></ul>
>       </li>
>       <li>And the third item</li>
>   </ul>

Kiwi comes pre-installed with _tahchee_. To use it, simply process any of your
variable with the `$kiwi' function. For instance, if your page template
contains a content section `<div id="content">$content</div>' that holds your
page content, and that you expect `$content' to contain Kiwi text, simply use
the following:

>   <div id="content">$kiwi($content)</div>

This will enable any content to be written in Kiwi. Also, note that 
with kiwi you can mix HTML (or XML) with Kiwi without any problem, so you can
gradually convert your HTML files to Kiwi markup if you need to.

Kiwi is pretty much similar to [Markdown](http://daringfireball.net/projects/markdown/),
but may be more powerful in some areas. You can learn more about
Kiwi [here](http://www.ivy.fr/kiwi).

ReStructuredText Markup
-----------------------

In addition to Kiwi markup, Tahchee also supports [Rest](http://docutils.sf.net/rst)
markup. To use Rest markup in one of your templates, simply do:

>      $rest("some rest **text**")

if you prefer, you can also refer to a variable defined elsewhere:

>   #def rest_text
>   Hello, I am a rest text
>   #end

and do:

>   $rest($rest_text)

In case you have encoding problems, the 'rest' function takes the following
paramaters:

>   rest(text,encoding,outputEncoding)

So you can specify the _input encoding_ ('encoding') and _output encoding_
('outputEncoding'), which should be given as a strings (like 'utf-8', 'latin-1',
'ascii', etc)

6. Configuration
================

Tahchee can be configured to meet your specific site setup. All the configuration
should be made in the `build.py` file in your Tahchee website directory, which
present you the available options.

Your website `build.py` contains a set of options that you can change and edit.
These options should look like the following.

>   # You can change the following things
>   # =============================================================================
>   URL     = "www.ivy.fr/tahchee"
>   INDEXES = ["index.*"]
>   IGNORES = [".cvs", ".CVS", ".svn", ".DS_Store"]
>   ACCEPTS = []
>   # =============================================================================

There are many configuration options available. Here is the complete list of
supported options.

    - 'URL' allows you to set the main URL from which your website will be
      accessed. This is useful when you want to generate a website with absolute
      links.

    - 'MAIN' indicates the relative path of the main HTML file for your website.
      This is usually `index.html`. When 'SHOW_MAIN' is set, then the main file
      will be displayed in your browser after each build. (new in 0.9.8)

    - 'SHOW_MAIN' (can be `True` or `False`), indicate if you want your main
      page to be shown in your browser after each build. (new in 0.9.8)
    
    - 'INDEXES' is a set of "globs" (shell-like patterns) that tell which
      files should be considered as indexes. This also affects link expansion.
    
    - 'IGNORES' specifies a list of "globs" of files that should be ignored.
      These files will not be copied or processed. You can also give paths
      relative to the `Pages` directory.

    - 'ACCEPTS' specifies the list of "globs" that will be processed. You should
      leave this empty, as if you specify one 'ACCEPT', then everything not
      accepted will be ignored.
    
    - 'TIDY' indicates the path to the HTML tidy utility (it is auto-detected
      otherwise).

    - 'USE_TIDY' (takes `yes` or `no`, yes is the default), indicates if HTML
      tidy should be enabled or not.

    - 'TIDYFLAGS' specifies the flags that should be passed to HTML tidy. You
      can also use an environment variable with the same name.

    - 'TIDYCONF' specifies the configuration file that should be used by HTML
      tidy. You can also use an environment variable with the same name.

    - 'CHANGE' can be set to `date` to detect changes based on the file date and
      `sig` to detect changes based on the signature.

7. Extending Tahchee
====================

Tahchee can be very easily extended using its plugin system (since Tahchee
0.9.7).

Writing a plugin is very easy:

 - Write your Python code independently
 - Wrap your classes/functions into a plugin that will make particular objects
   available to templates as variables (pretty much like the `$site` object)
 - Publish your plugins by putting them within the `Plugins` directory
 - Type `tahchee plugins` to make sure that your plugin was registered

If you don't want to write plugins, you can alternatively drop some Python
modules within the `Sources` directory of your Tahchee website (you have to
create this directory, which is not created by default). Tahchee will then
automatically add this directory to the Python path.

So, if you create a module in `Sources/mymodule.py`, you can use it in your page
templates by doing:

>   #import mymodule

and then

>   $mymodule.doSomething()...

This is probably the easies way to extend Tahchee functionality.

7. Some advices
===============

Tahchee can be very powerful, provided you do things with a little bit of
discipline. Here is what I would advice :

    - Spend some time thinking about your site map, and the type of pages that
      you want to have.
    - Do not write too many Templates, try to keep them minimal, and make a list
      of the variables names that will be filled by Pages.
    - Do not hesitate to use templates for your CSS files, as it can allow
      (among other things) to quickly change a set of predefined colors.
    - Cheetah templates allow to use any Python module, so do not hesitate to
      add extra functionality in Python modules that you can put just inside
      your 'Templates' directory or anywhere in your PYTHONPATH.
    - Do not hesitate to write Plugins to provide custom functionalities
      (automatic generation of pages or linked data)

I hope this small documentation will help you kickstart using Tahchee, if you
have questions or comments, you can contact me at <sebastien@ivy.fr>.

# vim: ts=4 sw=4 et fenc=latin-1 syn=kiwi
