restindex
    crumb: restindex
    # we can't call the source file restindex.txt !
    target: restindex.html
    page-description:
        An explanation of the options and default values in the restindex.
    /description
/restindex

===============
 The restindex
===============

--------------------------------------------
 Controlling rest2web Through the restindex
--------------------------------------------

.. contents:: The restindex 

Introduction
============

reST format alone doesn't tell us everything we need in order to build the pages. It will generate a title from the top headline - but it won't tell us things like which template file to use, what text to use as a description of the page in the index, etc. For this I've added something called a *restindex*, which is a simple list of keywords and values to go at the start of every page you want rest2web to render for you.

There is another set of values you can add at the start of your files. These are *uservalues* and they allow you to add your own values into the namespace when templating. See the uservalues_ page for the details.

The Master restindex
====================

This shows every option in the **restindex** - with an example value. In practise you only need to ever *use* values that are different from the defaults. For a good example see the tutorial_.

::

    restindex          
    # this is a comment
        include: yes 
        format: html        
        file-extension: shtml       
        template: template.txt 
        template-encoding: utf8
        index-file: index.txt
        section:  section name                  
        link-title: This is the text to use in the link
        page-title: We *usually* only need a title for HTML
        page-description: 
            this is a description
            It can go across several line
            And even be indented a bit.
            It will be interpreted as *reST*.
        /description
        crumb: Short Name  
        build: yes
        initialheaderlevel: 1
        tags: keyword1, keyword2, keyword3
        file: filename1
        file: filename2
        file: filename3
        target: thisfile.html   
        encoding: utf8  
        output-encoding: utf8 
        sectionlist: section-name1, section-name2, section-name3
        section-pages: section-name1, page1, page2, page3
        section-title: section-name1, title
        section-description: section-name1
            This is also a description.
            
        /description
        section-pages: , page1, page2, page3
        section-title: , Default Section Title
        # note the leading ',' to specify the default section
        section-description: 
            Default section description.
            
        /description        
    /restindex

Every **rest2web** source file must start with a 'restindex' chunk. This tells rest2web how to render the page. If a text file doesn't start with a restindex, it won't be processed.

To qualify as a restindex - the first non-empty line of the file must be **restindex**. Subsequent lines that start with a '#' are comments.

Each line is in the format - ``keyword: value``, except for multiline values. Currently this means only the ``description:`` type keywords.

If a keyword is missing, or the value is blank, then the default will be used.

The restindex is used for two purposes.

1) For setting values for individual pages. In this case the index is at the start of the page that is being processed. Only certain values are relevant.
2) In the index page, the restindex can set options for a whole directory.


Restindex and Uservalues in a ReST Comment
------------------------------------------

Since rest2web 0.5.0, you can put the restindex (and `uservalues <reference/uservalues.html>`_) inside a ReST comment.

That means that your source documents can contain a restindex *and* still be valid ReStructured Text documents : ::

    ..
        This is a ReST Comment
        This page is copyright by me, 1941
        
        restindex
            format: html
            page-title: This is a Phantasmagorical Page
        /restindex
        
        uservalues
            site_title: My Great Site
            copyright: A Copyright Message
        /uservalues

Due to technical limitations (read laziness), the restindex and the uservalues *must* be the last part of the comment. {sm;:-)}


The Keywords
============

The keywords are as follows. [#]_ :

#. **include** - include this file in the index ? Should be yes or no. If no, the page is still generated from the template - but not included in the index page.

    This value applies to both normal files and index files. 
    
    Default value is yes.


#. **format:** - so far this can either be 'rest' or 'html'. It would be theoretically possible to allow other markup formats like 'sextile', or 'textile'. This is the markup format of the page. If it is 'rest' then docutils is used to generate the html (and usually the page title). The page contents are processed for embedded code, along with the templates (this allows you to use the templating in your indexes, using the ``.. raw::`` directive you can even do this in reST documents).

    The default value for this is 'rest'.


#. **file-extension:** - what file extension to use for this file. You don't need to specify the '.'. Normal values would be *html*, *htm*, *shtml*, or *shtm*. In 'index.txt' it can apply to a whole directory.

    The default value for this is 'html'. (Grr... I'd prefer it to be 'shtml', but there you go).


#. **template:** - this is the file to use as the template file. Relative locations will be relative to this directory of course. The template is processed for each page - and the body inserted, title created, dynamic elements are processed etc. See note on `Handling Paths`_.

    In an 'index.txt' this can specify the template file for the whole directory (and directories below it as well). 
    
    The default value for this is 'template.txt'. If none is specified in 'index.txt' and 'template.txt' doesn't exist, then 'template.txt' in the directory above will be tried. (moving up directories until one is found)


#. **template-encoding:** - This is the encoding of the specified template file. If an encoding isn't supplied then it will be guessed. 


#. **index-file:** - this specifies which page to use as the index file. (This file is used as the source to *build* the index file and as the target to link to in the index for the next level up). If 'index.txt' has this value, then all other values will be read from the restindex of the specified file. See note on `Handling Paths`_.

    It only has any meaning in the 'index.txt'. It can be used to specify an alternative page as being the main index page for this directory. The index page in the next level up will link to the target of the specified file.
    
    Default value is 'index.txt'.


#. **section:** - This specifies what section this page should appear in, in the relevant index page.
    
    For 'index.txt', the relevant index page is the next level up. The section is the section this index page will appear in, in *the index above* ! Got it ? (So for the 'root index' this value will never be used).
    
    The default value is for a page to be in the ``None`` section.


#. **link-title:** - this is the text used in the *link* to this page from the index page.

    In an 'index.txt', this will be the link to the index from the next level up.
    
    The page title will be uased as the default value, if none is specified.


#. **page-title:** - this is the page title. You should specify the ``page-title`` for index pages *and* for html pages. If the page body is in rest, this value overrides any autogenerated value.

    In an 'index.txt' this has the same meaning as in ordinary pages.
    
    There is no default value for this *FIXME: could use the filename ?*


#. **page-description:** - This marks the start of the description, which actually starts on the next line. The description is the text used along with the link to this page. Currently description format is 'rest' only. If you want to include HTML you can always use the 'raw' directive ! The page description can go over several lines - it terminates with '/description' on a newline. Uniform indentation (spaces) that occurs on *every* line, will be removed before processing.

    In an 'index.txt', this is the description used in the next level up.

    The default value is '' (no description).


#. **crumb:** - this is a short name for the page. It will be used for generating the 'breadcrumb' navigation links.

    For index pages, this name will form a link back to the page.
    
    The default value is to use the page title [#]_. (Which will usually be too long).
    
    For index pages (or if no page title is available), the filename is used as
    the default crumb instead.
    

#. **target:** - This specifies the target file. This will be the filename of the 'built' file, and the filename linked to in the index. If this keyword is used, the 'file-extension' keyword is ignored. (So a file extension must be included in the value for this keyword). The target can be a relative path to the file. See note on `Handling Paths`_.

    This value applies equally to 'index.txt' as other files. 

    The default value is the filename, minus '.txt', plus the value of the 'file-extension' keyword. 


#. **build:** - This should be 'yes' or 'no'. This allows you to specify that a file is not to be built, but should be included in the index. This allows you to include prebuilt files in the index.  In conjunction with the target keyword, it can be used to link to files in other locations.

    This value applies equally to 'index.txt' as other files. 

    The default value is 'yes'.

#. **initialheaderlevel** - An integer value. If your page format is ReST, then
   this value is passed to docutils when the page is built. This specifies the
   starting level (``h1``, ``h2``  etc) for headers in the page.

    This value applies equally to 'index.txt' as other files. 

    The default value is '1'.

#. **encoding** - this is the encoding of the file. The value must be a recognised python standard encoding.

    This value applies equally to an index file. 
    
    The default value is to ignore encoding and leave the 'subtools' (docutils) to guess encoding.


#. **output-encoding** - this is the encoding the page is written out as. The ``output-encoding`` ought to match the encoding used for the template ! The value must be a recognised python standard encoding, or one of two special values. **unicode** means don't encode the page - but present it to the template as a unicode string. **None** means use the encoding the page was originally encoded with. 

    This value applies equally to an index file. Setting it in an index file will set this value as the default for the whole directory *and* any subdirectories. (Unless an alternative is explicitly specified).
    
    The default value is 'None', which encodes the page using the encoding the page was originally encoded with. If a value is specified in any of the index pages above this page, then that will be used *instead* of the default.
    
    .. warning::
    
        Not including this keyword *is not* the same as including the keyword with no value.
        
        Not including it will cause the default for this directory to be used. 
        
        Including it, but leaving it empty is the same as specifying ``None``.


#. **sectionlist:** - This is a list of different sections for an index page. Links to pages in this directory appear in these different sections. The names should be unique as they will be used as "id's" to reference the section in the index.

    This value *only* has meaning in an index page.
    
    The default value is to have a single section referenced as 'default' if it isn't named.


#. **section-title:** - This is how you specify the title for each section. The first value is the nameof the section, followed by the title to be used for the section. This can be made into a link back up to a section table at the top of the index page. You can have multiple section titles, one per section.

    This value *only* has meaning in an index page.
    
    The default value is to use the section name as the title. (In 'Title-Case').  


#. **section-pages** - This specifies the *order* that pages appear in the section, for example in sidebars and in the ``sections`` data structure (used by the ``print_details`` `standard function`_). 

   The first value is the section name (or a leading comma for the default section). You use the filename (minus the '.txt') to specify a page. You don't have to list all the pages - but including a page that doesn't exist will raise an error. The pages you specify will appear in that order, followed by the rest of the pages in an arbitrary order.
   
   If you want to specify a subdirectory then use the directory name followed by 'index'. For example - ``subdirectory/index``.

    This value *only* has meaning in an index page.

    The default value is for pages to be in an arbitrary order.


#. **section-description:** - This is a description used for this section. It will appear above the links to the pages in the section. Other details are the same as the *page-description*.

    This value *only* has meaning in an index page.

    The default value is '' (no description).


#. **tags** - This option takes a list of keywords that applies to the page. You can then use this list in your template and pages. (E.g. for the ``meta type="keywords"`` data).

    This value applies equally to an index file.
    
    The default value is for it to be an empty list.


#. **file** - This option specifies an additonal file to copy from the source directory to the same directory as the target file. You can use this keyword multiple times in the restindex.

    This value applies equally to an index file.
    
    The default is for no additional files to be copied.

#. **plugins** - A list of plugins that should be applied to the page. See the plugins_ page for more details.

Building the Index
==================

The contents of a directory will only be built if it has an 'index.txt' file. This doesn't mean that the main file needs to be called 'index.html' or similar. There are two ways of changing this.

First - the 'index.txt' file can contain the content, but have a *target* value set. This sets the filename that the built file will be saved as.

Alternatively, 'index.txt' can have an *index-file* value. This will specify an alternative file that is to be used as the index page. In this case *all* the other values in 'index.txt' will be ignored and the values from the specified file will be used. This means the restindex will be very short : ::

    restindex
        index-file: anotherfile.txt
    /restindex


Handling Paths
==============

Windows, Linux, and the Mac, all handle paths differently. rest2web uses the file structure on disk to represent the structure of the website [#]_. This means we are using the same relative file paths to represent the file path on the local computer (on which rest2web is running) and the links within the website. Because the different OS's represent filepaths differently - we have a conflict between specifing file paths and urls. 

A few of the restindex keywords expect a path. Specifically ``template``, ``index-file``, and ``target``. ``template`` is always a filepath - because it specifies a file which is built into other pages. This means it can be specified as an absolute location - or using a native, relative file path.

For the other two values, ``index-file`` and ``target``, rest2web expects the path to be a *relative path, that follows the Unix path conventions*. This greatly simplifies our path handling routines.


restindex.txt
=============

You may be using rest2web to only generate some of the pages in your website. In this case it can be useful to provide a restindex for pages that rest2web *isn't* building. This enables rest2web to include them in indexes etc. You can easily doing this by setting the ``build: No`` option in the restindex. If you have several pages like this in a directory it can be a nuisance to maintain all the files for them. rest2web allows you to put several restindexes in a file called 'restindex.txt'. See the `Special Files`_ page for more details.

As a summary - every restindex in 'restindex.txt' will be assumed to have ``build: No`` set, but you must specify a target - or all the ouput files will be named 'restindex.html' {sm;:badgrin:}


------------


Footnotes
=========

.. [#] If you see **#** by every entry in this list (in the output html) rather than a numbered list, you need to update your version of docutils. (0.3.8 or more recent required)
.. [#] For index pages we may not pick up on the default of using the title - this is because we don't generate the page when reading the defaults. Index pages **need** crumbs !
.. [#] Although you can override this using the *'target'* keyword.

.. _Special Files: special_files.html
.. _uservalues: reference/uservalues.html
.. _tutorial: tutorial.html
.. _standard function: functions.html
.. _plugins: reference/plugins.html

