Marco Pessotto
and 1 contributors

# NAME

Text::Amuse::Compile::TemplateOptions - parse and validate options for templates

## SYNOPSIS

``````  use Text::Amuse::Compile::TemplateOptions;
my \$options = Text::Amuse::Compile::TemplateOptions->new(%options);
my \$doc = Text::Amuse->new(file => 'test.muse');
# and get the hashrefs for the tokens
my \$latex_options = \$options->as_latex(\$doc);``````

# ACCESSORS

The follow accessors are read-write. The same settings can be passed to the `muse-compile.pl` script.

## Paper

• papersize (common values: a4, a5, letter)

Paper size, like a4, a5 or 210mm:11in. The width and heigth are swapped in some komascript version. Just keep this in mind and do some trial and error if you need custom dimensions.

• bcor (binding correction for inner margins)

The BCOR of the `typearea` package. Defaults to 0mm. Go and read the doc. It expects a TeX dimension like 10mm or 1in or 1.2cm.

Please note that this has no effect on the plain PDF output when an imposed version is also required, because we force BCOR=0mm and oneside=true for the planin version in this case.

• division (the DIV factor for margin control)

The DIV of the `typearea` package. Defaults to 12. Go and read the doc. Sensible values are from 9 to 15. 15 has narrow margins, while in 9 they are pretty generous.

• areaset_width 3in

• areaset_height 50mm

Usually you want to use the DIV factor, but you can also set the type area manually specifying the dimensions. The dimensions can be in mm, cm, in and pt, separated by a colon.

• oneside (boolean)

This is the default. Actually, this option doesn't have any use.

• twoside (boolean)

Set it to a true value to have a twosided document. Default is false.

Please note that this has no effect on the plain PDF output when an imposed version is also required, because we force BCOR=0mm and oneside=true for the planin version in this case.

• opening

On which pages the chapters should open: right, left, any. Default: right. The left one will probably lead to unexpected results (the PDF will start with an empty page), so use it at your own peril.

## Fonts

• mainfont (grep fc-list -l for the correct name)

The system font name, such as `Linux Libertine O` or `Charis SIL`. This implementation uses XeLaTeX, so we can use system fonts. Defaults to `CMU Serif`.

• sansfont

The sans serif font to use. This option has some effects only on slides. Defaults to `CMU Sans Serif`

• monofont

The monospace font to use. Defaults to `CMU Typewriter Text`.

• fontsize

The size of the body font (9, 10, 11, 12) as integer, meaning points (pt), defaulting to 10.

## Colophon

• sitename

At the top of the page

• siteslogan

At the top, under sitename

• logo (filename)

At the top, under siteslogan

• site

At the bottom of the page

## Cover

• cover (filename for front cover)

When this option is set to a true value, skip the creation of the title page with \maketitle, and instead build a custome one, with the cover placed in the middle of the page.

The value can be an absolute path, or a bare filename, which can be found by `kpsewhich`. If the path is not valid and sane (from the LaTeX point of view: no spaces, no strange chars), the value is ignored.

With EPUB output, the cover is used in the title page.

• coverwidth (dimension ratio with the text width, eg. '0.85')

Option to control the cover width, when is set (ignored otherwise). Defaults to the full text width (i.e., 1). You have to pass a float here with the ratio to the text width, like `0.5`, `1`.

With EPUB output, this affects the maximum width, not the actual width.

• nocoverpage

Force the use of the LaTeX article class. If there are chapters present, consider them aliases for a section.

• ignore_cover

Ignore the cover unconditionally

• notoc

• nofinalpage

Do not produce the last page on the PDF with the author/title/notes/source/site name.

• impressum

Move the notes, which are usually in the last page at the bottom and centered, on the second page, raggedright, in smaller size.

• continuefootnotes

Normally the footnotes are reset at chapter. With this option turned on, they will not reset.

• centerchapter

Center the chapter title instead of ragged

• centersection

Center all the sectioning titles, including the chapters.

• sansfontsections

Use the default komascript style where chapters and parts have sans font.

• nobold

Prevent the use of bold fonts and replace them with italics.

• secondary_footnotes_alpha

By default, secondary footnotes use arabic numbering between parens. You can switch to alpha per-page setting this option to 1 (boolean).

• start_with_empty_page

Start the PDF with an empty page (not with the title page, which will be placed on the next recto page).

Generate the running headings in the document. Beware that this will get you overfull headings if you have long titles.

The behaviour changes if it's a oneside document.

Available values:

• title_subtitle

Title on the left page, subtitle on right page. Oneside: title.

• author_title

Author on the left, title on the right. Oneside: title

• section_subsection

Section on the left, subsection on the right. Oneside: section name

• chapter_section

Chapter on the left, section on the right. Oneside: chapter name

• title_section

Title on the left, section on the right. Oneside: section name

• title_chapter

Title on the left, chapter on the right. Oneside: chapter name

## Slides

• beamertheme

The theme to use with beamer, if and when the slides are produced. See the beamer manual or https://www.hartwork.org/beamer-theme-matrix/. Defaults to the default one.

• beamercolortheme

Same as above, but for the color theme. Defaults to "dove" (b/w theme, can't see the default purple).

• tex_tolerance

An integer between 0 and 10000

Quoting: a parameter that tells TeX how much badness is allowable without error. Default to 200.

\tolerance sets the maximum "badness" that tex is allowed to use while setting the paragraph, that is it inserts breakpoints allowing white space to stretch and penalties to be taken, so long as the badness keeps below this threshold. If it can not do that then you get overfull boxes. So different values produce different typeset result.

• tex_emergencystretch

Default to 30pt. It can be a TeX measure (I guess pt is what makes most sense for our use)

\emergencystretch (added at TeX3) is used if TeX can not set the paragraph below the \tolerance badness, but rather than make overfull boxes it tries an extra pass "pretending" that every line has an additional \emergencystretch of stretchable glue, this allows the overall badness to be kept below 1000 and stops TeX "giving up" and putting all stretch into one line. So \emergencystretch does not change the setting of "good" paragraphs, it only changes the setting of paragraphs that would have produced over-full boxes. Note that you get warnings about the real badness calculation from TeX even though it retries with \emergencystretch the extra stretch is used to control the typesetting but it is not considered as good for the purposes of logging.

• fussy_last_word

Avoid breking the last word of a paragraph. This sounds great, but if you have short paragraphs (say, on line, or the text is full of dialogs), this is going to be a big problem, generating really bad lines.

• format_id

This does nothing per se but makes `safe_options.format_id.\$name` accessible in the template.

This is useful if you have a local latex.tt template which needs to do different things with different formats, so you can call:

``````  [% IF safe_options.format_id.c999 %]
Output 1
[% ELSE %]
Output 2
[% END %]``````

If not specified, `DEFAULT` is set.

The value must begin with a letter and have only letters, digits and underscores.

# METHODS

## paging

This merges `oneside` and `twoside`. If both or none are set, defaults to `oneside`.

## tex_papersize

The real name of the papersize, unaliased (so, e.g. `half-a4` will be `a5`).

## config_setters

The list of the values which should be passed to the constructor

## config_output

Return a validated hashref of the options. This is basically the purpose of this module.

## Available fonts listing

They return a list of hashrefs, with two keys, `name` and `desc`. The first is the system font name, the second is the description. They can be called on the class.

sans_fonts
mono_fonts
serif_fonts
all_fonts
all_fontsizes

## Themes listing

The following methods can be called on the class and return lists with the available Beamer themes and color themes:

beamer_colorthemes
beamer_themes

Return a list of hashrefs with `name` and `desc`. Legacy options have an empty description.

## Defaults fonts and themes

default_mainfont
default_sansfont
default_monofont
default_beamertheme
default_beamercolortheme

## Help

### show_options

Print out the relevant stanza of the POD.

# INTERNALS

## check_filename(\$filename)

Return true if the path is absolute (and looks like a pdf/jpg/png file) or if it's a bare filename, even without extension.