## :highlighter
- code default undefined
- if defined, then the code is expected to receive a String containing perl6 code
and return a String of the same code highlighted in a form consistent with the rendering.

## create-collection
- Creates a collection from scratch.
- Erases all previous rendering files, rewrites the rendering database file
- If the file ｢/rendering.json｣ is absent, then update-collection will do the same
- Generates the index files

## update-collection
- Compares timestamp of sources in cache with timestamp of rendered files
- Regenerates rendered files when source in cache is newer.
- Regenerates the index files based on new files.

## report( :errors, :links , :cache, :rendered )
- Returns an array of strings containing information
- no adverbs: all link responses, all cache statuses, all files when rendered.
- :errors (default = False): Failed link responses, files with cache status Valid, Failed, Old; no rendering info
- :links-only (default = False): Supply link responses only.
- :cache-only (default = False): ditto for cache reponses.
- :just-rendered (default = False): the sources added by the most recent call to update-collection
- :when-rendered (default = True ): source and time rendered
- If no adverbs are given, then it is assumed all are True

# Usage

To render a document cache to HTML:
- place pod sources in `doc`,
- create a writable directory `html/`
- instantiate a Render object, (`$renderer`)
- run create-collection (`$render.create-collection`)
- verify whether there are problems to solve (`$renderer.report`)

## Customisation

### Sources

The cache and sources are managed using `Pod::To::Cache` module, and the source and repository names can be changed,
as documented in that module.

The source directory may contain subdirectories. The 'name' of a source is the `subdirectory/basename` of the source without an
extension, which are by default `pod | pod6`.

### Rendering

All of the rendering is done via mustache templates.

Each template can be over-ridden individually by setting the `:templates` option to a directory and placing the mustache file there.

Typically, the template `source-wrap.mustache` will be over-ridden in order to provide links to custom css, js, and image files.

The source-wrap template is called with the following elements:
- :title generated from the pod file's `=TITLE`
- :subtitle generated from the pod file's `=SUBTITLE`
- :metadata generated from the pod file's `=AUTHOR, =SUMMARY, etc `
- :toc generated from the pod file's `=HEAD`
- :index generated from the pod file's ` X<> elements`
- :footnotes generated from the pod file's `N<> elements`
- :body generated from the pod file
- :path a string containing the original path of the POD6 file (if the doc-cache retains the information)

In order to see all the templates, instantiate a Render object pointing to a template directory, and run the `gen-templates` method.
The templates `toc` and `index` may need tweaking for custom Table of Contents and Index (local index to the source) rendering.

### CSS, JS, Images

All the contents (files and recursively subdirectories) in a directory provided to the `:assets` option upon instantiation
will be copied to the subdirectory **output/assets/**, where **output** is the directory for the rendered files.

# Configuration

By default - that is without any configuration file(s) - a "landing page" index file, called **index.ext**, is generated
from the source cache with the documents
in the top directory of the cache listed by
TITLE, followed by the SUBTITLE, followed by the Table of Content for the cache file.
If the cache has subdirectories, then the name of the directory is made into a title, and the files under it are listed as above.

A separate file called **global-index.ext** is also generated by default containing
the indexed elements from all the pod-files in the cache.

These two files are rendered into html (by default), but if a different rendering has been specified, they will follow those rendering
templates.

If a `config` directory is provided, Render will look for `*.yaml` files and consider them customised index files.

The structure of the index file is documented in the default files (see below for generating default files). However, if **a customised rendered file**
is required, eg., a customised `index.html`, then the `index.yaml` file (where **index** could be any name) should contain the
single line `source: R.

The R should be the name of the file relative to the `Configuration` directory and it will be copied to the `Output`
directory.

Each configuration file will be converted from `name.yaml` to **name.ext** where **ext** is `html` by default, but could, eg,
be `md` if the rendering is to Markdown and templates are provided.

If there are sources in the document cache that are not included in customised `*.yaml` index files, then a `missing-sources.yaml`
configuration file will be generated and used to create an index file.

The indexation files are rendered using the templates `indexation-file` and `global-indexation-file`, respectively.
These templates can be over-ridden as required.

For more information, generate the default configuration files into the `config` directory (see below).

# Work Flow

The work flow to create a document collection might be:
- create the collection (which will generate default configuration files)
- remove creation errors (in pod sources)
- edit configuration files into more content oriented forms
- edit templates to customise content
- run method to ensure that config files contain all source names and no typos create an invalid source
- add customised css, js, and images
- when source files are edited run `update-collection` and check for errors using the `report`method
- eg
```
die 'errors found: ' ~ $renderer.report(:all).join("\n") if +$renderer.report(:errors);
```

# Utilities

## templates-changed

- Generates a list of template names that have been over-ridden.

## gen-templates

- 'templates/rendering' is interpreted as a directory, which must exist. All the mustache templates will be copied into it.

- Only the templates required may be kept. Some templates, such as `zero` do not need to be over-ridden as there is no rendering data.

## generate-config-files

- `:config` is a writable directory that must exist, defaults to `output`

- the two index files `index.yaml` and `global-index.yaml` are generated in that directory. The intent is to provide templates for customised config files. For more information generate a template.

- Care should be taken as any custom `index.yaml` or `global-index.yaml` files will be over-written by this method

- The index files themselves are generated using the `indexation-file`/`global-indexation-file` templates

- the extension of the final index files will be the same as `rendering`

- the filename of the index file will be same as the +.yaml files in the config directory

## test-config-files

- `config` is a directory that should contain the config files.

- if no `.yaml` files are in the config directory, the method will throw a Fatal Exception.

- each pod6 file will be read and the filenames from `- item` lines will be compared to the files in the doc-cache

- any file present in *the doc-cache*, but **not** included in *a config file* will be output into a config file called `missing-sources.yaml`

- any filename included in *a config file*, but **not** in *the doc-cache*, will be listed in a file called `error.txt`

## LICENSE

You can use and distribute this module under the terms of the The Artistic License 2.0. See the LICENSE file included in this distribution for complete details.