/ 
Papery-0.01
River stage zero No dependents
/ Papery

NAME

Papery - The thin layer between what you write and what you publish

SYNOPSIS

Below is a significant excerpt of the papery command-line tool:

use Papery;

# generate the site
Papery->new( @ARGV )->generate();

DESCRIPTION

Papery is meant to be a very thin layer between a number of Perl modules that you can use to generate the files of a static web site.

It is intended to make it very flexible, so that it's easy to add hooks and specialized modules to generate any file that is needed for the site.

Workflow

Papery processes entire directory trees containing files and templates, and for each file that is not ignored, it will run the follwing steps:

analysis

splits the file between "metadata" and "text", and creates one or more objects encapsulating those (everything is basically a hash, and the text is just some special metadata)

processing

turns the "text" into "content" by parsing it with a given processor. For example Papery::Processor::Pod::POM uses Pod::POM to turn POD text into HTML.

rendering

turns the "content" into "output", by processing it through a templating engine. For example, Papery::Renderer::Template will use Template Toolkit to process the main template and produce the target file.

Each step takes a Papery::Pulp object, which is basically a hash of metadata. Each step can return more than one Papery::Pulp object. After the rendering step, each Papery::Pulp object is saved to a file.

Metadata

Initial meta information comes from the global configuration (top-level _config.yml file). It is then updated from the _meta.yml file in the current directory.

Furthermore, each file can contain metadata for itself, using "YAML Front Matter":

---
# this is actually YAML
title: Page title
---
This is the actual content

The metadata comes in three kinds:

  • variables prefixed with a double underscore (__) are internal to Papery and set by Papery. They cannot be overwritten by any of _config.yml, _meta.yml or the YAML front matter

  • variables prefixed with a single underscore (_) are reserved for Papery, and can be overridden by any of _config.yml, _meta.yml or the YAML front matter

  • all the other variables are free to use by the web site itself.

Papery internal / reserved variables

The metadata variables recognized by Papery are:

__source

The top-level source directory for the site

__destination

The top-level destination directory for the site

_analyer

The Papery::Analyzer subclass that will be used to analyze the source file.

_processors

A hash of extentions to Papery::Processor classes

_processor

The Papery::Processor subclass that will be used to process text and generate the content.

_renderer

The Papery::Renderer subclass that will be used to render the content and create the output

_text

The text resulting from the analysis step.

_content

The content resulting from the processing step.

_output

The output resulting from the rendering step.

_permalink

The final destination for the output. The filename is relative to __destination.

Some of the analyzers, processors and renderers may also define their own variables.

METHODS

Papery supports the following methods:

new( $src, $dst )

Create a new Papery object, with the provided source and destination directories.

generate()

Process all the files in the source directory and generate the resulting files in the destination directory.

process_tree( $dir )

Process the $dir tree.

$dir is relative to the source directory.

process_file( $file )

Process the $file file, to generate one or more target files.

$file is relative to the source directory.

AUTHOR

Philippe Bruhat (BooK), <book at cpan.org>

ACKNOWLEDGEMENTS

Much of the inspiration for this module comes from Jekyll (http://jekyllrb.com/) and Template Toolkit's ttree (http://www.template-toolkit.org/>).

While my initial goal was to be able to write a web site in POD, I realized that any format can be turned into HTML and no limitation on the source format should be imposed on the people. Same goes for the templating engine. My plan is to make this flexible enough (using hooks) that one can extend it easily to build any kind of website.

BUGS

Please report any bugs or feature requests to bug-papery at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Papery. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

TODO

Here's a list of some of the things ahead:

  • post_(analyze|process|render) hooks

  • post_site hooks (for all those files we need to generate after the whole site has been generated)

  • file copy

  • not rebuilding files that don't need to be rebuilt

  • dependencies

  • support for local _lib and _hooks directories

  • more analyzers (e.g. Papery::Analyzer::Multiple) =item *

    more processors (e.g. Text::Markdown)

  • more renderers (e.g. Text::Template

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Papery

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT

Copyright 2010 Philippe Bruhat (BooK), all rights reserved.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.