/ 
Text-Amuse-Compile-1.33
River stage zero No dependents
/ Text::Amuse::Compile

NAME

Text::Amuse::Compile - Compiler for Text::Amuse

VERSION

Version 1.33

SYNOPSIS

use Text::Amuse::Compile;
my $compiler = Text::Amuse::Compile->new;
$compiler->compile($file1, $file2, $file3)

METHODS/ACCESSORS

CONSTRUCTOR

new(ttdir => '.', pdf => 1, ...);

Constructor. It will accept the following options

Format options (by default all of them are activated);

cleanup

Remove auxiliary files after compilation (.status)

webfontsdir

If you want to embed fonts in the EPUB, pass the directory with the fonts and the specification file (see Text::Amuse::Compile::Webfonts) in this option.

fontspec

Argument for Text::Amuse::Compile::Fonts constructor. Passing these triggers a new way to select fonts. The validation happens against a list of font you can provide and you don't need the Webfonts mess above.

epub_embed_fonts

Boolean (default to true) which triggers the epub font embedding.

luatex

Use lualatex instead of xelatex.

tex

LaTeX output. Compatible with xelatex and lualatex (see below for the packages needed).

pdf

Plain PDF without any imposition.

a4_pdf

PDF imposed on A4 paper

lt_pdf

PDF imposed on Letter paper

html

Full HTML output

epub

The EPUB

bare_html

The bare HTML, non <head>

zip

The zipped sources

sl_tex

The Beamer LaTeX output, if the muse headers say so.

sl_pdf

The Beamer PDF output, if the muse headers say so.

If the header has a #slides header with some value (e.g., 1, yes, ok, whatever) and if there some sectioning, create a pdf presentation out of it.

E.g., the following will not produce slides:

#title Foo
#slides

But this would

#title Foo
#slides 1

The value of the header is totally insignificant, as long is not false or no or 0 or empty, which disable them.

Sections which contain the comment ; noslide are ignored. LaTeX source is left in the tree with .sl.tex extension, and the output will have .sl.pdf extension.

slides

Alias for sl_pdf.

selected_font_main

The selected main font (from the extra hashref)

selected_font_sans

The selected sans font (from the extra hashref)

selected_font_mono

The selected mono font (from the extra hashref)

selected_font_size

The selected font size (from the extra hashref)

extra_opts

An hashref of key/value pairs to pass to each template in the options namespace. This is internal

coverpage_only_if_toc

Generate a cover page only if there is a ToC in the document.

When compiling a virtual file (a collection) the option is ignored, because Text::Amuse::Compile::Merged wants_toc always returns true.

extra

In the constructor arguments, a shallow copy will be stored in extra_opts. Using it as an accessor will return an hash with the copy of extra_opts

standalone

Do not force bcor=0 and oneside for plain tex and pdf

Template directory:

ttdir

The directory where to look for templates, named as format.tt

You can retrieve the value by calling them on the object.

available_methods

Return a list of all the available compilation methods

compile_methods

Return the list of the methods which are going to be used.

BUILDARGS routine

The extra key is passed instead to extra_opts. Directories are made absolute. If no formats are required explicitely, set them all to true.

METHODS

webfonts

The Text::Amuse::Compile::Webfonts object, constructed from the the webfontsdir option.

fonts

The Text::Amuse::Compile::Fonts::Selected object, constructed from the fontspec argument and eventual extra font keys passed.

version

Report version information

logger($sub)

Accessor/setter for the subroutine which will handle the logging. Defaults to printing to the standard output.

recursive_compile($directory)

Compile recursive a directory, comparing the timestamps of the status file with the muse file. If the status file is newer, the file is ignored.

Return a list of absolute path to the files processed. To infer the success or the failure of each file look at the status file or at the logs.

find_muse_files($directory)

Return a sorted list of files with extension .muse excluding illegal names (including hidden files and directories).

find_new_muse_files($directory)

As above, but check the age of the status file and skip already processed files.

compile($file1, $file2, ...);

Main method to get the job done, passing the list of muse files. You can inspect the errors calling errors. It does produce some output.

The file may also be an hash reference. In this case, the compile will act on a list of files and will merge them. Beware that so far only the pdf and tex options will work, while the other html methods will throw exceptions or (worse probably) produce empty files. This will be fixed soon. This feature is marked as experimental and could change in the future.

virtual file hashref

The hash reference should have those mandatory fields:

files

An arrayref of filenames without extension.

path

A mandatory directory where to find the above files.

Optional keys

name

Default to virtual. This is the basename of the files which will be produced. It's up to you to provide a sensible name we don't do any check on that.

suffix

Defaults to '.muse' and you have no reason to change this.

Every other key is the metadata of the new document, so usually you want to set title and optionally author.

Example:

$c->compile({
             # mandatory
             path  => File::Spec->catdir(qw/t merged-dir/),
             files => [qw/first second/],

             # recommended
             name  => 'my-new-test',
             title => 'My new shiny test',

             # optional
             subtitle => 'Another one',
             date => 'Today!',
             source => 'Text::Amuse::Compile',
            });

You can pass as many hashref you want.

file_needs_compilation

Returns true if the file has already been compiled, false if some output file is missing or stale.

parse_muse_header($file)

Return a Text::Amuse::Compile::MuseHeader object for the given file.

purge(@files)

Remove all the files produced by the compilation of the files passed as arguments.

report_failure_sub(sub { push @problems, $_[0] });

You can set the sub to be used to report problems using this accessor. It will receive as first argument the file which led to failure.

The actual errors are logged by the logger sub.

errors

Accessor to the catched errors. It returns a list of strings.

add_errors($error1, $error2,...)

Add an error. [Internal]

reset_errors

Reset the errors

has_errors

Return the number of errors (handy to use as a boolean).

TeX live packages needed.

You need the xetex scheme plus the following packages: fontspec, polyglossia, pzdr, wrapfig, footmisc, ulem, microtype, zapfding.

For the luatex options, same as above plus luatex (and the lualatex format), luatexbase, luaotfload.

The luatex option could give better microtypography results but is slower (x4) and requires more memory (x2).

AUTHOR

Marco Pessotto, <melmothx at gmail.com>

BUGS

Please mail the author and provide a minimal example to add to the test suite.

SUPPORT

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

perldoc Text::Amuse::Compile

LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.