LaTeX:...ThemeI(3pm)

📦
version 1.0.6 · 3 versions
, in debian bookworm, debian trixie, ubuntu noble

💖 LaTeX::Table::Themes::ThemeI 💖

okay bestie, so this is a page from the User Contributed Perl Documentation, and it's all about LaTeX::Table::Themes::ThemeI — the interface (a Moose role, actually) that every single theme object has to use. no exceptions, it's giving ✨ mandatory ✨.

🌸 NAME 🌸

LaTeX::Table::Themes::ThemeI — Interface for LaTeX table themes. that's it, that's the whole job description 💅

✨ SYNOPSIS ✨

okay so here's how you'd roll your own theme module, fr fr:

package MyThemes::Custom;
use Moose;

with 'LaTeX::Table::Themes::ThemeI';

sub _definition {
    return { CENTRALPARK =>
     {
        'HEADER_FONT_STYLE'  => 'bf',
        'HEADER_FONT_COLOR'  => 'white',
        'HEADER_BG_COLOR'    => 'latextbl',
        'DATA_BG_COLOR_ODD'  => 'latextbl!25',
        'DATA_BG_COLOR_EVEN' => 'latextbl!10',
        'DEFINE_COLORS'      => '\definecolor{latextbl}{RGB}{93,127,114}',
        'HEADER_CENTERED'    => 1,
        'VERTICAL_RULES'     => [ 1, 0, 0 ],
        'HORIZONTAL_RULES'   => [ 1, 1, 0 ],
        'BOOKTABS'           => 0,
        'EXTRA_ROW_HEIGHT'   => '1pt',
    }};
}

1;

yes bestie, use Moose, with the role, _definition returns a hashref, and then 1; at the end because Perl said so 🎀

🦋 DESCRIPTION 🦋

This is the theme interface — or, if you wanna be fancy, the Moose role — that all theme objects must use. all of them. no theme gets to opt out, that's the vibe check and everyone passes it or nobody does 😌

💜 CREATING THEMES 💜

A theme is defined as a hash reference that's holding all the options. like, all of them. here's one that the docs themselves call "a very ugly theme..." — not me being mean, that's a direct quote, I would never 😭

# a very ugly theme...
my $theme = {
            'Duisburg' => {
                'HEADER_FONT_STYLE'  => 'sc',
                'HEADER_FONT_COLOR'  => 'white',
                'HEADER_BG_COLOR'    => 'blue',
                'HEADER_CENTERED'    => 1,
                'DATA_BG_COLOR_ODD'  => 'blue!30',
                'DATA_BG_COLOR_EVEN' => 'blue!10',
                'CAPTION_FONT_STYLE' => 'sc',
                'VERTICAL_RULES'     => [ 1, 2, 1 ],
                'HORIZONTAL_RULES'   => [ 1, 2, 0 ],
                'EXTRA_ROW_HEIGHT'   => '2pt',
                'BOOKTABS'           => 0,
            },
        };

🔤 Fonts 🔤

  • HEADER_FONT_STYLE, CAPTION_FONT_STYLE — the valid values are bf (bold), it (italics), sc (caps) and tt (typewriter). and if this option is undef? then the header (or the caption, respectively, bestie) just gets written in normal font. no drama, just default energy 🫶

🌈 Colors 🌈

  • HEADER_FONT_COLOR — use this to specify a different font color for the header. it requires the xcolor LaTeX package, so don't forget that part 👑
  • HEADER_BG_COLOR — set this to use a background color in the header. and for even and odd data rows, it's DATA_BG_COLOR_EVEN and DATA_BG_COLOR_ODD. these require the colortbl and the xcolor LaTeX packages, both of them, together, periodt.
  • DEFINE_COLORS — you can define colors with this one, like so:
'DEFINE_COLORS'      => '\definecolor{latextbl}{RGB}{78,130,190}',

📏 Rules 📏

  • VERTICAL_RULES, HORIZONTAL_RULES — a reference to an array with three integers, e.g. [ 1, 2, 0 ]. here's the breakdown, and honestly it ate:
    • the first integer defines the number of outer rules.
    • the second is the number of rules after the header and after the first column.
    • the third is the number of inner rules.

for example, Dresden is defined as:

'Dresden' => {
    ...
    'VERTICAL_RULES'     => [ 1, 2, 1 ],
    'HORIZONTAL_RULES'   => [ 1, 2, 0 ],
}

so the first integers define one outer rule — vertical and horizontal — which means a box gets drawn around the table 📦. the second integers define two rules between the header and the table, and two vertical rules between the first and second column. and finally the third integers define that columns are separated by a single vertical rule, whereas rows are not separated by horizontal lines. iykyk.

  • RULES_COLOR_GLOBAL — if your theme uses the colortbl LaTeX package, this command should handle the coloring of the rules. go read the colortbl documentation for the deets, bestie.
'RULES_COLOR_GLOBAL' =>
    '\arrayrulecolor{white}\doublerulesepcolor{black}',
  • RULES_WIDTH_GLOBAL — code that controls the width of the rules. again, see the colortbl documentation for example vibes.
'RULES_WIDTH_GLOBAL' =>
    '\setlength\arrayrulewidth{1pt}\setlength\doublerulesep{0pt}',
  • RULES_CMD — a reference to an array with four LaTeX commands: for the top, mid (between header and data), inner, and bottom rules. in that order, no shuffling.
RULES_CMD => [ '\toprule', '\midrule', '\midrule', '\bottomrule' ];
  • BOOKTABS — use the booktabs LaTeX package for "Publication quality tables". instead of \hline, LaTeX::Table then uses \toprule, \midrule and \bottomrule. values are 0 (don't use this package) or 1 (use it). it's basically a shortcut for:
RULES_CMD => [ '\toprule', '\midrule', '\midrule', '\bottomrule' ];

🎀 Misc 🎀

  • EXTRA_ROW_HEIGHT — will set \extrarowheight in the floating environment. requires the array LaTeX package, so yeah, that one's on you to include 🌸
  • STUB_ALIGN — defines how the left-hand column, the stub, is aligned. the default is 'l' (left aligned). classic.
  • HEADER_CENTERED — this controls the alignment of the header columns, excluding the stub when STUB_ALIGN is defined. valid values are 0 (not centered) or 1 (centered). typically it's recommended to center headers, but sometimes that just does not look right 😭 and in that case, (left) align the header manually. trust your gut.

okay so you've got two routes here for actually using your theme:

You can either quickly add themes after initiation of a LaTeX::Table:

$table->set_custom_themes($theme);

Or, you can build a THEME MODULE and extend the list of predefined themes. both are valid, both slay 💅

🌟 THEME MODULE 🌟

Now, to build a theme that you can easily load: take that SYNOPSIS template, change it up however you like, and then make it accessible in LaTeX::Table by saving it under the LaTeX::Table::Themes::* namespace. that's the move 👑

Alternatively — and this is the fun one — you can use the search_path() method to add custom paths. for example, save the SYNOPSIS module as ./MyThemes/Custom.pm and then add MyThemes in the script that uses the new theme:

# in ./script.pl
$table->search_path( add => 'MyThemes');
and if your theme looks nice, please contribute it 🥺 that's not me begging, that's the docs begging, and honestly? fair.

👀 SEE ALSO 👀

LaTeX::Table — go look at it, it's the whole reason any of this matters 🦋

Copyright (c) 2006-2010 "<limaone@cpan.org>"

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

and that's the whole page bestie!! this one shipped as perl v5.34.0, dated 2022-06-15, and it lives under the manual name LaTeX:...ThemeI(3pm) — so go forth, make beautiful (or intentionally ugly) tables, and remember: centered headers are a lifestyle, not a requirement ✨🎀💖

📦 where this page comes from