/ 
Text-Amuse-Compile-1.90
River stage zero No dependents
/ Text::Amuse::Compile::TemplateOptions

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 text block dimensions. The dimensions can be in mm, cm, in and pt.

    Both need to be set to have an effect.

  • geometry_top_margin 1in

  • geometry_outer_margin 1in

    Usually you want to use the DIV factor, but you can also set the type area manually specifying the top and outer margins. The dimensions can be in mm, cm, in and pt.

    You also need to set areaset_width and areaset_height to use these custom margins (inner and bottom margins are calculated using the text block dimensions).

  • 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.

  • body_only

    Skip title, cover pages and final pages. Just produce the body.

  • 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

    Do not generate a table of contents, even if the document requires one.

  • 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).

  • linespacing (float, tipically 1.5 or 2)

    Set the linespacing instead of the default value.

  • parindent (integer)

    Paragraph indentation in points (pt).

  • headings

    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).

Advanced

  • 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.

    See https://tex.stackexchange.com/questions/241343/what-is-the-meaning-of-fussy-sloppy-emergencystretch-tolerance-hbadness for reference.

  • 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

Headings style listing

all_headings

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.