bookml.sty.ltxml

# -*- mode: Perl -*-
# vim: syntax=perl

=begin comment

  BookML: bookdown flavoured GitBook port for LaTeXML
  Copyright (C) 2021-23  Vincenzo Mantova <v.l.mantova@leeds.ac.uk>

  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.

=end comment

=cut

package LaTeXML::Package::Pool;
use strict;
use warnings;

use LaTeXML::Common::Color;
use LaTeXML::Package;
use LaTeXML::Util::Pathname;

use File::Find;
use File::Spec;
use File::Which;
use IPC::Open3;
use XML::LibXML;
use DB_File;

my $bmlVersion = '@VERSION@';

my ($bml_ProgressSpinup, $bml_ProgressSpindown, $bml_ProgressStep, $bml_Note, $bml_NoteLog, $bml_NoteSTDERR);

if (!defined &ProgressSpinup) {
  # pre-0.8.6 reporting
  $bml_ProgressSpinup   = \&NoteBegin;
  $bml_ProgressSpindown = \&NoteEnd;
  $bml_ProgressStep     = sub { my $text = shift; if (defined $text) { \&NoteProgress("\n$text"); } };
  $bml_Note             = sub { my $text = shift; if (defined $text) { \&NoteProgress("\n$text"); } };
  $bml_NoteLog = sub { my $text = shift; if (defined $text) { \&NoteProgressDetailed("\n$text"); } };
  $bml_NoteSTDERR = sub { };
} else {
  $bml_ProgressSpinup   = \&ProgressSpinup;
  $bml_ProgressSpindown = \&ProgressSpindown;
  $bml_ProgressStep     = \&ProgressStep;
  $bml_Note             = \&Note;
  $bml_NoteLog          = \&NoteLog;
  $bml_NoteSTDERR       = \&NoteSTDERR;
}

# Helper function to add resources at the *end* of head or body
# Partly copied from RequireResource
my $bml_resource_options = {
  type => 1, location => 1, content => 1, name => 1 };
my $bml_resource_types = {
  css  => 'text/css',
  js   => 'text/javascript',
  ttf  => 'font/ttf',
  pdf  => 'application/pdf',
  epub => 'application/epub+zip'
};

sub BMLRequireResource {
  my ($resource, %options) = @_;
  CheckOptions('BMLRequireResource', $bml_resource_options, %options);

  if (!$options{content} && !$resource) {
    Warn('expected', 'resource', undef, 'Resource must have a resource pathname or content; skipping');
    return; }

  if (!$options{location}) {
    $options{location} = 'head'; }

  if (!$options{type}) {
    my $ext = $resource && pathname_type($resource);
    $options{type} = $ext && $$bml_resource_types{$ext}; }
  if (!$options{type}) {
    Warn('expected', 'type', undef, 'Resource must have a mime-type; skipping');
    return; }
  $options{type} .= ';bmllocation=' . $options{location};
  if ($options{name}) {
    $options{type} .= ';bmlname=' . $options{name}; }

  delete $options{location};
  delete $options{name};
  return RequireResource($resource, %options);
}

my $bml_style      = 'gitbook';
my $bml_imagescale = 1;
my $bml_jobname    = ToString(Expand(T_CS('\jobname')));
my $bml_htmlsyn    = 1;
my @bml_download   = ();

for my $ext ('pdf', 'epub') {
  if (-f "$bml_jobname.$ext") {
    Info('found', $ext, undef, "bundling '$bml_jobname.$ext' in the output");
    push(@bml_download, "$bml_jobname.$ext"); }
}

DeclareOption('style=plain',   sub { $bml_style   = 'plain';   return; });
DeclareOption('style=gitbook', sub { $bml_style   = 'gitbook'; return; });
DeclareOption('style=none',    sub { $bml_style   = 'none';    return; });
DeclareOption('htmlsyntax',    sub { $bml_htmlsyn = 1;         return; });
DeclareOption('nohtmlsyntax',  sub { $bml_htmlsyn = 0;         return; });
DeclareOption('mathjax=2');
DeclareOption('nomathjax');

# LaTeXML currently does not support the class options 10pt, 11pt, etc so we have to do the work ourselves
my %bml_font_sizes = (
  # article
  'size10.clo' => {
    normalsize   => [10,    12],
    small        => [9,     11],
    footnotesize => [8,     9.5],
    scriptsize   => [7,     8],
    tiny         => [5,     6],
    large        => [12,    14],
    Large        => [14.4,  18],
    LARGE        => [17.28, 22],
    huge         => [20.74, 25],
    Huge         => [24.88, 30]
  },
  'size11.clo' => {
    normalsize   => [10.95, 13.6],
    small        => [10,    12],
    footnotesize => [9,     11],
    scriptsize   => [8,     9.5],
    tiny         => [6,     7],
    large        => [12,    14],
    Large        => [14.4,  18],
    LARGE        => [17.28, 22],
    huge         => [20.74, 25],
    Huge         => [24.88, 30]
  },
  'size12.clo' => {
    normalsize   => [12,    14.5],
    small        => [10.95, 13.6],
    footnotesize => [10,    12],
    scriptsize   => [8,     9.5],
    tiny         => [6,     7],
    large        => [14.4,  18],
    Large        => [17.28, 22],
    LARGE        => [20.74, 25],
    huge         => [24.88, 30],
    Huge         => [24.88, 30]
  },
  # book, amsdtx, amsldoc
  'bk10.clo' => {
    normalsize   => [10,    12],
    small        => [9,     11],
    footnotesize => [8,     9.5],
    scriptsize   => [7,     8],
    tiny         => [5,     6],
    large        => [12,    14],
    Large        => [14.4,  18],
    LARGE        => [17.28, 22],
    huge         => [20.74, 25],
    Huge         => [24.88, 30]
  },
  'bk11.clo' => {
    normalsize   => [10.95, 13.6],
    small        => [10,    12],
    footnotesize => [9,     11],
    scriptsize   => [8,     9.5],
    tiny         => [6,     7],
    large        => [12,    14],
    Large        => [14.4,  18],
    LARGE        => [17.28, 22],
    huge         => [20.74, 25],
    Huge         => [24.88, 30]
  },
  'bk12.clo' => {
    normalsize   => [12,    14.5],
    small        => [10.95, 13.6],
    footnotesize => [10,    12],
    scriptsize   => [8,     9.5],
    tiny         => [6,     7],
    large        => [14.4,  18],
    Large        => [17.28, 22],
    LARGE        => [20.74, 25],
    huge         => [24.88, 30],
    Huge         => [24.88, 30]
  },
  # amsart, amsbook, amsproc
  'amscls10.clo' => {
    Tiny         => [5,     6],
    tiny         => [6,     7],
    scriptsize   => [7,     8],
    footnotesize => [8,     10],
    small        => [9,     11],
    normalsize   => [10,    12],
    large        => [10.95, 13],
    Large        => [12,    14],
    LARGE        => [14.4,  17],
    huge         => [17.28, 20],
    Huge         => [20.74, 24]
  },
  'amscls11.clo' => {
    Tiny         => [6,     7],
    tiny         => [7,     8],
    scriptsize   => [8,     10],
    footnotesize => [9,     11],
    small        => [10,    12],
    normalsize   => [10.95, 13],
    large        => [12,    14],
    Large        => [14.4,  17],
    LARGE        => [17.28, 20],
    huge         => [20.74, 24],
    Huge         => [24.88, 30]
  },
  'amscls12.clo' => {
    Tiny         => [7,     8],
    tiny         => [8,     10],
    scriptsize   => [9,     11],
    footnotesize => [10,    12],
    small        => [10.95, 13],
    normalsize   => [12,    14],
    large        => [14.4,  17],
    Large        => [17.28, 20],
    LARGE        => [20.74, 24],
    huge         => [24.88, 30],
    Huge         => [24.88, 30]
  },
  'amscls8.clo' => {
    Tiny         => [5,     6],
    tiny         => [5,     6],
    scriptsize   => [5,     6],
    footnotesize => [6,     7],
    small        => [7,     8],
    normalsize   => [8,     10],
    large        => [9,     11],
    Large        => [10,    12],
    LARGE        => [10.95, 13],
    huge         => [12,    14],
    Huge         => [14.4,  17]
  },
  'amscls9.clo' => {
    Tiny         => [5,     6],
    tiny         => [5,     6],
    scriptsize   => [6,     7],
    footnotesize => [7,     8],
    small        => [8,     10],
    normalsize   => [9,     11],
    large        => [10,    12],
    Large        => [10.95, 13],
    LARGE        => [12,    14],
    huge         => [14.4,  17],
    Huge         => [17.28, 20]
  },
  # aa
  'aa10.clo' => {
    normalsize   => [10,    11],
    small        => [9,     10],
    scriptsize   => [7,     8],
    tiny         => [8,     9],
    large        => [10.95, 13],
    Large        => [14.4,  16],
    LARGE        => [17.28, 20],
    huge         => [20.74, 24],
    Huge         => [24.88, 30],
    footnotesize => [9,     10]
  },
  'aa11.clo' => {
    normalsize   => [10.95, 13.6],
    small        => [10,    12],
    scriptsize   => [8,     9.5],
    tiny         => [6,     7],
    large        => [12,    14],
    Large        => [14.4,  18],
    LARGE        => [17.28, 22],
    huge         => [20.74, 25],
    Huge         => [24.88, 30],
    footnotesize => [10,    12]
  },
  'a12.clo' => {
    normalsize   => [12,    14.5],
    small        => [10.95, 13.6],
    scriptsize   => [8,     9.5],
    tiny         => [6,     7],
    large        => [14.4,  18],
    Large        => [17.28, 22],
    LARGE        => [20.74, 25],
    huge         => [24.88, 30],
    Huge         => [24.88, 30],
    footnotesize => [10.95, 13.6]
  },
);

for my $pt (5 .. 28) {
  DeclareOption($pt . 'pt', sub {
      AssignValue('BML_PT_SIZE', $pt);
      return;
  });
}

AtBeginDocument(sub {
    my ($stomach) = @_;

    my $sizes = undef;
    my $pt    = LookupValue('BML_PT_SIZE');

    if (!$pt) {
      # default
      $pt = 10;
      # re-check the class options, in case bookml has been loaded before \documentclass
      for my $opt (grep(/^\d+pt$/, @{ LookupValue('class_options') || [] })) {
        $pt = $opt =~ s/pt//r;
        last; }
      AssignValue('BML_PT_SIZE', $pt);
    }

    for my $class ('aa') {
      if (LookupValue($class . '.cls.ltxml_loaded') || LookupValue($class . '.cls_loaded')) {
        $sizes = $bml_font_sizes{"$class$pt.clo"}; } }

    for my $class ('amsart', 'amsbook', 'amsproc', 'IEEEtran') {
      if (LookupValue($class . '.cls.ltxml_loaded') || LookupValue($class . '.cls_loaded')) {
        $sizes = $bml_font_sizes{"amscls$pt.clo"}; } }

    for my $class ('elsart') {
      if (LookupValue($class . '.cls.ltxml_loaded') || LookupValue($class . '.cls_loaded')) {
        return unless 10 <= $pt && $pt <= 12;
        $sizes = $bml_font_sizes{"size10.clo"}; } }

    for my $class ('article', 'report') {
      if (LookupValue($class . '.cls.ltxml_loaded') || LookupValue($class . '.cls_loaded')) {
        $sizes = $bml_font_sizes{"size$pt.clo"}; } }

    for my $class ('book') {
      if (LookupValue($class . '.cls.ltxml_loaded') || LookupValue($class . '.cls_loaded')) {
        $sizes = $bml_font_sizes{"bk$pt.clo"}; } }

    # LaTeXML makes \baselinestretch a register with value 0, but it should be a macro with value 1
    my $defn;
    if (($defn = LookupDefinition(T_CS('\baselinestretch'))) && $defn->isRegister) {
      DefMacroI('\baselinestretch', undef, 1); }

    if ($sizes) {
      # LaTeXML defines \baselinestretch as a register containing 0
      # in LaTeX it is actually the macro 1
      for my $name (keys %{$sizes}) {
        my ($size, $skip) = @{ $sizes->{$name} };
        # mimic the internal \@setfontsize
        DefPrimitiveI("\\$name", undef, sub {
            my ($stomach) = @_;
            my $stretched = $skip * ToString(Expand(T_CS('\baselinestretch')));
            $stretched = Glue("${stretched}pt");
            AssignRegister('\normalbaselineskip' => $stretched);
            AssignRegister('\baselineskip'       => $stretched);
            RawTeX('\normalbaselineskip\baselineskip');
            return;
        }, font => { size => $size });
      }

      # mimic running \normalsize in the preamble (hence scope 'global')
      my ($normalsize, $skip) = @{ $sizes->{normalsize} };
      my $stretched = $skip * ToString(Expand(T_CS('\baselinestretch')));
      $stretched = Glue("${stretched}pt");
      AssignRegister('\normalbaselineskip' => $stretched, 'global');
      AssignRegister('\baselineskip'       => $stretched, 'global');
      # configure LaTeXML font size
      AssignValue(NOMINAL_FONT_SIZE => $normalsize, 'global');

      # save the pt font size in the output, for later use in CSS
      return Tokens(T_CS('\lx@save@parameter'), T_OTHER('bml-font-size'), T_OTHER($normalsize), T_CS('\normalsize'));
    } else {
      Error('unexpected', $pt . 'pt', undef, "BookML does not know how the current class handles the point size '${pt}pt'"); }

    return;
});

DeclareOption(undef, sub {
    my ($stomach) = @_;
    my $opt = ToString(Expand(T_CS('\CurrentOption')));
    if ($opt =~ m/^imagescale\s*=\s*(.*)$/) {
      Warn('deprecated', 'imagescale', $stomach, 'the option imagescale is deprecated and may be ignored in future releases');
      my $val = $1;
      if ($val =~ m/^(?:\d+|\d*\.\d+)$/) {
        $bml_imagescale = $val; }
      else {
        Error('malformed', $opt, $stomach, "Value '$val' of imagescale= for bookml.sty must be a decimal number"); } }
    else {
      Error('unexpected', $opt, $stomach, "Unexpected option '$opt' passed to bookml.sty"); }
    return;
});

ProcessOptions();

DefMacroI('\BookMLversion', undef, $bmlVersion);

RequirePackage('latexml', options => ['nocomments', 'noguesstabularheaders']);

if ($bml_style eq 'gitbook') {
  # anywhere in the head
  for my $res (qw(
    bookml/gitbook/css/style.css
    bookml/gitbook/css/plugin-table.css
    bookml/gitbook/css/plugin-search.css
    bookml/gitbook/css/plugin-bookdown.css
    bookml/gitbook/css/plugin-fontsettings.css
    )
  ) { RequireResource($res); }

  # end of body
  for my $res (qw(
    bookml/gitbook/js/app.min.js
    bookml/gitbook/js/jquery.highlight.js
    bookml/gitbook/js/plugin-search.js
    bookml/gitbook/js/plugin-fontsettings.js
    bookml/gitbook/js/plugin-bookdown.js
  )) { BMLRequireResource($res, location => 'body'); }

  # additional files to be copied over
  RequireResource('bookml/gitbook/css/fontawesome/fontawesome-webfont.ttf', type => 'font/ttf');
}

# CSS files
DefConstructorI('\bml@css', undef, sub {
    my ($document) = @_;
    File::Find::find({
        preprocess => sub { sort @_; },
        no_chdir   => 1,
        wanted     => sub {
          if (-f $_ && m/\.css$/i) {
            my $styles = ',_all,';
            if ($_ =~ /\.([^.]+)\.css$/i) {
              $styles = ",$1,"; }
            if ($styles =~ /,(?:_all|\Q$bml_style\E|\Q$bml_style-$bml_jobname\E),/) {
              RequireResource($_); } }
        }
      },
      'bookml/CSS', (-d 'bmluser') ? 'bmluser' : ());
    # move <ltx:resource> up to the top or they will not work
    my ($firstnonresource) = $document->findnodes('/*/*[local-name()!="resource"]');
    for my $node ($document->findnodes('//ltx:resource')) {
      $node->unbindNode();
      $document->documentElement->insertBefore($node, $firstnonresource); }
    return;
});

# Include alternative format
DefPrimitive('\bmlAltFormat {} {}', sub {
    my ($stomach, $path, $name) = @_;
    $path = ToString(Expand($path));
    $name = ToString(Expand($name));
    BMLRequireResource($path, location => 'download', name => $name) if $name;
    @bml_download = grep { !$_ eq $path } @bml_download;
    return;
});

AtBeginDocument(sub {
    for my $file (@bml_download) {
      BMLRequireResource($file, location => 'download', name => uc(pathname_type($file))); }
    return;
});

# Compute colors for sepia and dark mode (mimicking CSS filters)
# note that xcolor.sty and LaTeXML::Common::Color use the linear RGB space
AtEndDocument(sub {
    return unless $bml_style eq 'gitbook';
    return T_CS('\bml@colors');
});

AtEndDocument(sub {
    return T_CS('\bml@css');
});

# CSS filter invert(100%) hue-rotate(180deg)
sub BMLColorDarkMode {
  my ($color) = @_;

  # sRGB to linear RGB
  my ($R, $G, $B) = $color->convert('rgb')->components;

  # invert
  # https://www.w3.org/TR/filter-effects-1/#invertEquivalent
  ($R, $G, $B) = map { 1 - $_ } ($R, $G, $B);

  # rotate hue
  # https://www.w3.org/TR/filter-effects-1/#element-attrdef-fecolormatrix-values
  ($R, $G, $B) = ((0.213 - 0.787) * $R + (0.715 + 0.715) * $G + (0.072 + 0.072) * $B,
    (0.213 + 0.213) * $R + (0.715 - 0.285) * $G + (0.072 + 0.072) * $B,
    (0.213 + 0.213) * $R + (0.715 + 0.715) * $G + (0.072 - 0.928) * $B);

  # clamp
  ($R, $G, $B) = map { ($_ < 0) ? 0 : (($_ > 1) ? 1 : $_) } ($R, $G, $B);
  return Color('rgb', $R, $G, $B);
}

# CSS filter sepia(40%)
sub BMLColorSepiaMode {
  my ($color) = @_;
  my $amount = 0.40;

  # sRGB to linear RGB
  my ($R, $G, $B) = $color->convert('rgb')->components;

  # sepia
  # https://www.w3.org/TR/filter-effects-1/#sepiaEquivalent
  ($R, $G, $B) = ((0.393 + 0.607 * (1 - $amount)) * $R + (0.769 - 0.769 * (1 - $amount)) * $G + (0.189 - 0.189 * (1 - $amount)) * $B,
    (0.349 - 0.349 * (1 - $amount)) * $R + (0.686 + 0.314 * (1 - $amount)) * $G + (0.168 - 0.168 * (1 - $amount)) * $B,
    (0.272 - 0.272 * (1 - $amount)) * $R + (0.534 - 0.534 * (1 - $amount)) * $G + (0.131 + 0.869 * (1 - $amount)) * $B);

  # clamp
  ($R, $G, $B) = map { ($_ < 0) ? 0 : (($_ > 1) ? 1 : $_) } ($R, $G, $B);
  return Color('rgb', $R, $G, $B);
}

my ($bml_colors_css, %bml_colors_darkmode, %bml_colors_sepiamode, %bml_colors) = ('', (), (), ());

DefConstructorI('\bml@colors', undef, sub {
    my ($document) = @_;

    &$bml_ProgressSpinup('BookML colors');

    sub genColors {
      my ($attr, $color) = @_;
      my $color_hex;

      if (!ref $color) {    # hex string
        $color_hex = $color;
        my ($red, $green, $blue) = map { hex($_) / 255 } ($color_hex =~ m/../g);
        $color = Color('rgb', $red, $green, $blue); }
      else {                # LaTeXML::Common::Color
        $color_hex = substr($color->toHex, 1); }

      my $class = "bml_${attr}_$color_hex";

      if (!$bml_colors{$attr}{$color_hex}) {
        $bml_colors{$attr}{$color_hex} = 1;
        $bml_colors_darkmode{$color_hex}  //= BMLColorDarkMode($color)->toHex;
        $bml_colors_sepiamode{$color_hex} //= BMLColorSepiaMode($color)->toHex;
        my $dark_hex  = $bml_colors_darkmode{$color_hex};
        my $sepia_hex = $bml_colors_sepiamode{$color_hex};
        $bml_colors_css .= ".$class {$attr:#$color_hex !important} .book.color-theme-1 .$class {$attr:$sepia_hex !important} .book.color-theme-2 .$class {$attr:$dark_hex !important}\n"; }

      return $class;
    }

    # <ltx:text _font="...">
    for my $node ($document->findnodes('//*[@_font]')) {
      my $color = $document->getNodeFont($node)->getColor;
      $color = '000000' if $color eq 'black';    # $LaTeXML::Common::Font::DEFCOLOR
      my $class = genColors('color', $color); }

    # <ltx:* framecolor="...">
    for my $node ($document->findnodes('//*[@framecolor]')) {
      my $color_hex = substr($node->getAttribute('framecolor'), 1);
      my $class     = genColors('border-color', $color_hex);
      $document->addClass($node, $class); }

    # <ltx:* backgroundcolor="...">
    for my $node ($document->findnodes('//*[@backgroundcolor]')) {
      my $color_hex = substr($node->getAttribute('backgroundcolor'), 1);
      my $class     = genColors('background-color', $color_hex);
      $document->addClass($node, $class); }

    # <ltx:rule color="...">
    for my $node ($document->findnodes('//ltx:rule[@color]')) {
      my $color_hex = substr($node->getAttribute('color'), 1);
      my $class     = genColors('background-color', $color_hex);
      $document->addClass($node, $class); }

    for my $attr ('color', 'fill', 'stroke', 'stop-color', 'flood-color', 'lighting-color') {
      for my $node ($document->findnodes("//*[\@$attr and not(self::ltx:rule)]")) {
        my $color_hex = $node->getAttribute($attr);
        next if $color_hex =~ m/^(none|context-fill|context-stroke)$|^url\(/;    # see SVG <paint> values
        $color_hex = '#000000' if $color_hex eq 'black';    # $LaTeXML::Common::Font::DEFCOLOR
        $color_hex = substr($color_hex, 1);
        my $class = genColors($attr, $color_hex);
        $document->addClass($node, $class); } }

    # <ltx:* cssstyle="... text-decoration-color:...">
    for my $node ($document->findnodes('//*[contains(@cssstyle,"text-decoration-color:")]')) {
      my ($color_hex) = $node->getAttribute('cssstyle') =~ m/text-decoration-color: *#([0-9A-Fa-f])*/;
      my $class = genColors('text-decoration-color', $color_hex);
      $document->addClass($node, $class); }

    if ($bml_colors_css) {
      (mkdir("bmluser") or die "cannot create directory bmluser: $!") unless -d "bmluser";
      my $cssfile = "bmluser/colors.gitbook-$bml_jobname.css";
      open(my $fh, '>', $cssfile) or die "cannot write to $cssfile: $!";
      print $fh $bml_colors_css;
      close($fh); }

    &$bml_ProgressSpindown('BookML colors');
    return;
});

# HTML-in-LaTeX mechanism
my %bml_html_innerctx = ();
my @bml_html_inline   = ('a', 'abbr', 'acronym', 'audio', 'b', 'bdi', 'bdo', 'big', 'br', 'button',
  'canvas',  'cite', 'code',  'data',  'datalist', 'del',  'dfn', 'em', 'embed', 'i', 'iframe', 'img',
  'input',   'ins',  'kbd',   'label', 'map',      'mark', 'meter', 'noscript', 'object', 'output',
  'picture', 'progress', 'q', 'ruby',  's',      'samp', 'script',  'select', 'slot', 'small', 'span',
  'strong',  'sub', 'sup',    'svg', 'template', 'textarea', 'time', 'u', 'tt', 'var', 'video', 'wbr',
  'summary');    # summary is not 'inline' per spec, but we must avoid the ltx:p wrapper

AtBeginDocument(sub { RelaxNGSchema('bookml/schema'); });

# switch to T1 encoding for proper parsing of <, >
sub BMLStartHTMLFontEncoding {
  my ($stomach) = @_;
  $stomach->bgroup;
  if (LoadFontMap('T1')) {
    MergeFont(encoding => 'T1'); }
  else {
    Warning('bookml', 'html', $stomach, 'Can\'t load T1 encoding, raw HTML likely to be garbled'); }
  return; }

sub BMLEndHTMLFontEncoding {
  $_[0]->egroup;
  return; }

sub BMLHTMLEnvironment {
  my ($name, %opts) = @_;

  DefEnvironment("{h:$name} OptionalKeyVals", sub {
      my ($document, $kv, %properties) = @_;
      my $body = $properties{body};
      $kv = $kv && $kv->getKeyVals;

      my $innercontext = $opts{innercontext} // '';
      my $elem         = "ltx:xml${innercontext}elem";

      my $node = $document->openElement($elem,
        ns   => 'http://www.w3.org/1999/xhtml',
        name => $name, innercontext => $opts{innercontext});

      for my $attr (keys %$kv) {
        $document->insertElement('ltx:xmlattr', undef, name => lc($attr),
          value => ToString($$kv{$attr})); }

      $document->absorb($body);    # emit content of the environment

      $document->closeElement($elem);
    },
    scope => 'global'
  );

  return;
}

DefPrimitive('\bmlHTMLEnvironment{}', sub {
    my ($gullet, $names) = @_;
    my @names = split(/,/, ToString(Expand($names)));
    for my $name (@names) {
      if (!defined $bml_html_innerctx{$name} || '' ne $bml_html_innerctx{$name}) {
        $bml_html_innerctx{$name} = '';
        BMLHTMLEnvironment($name); } }
    return;
});

DefPrimitive('\bmlHTMLInlineEnvironment{}', sub {
    my ($gullet, $names) = @_;
    my @names = split(/,/, ToString(Expand($names)));
    for my $name (@names) {
      if (!defined $bml_html_innerctx{$name} || 'inline' ne $bml_html_innerctx{$name}) {
        $bml_html_innerctx{$name} = 'inline';
        BMLHTMLEnvironment($name, innercontext => 'inline'); } }
    return;
});

DefPrimitive('\bmlHTMLBlockEnvironment{}', sub {
    my ($gullet, $names) = @_;
    my @names = split(/,/, ToString(Expand($names)));
    for my $name (@names) {
      if (!defined $bml_html_innerctx{$name} || 'block' ne $bml_html_innerctx{$name}) {
        $bml_html_innerctx{$name} = 'block';
        BMLHTMLEnvironment($name); } }
    return;
});

# HTML syntax
if ($bml_htmlsyn) {
  DefMacro('\< Until:>', sub {
      my ($gullet, $tokens) = @_;
      my ($elem, $attrs)    = split(/\s+/, ToString(Expand($tokens)), 2);
      $elem  = lc($elem);
      $attrs = $attrs // '';

      my $output = '';
      if ($elem =~ m!^/(.+)!) {
        $output = "\\end{h:$1}"; }
      else {
        my $opts = '';
        while ($attrs =~ m!\s*([^=]+)\s*=\s*('|")(.*?)\g2!g) {
          $opts = $opts . "$1={$3},"; }
        $opts = $opts ? "[$opts]" : '';

        if ($elem =~ m!^([^/]+)/$!) {
          $elem = $1; $output = "\\end{h:$elem}"; }
        elsif ($attrs =~ m!/$!) {
          $output = "\\end{h:$elem}"; }

        $output = "\\begin{h:$elem}$opts$output";
        if (!defined $bml_html_innerctx{$elem}) {
          my $innercontext = grep(/^$elem$/, @bml_html_inline) ? 'inline' : '';
          Info('found', 'html', $gullet, "new HTML tag <$elem>" . ($innercontext ? " ($innercontext)" : ''));
          BMLHTMLEnvironment($elem, innercontext => $innercontext);
          $bml_html_innerctx{$elem} = $innercontext; }
      }

      $gullet->openMouth(LaTeXML::Core::Mouth->new($output), 0);
  });
}

# Raw HTML mechanism

my $parser = XML::LibXML->new();

DefConstructor('\bmlRawHTML Digested', sub {
    my ($document, $arg) = @_;

    # wrap in <span> to set the XHTML namespace
    my $html = $parser->parse_balanced_chunk('<span xmlns="http://www.w3.org/1999/xhtml">'
        . ToString($arg) . '</span>');
    my @elems = $html->firstChild->findnodes('*');

    my $node = $document->openElement('ltx:rawhtml');
    map { $document->appendClone($node, $_) } @elems;
    $document->closeElement('ltx:rawhtml');
  },
  beforeDigest => \&BMLStartHTMLFontEncoding,
  afterDigest  => \&BMLEndHTMLFontEncoding
);

# Image generation via LaTeX
NewCounter('bml@imagecounter');
DefMacro('\bml@includeimage', '\stepcounter{bml@imagecounter}\includegraphics{bmlimages/\jobname-\thebml@imagecounter.svg}\bml@add@depth{\thebml@imagecounter}');
DefConstructor('\bml@add@depth{}', \&BMLAddDepth);

my $bml_depth;
my $source  = LookupValue('SOURCEFILE');
my $outdir  = pathname_concat('bmlimages', $bml_jobname);
my $dvifile = pathname_concat($outdir,     $bml_jobname . '.dvi');
my $svgfmt  = pathname_concat('bmlimages', '%f-%0p.svg');
my $dpth    = pathname_concat($outdir,     $bml_jobname . '.dpth');

sub BMLAddDepth {
  my ($document, $counter) = @_;
  $counter = ToString($counter);
  BMLGenerateImages($document);
  my $node = $document->getLastChildElement($document->getElement);
  return Error('expected', 'dpth', $document,
    'could not find depth for BookML image ' . $node->getAttribute('graphic')
      . "; see $bml_jobname.latexml.log for more details, and try deleting $dpth")
    unless defined $bml_depth && exists $$bml_depth{$counter};
  $document->setAttribute($node, 'imagedepth', int(0.5 + $$bml_depth{$counter} * $bml_imagescale * 96 / 72));
  return;
}

sub BMLGenerateImages {
  my ($gullet) = @_;

  # skip if we have already generated the images
  return if defined $bml_depth;
  $bml_depth = {};

  return Error('expected', 'latexmk', undef, 'No latexmk command found; BookML images will be missing.',
    'Please install latexmk to let BookML generate images from LaTeX')
    unless which 'latexmk';
  return Error('expected', 'dvisvgm', undef, 'No dvisvgm command found; BookML images will be missing.',
    'Please install dvisvgm to let BookML generate images from LaTeX')
    unless which 'dvisvgm';
  return Error('expected', 'preview.sty', undef, 'Package preview.sty not found; BookML images will be missing.',
    'Please install preview.sty to let BookML generate images from LaTeX')
    unless pathname_kpsewhich('preview.sty');

  &$bml_ProgressSpinup('BookML images');

  # code to activate bmlimages and add dvisvgm,hypertex as global options
  # hypertex ensures hyperref does not emit PDF specials which confuse dvisvgm
  my $preclass = '\PassOptionsToPackage{_bmlimages}{bookml/bookml}';       # activate bmlimages
  $preclass .= '\makeatletter';
  $preclass .= '\let\bml@dcl@ss\documentclass';                            # save \documentclass
  $preclass .= '\renewcommand{\documentclass}[1][]{';                      # renew \documentclass[]
  $preclass .= '\def\bml@dcl@ss@pts{#1}';                                  # save options
  $preclass .= '\let\documentclass\bml@dcl@ss';                            # restore \documentclass
  $preclass .= '\ifx\bml@dcl@ss@pts\@empty';                               # no options?
  $preclass .= '\def\bml@dcl@ss@{\documentclass[dvisvgm,hypertex]}';       # add dvisvgm,hypertex
  $preclass .= '\else';                                                    # with options?
  $preclass .= '\def\bml@dcl@ss@{\documentclass[dvisvgm,hypertex,#1]}';    # prepend dvisvgm,hypertex
  $preclass .= '\fi\bml@dcl@ss@}';                                         # close definition
  $preclass .= '\makeatother';

  # compile $source to DVI with latexmk
  my @lmk_invocation = ('latexmk', '-output-format=dvi',
    '-interaction=nonstopmode',     '-halt-on-error',
    '-output-directory=' . $outdir, '-usepretex=' . $preclass,
    '-jobname=' . $bml_jobname,     $source);
  if ($^O =~ /^(MSWin|cygwin)/) {
    require Win32::ShellQuote;
    @lmk_invocation = Win32::ShellQuote::quote_system_list(@lmk_invocation); }
  &$bml_NoteLog('Calling ' . join(' ', @lmk_invocation));
  &$bml_NoteLog('Logs in ' . pathname_concat($outdir, $bml_jobname . '.log'));
  my $lmk_pid = IPC::Open3::open3(undef, my $lmk_stdout, undef,
    @lmk_invocation);

  my $rebuild    = 1;
  my $print_next = 0;

  # report progress and remember if latexmk did anything
  while (<$lmk_stdout>) {
    if (!$rebuild || m/^Latexmk: Nothing to do for/) {
      $rebuild = 0; }
    if (m/^Latexmk: Run number (.*)/) {
      &$bml_ProgressStep("latexmk: run number $1"); }
    else {
      chomp;
      $_ = ' ' . $_;
      # copied from texfot.pl v1.47 by Karl Berry (public domain)
      if ($print_next) {
        &$bml_NoteSTDERR($_);
        $print_next = 0; }
      # lines that can be ignored
      elsif (/^\ (
        LaTeX\ Warning:\ You\ have\ requested\ package
        |LaTeX\ Font\ Warning:\ Some\ font\ shapes
        |LaTeX\ Font\ Warning:\ Size\ substitutions
        |Package\ auxhook\ Warning:\ Cannot\ patch
        |Package\ biditools\ Warning:\ Patching
        |Package\ caption\ Warning:\ Un(supported|known)\ document\ class
        |Package\ fixltx2e\ Warning:\ fixltx2e\ is\ not\ required
        |Package\ frenchb?\.ldf\ Warning:\ (Figures|The\ definition)
        |Package\ layouts\ Warning:\ Layout\ scale
        |\*\*\*\ Reloading\ Xunicode\ for\ encoding  # spurious ***
        |This\ is\ `?(epsf\.tex|.*\.sty|TAP) # so what
        |pdfTeX\ warning:.*inclusion:\ fou   #nd PDF version ...
        |pdfTeX\ warning:.*inclusion:\ mul   #tiple pdfs with page group
        |libpng\ warning:\ iCCP:\ Not\ recognizing
        |!\ $
        )/x) {
        &$bml_ProgressStep(); }
      # error messages followed by an additional line
      elsif (/^\ (
        .*?:[0-9]+:         # usual file:lineno: form
        |!                  # usual ! form
        |>\ [^<]            # from \show..., but not "> <img.whatever"
        |.*pdfTeX\ warning  # pdftex complaints often cross lines
        |LaTeX\ Font\ Warning:\ Font\ shape
        |Package\ hyperref\ Warning:\ Token\ not\ allowed
        |removed\ on\ input\ line  # hyperref
        |Runaway\ argument
        )/x) {
        $print_next = 1;
        &$bml_NoteSTDERR($_); }
      # remaining errors and diagnostic messages
      elsif (/^\ (
        This\ is
        |Output\ written
        |No\ pages\ of\ output
        |\(.*end\ occurred\ inside\ a\ group
        # |(Und|Ov)erfull                           # bookml does not care about und|overfulls
        |(LaTeX|Package|Class).*(Error) # |Warning) # bookml can ignore warnings
        |.*Citation.*undefined                      # bookml can ignore warnings
        |.*\ Error           # as in \Url Error ->...
        |Missing\ character: # good to show (need \tracinglostchars=1)
        |\\endL.*problem     # XeTeX?
        |\*\*\*\s            # *** from some packages or subprograms
        |l\.[0-9]+\          # line number marking
        |all\ text\ was\ ignored\ after\ line
        |.*Fatal\ error
        |.*for\ symbol.*on\ input\ line
        |\#\#
        )/x) {
        &$bml_NoteSTDERR($_); }
      &$bml_ProgressStep();
      &$bml_NoteLog($_); }
  }

  close($lmk_stdout);
  waitpid($lmk_pid, 0);
  if ($! || $?) {
    &$bml_ProgressSpindown('BookML images');
    return Error('bookml', 'latexmk', undef, "problem while running latexmk, some images will be missing; see $outdir/$bml_jobname.log for more details",
      $! ? "Error closing pipe: $!" : 'Exit status ' . ($? >> 8),
      'Invocation:', @lmk_invocation); }

  if (!$rebuild) {
    # open the depth cache
    if (tie my %bml_depth_db, 'DB_File', $dpth, O_RDONLY) {
      # restore the saved depth
      while (my ($k, $v) = each(%bml_depth_db)) {
        $$bml_depth{$k} = $v; }
      untie %bml_depth_db; }
    else {
      # delete the depth cache
      Info('I/O', 'dpth', undef, "Couldn't open the depth cache ($dpth) for $bml_jobname.tex, message was '$!'; SVGs and depth cache will be recreated");
      $rebuild = 1; } }

  # if the DVI has changed, or the depth cache is invalid, rebuild the images
  if ($rebuild) {
    # convert DVI to images
    my $dsvg_version = version->parse(split(' ', `dvisvgm --version`));
    return Error('bookml', 'dvisvgm', undef, "version $dsvg_version is too old, please upgrade to v1.6 or above") if $dsvg_version < v1.6;
    my @dsvg_invocation = ('dvisvgm', '--page=1-', '--bbox=preview',
      '--no-fonts', '--exact', '--zoom=' . $bml_imagescale,
      ('--optimize') x ($dsvg_version >= v2.7),
      '--output=' . $svgfmt, $dvifile);
    if ($^O =~ /^(MSWin|cygwin)/) {
      require Win32::ShellQuote;
      @dsvg_invocation = Win32::ShellQuote::quote_system_list(@dsvg_invocation); }
    &$bml_NoteLog('Calling ' . join(' ', @dsvg_invocation));
    my $dsvg_pid = IPC::Open3::open3(undef, my $dsvg_stdout, undef,
      @dsvg_invocation);

    # report progress
    my $counter;
    while (<$dsvg_stdout>) {
      if (m/^processing page (\d+)/) {
        $counter = $1;
        &$bml_ProgressStep("dvisvgm: processing image $counter"); }
      elsif (m/, depth=(\d*(?:\.\d+)?)pt/) {
        $$bml_depth{$counter} = $1; }
      else { &$bml_ProgressStep(); }
      chomp $_;
      &$bml_NoteLog($_);
    }

    close($dsvg_stdout);
    waitpid($dsvg_pid, 0);
    if ($! || $?) {
      &$bml_ProgressSpindown('BookML images');
      return Error('bookml', 'dvisvgm', undef, "problem while running dvisvgm, some images will be missing or misaligned; see $bml_jobname.latexml.log for more details",
        $! ? "Error closing pipe: $!" : 'Exit status ' . ($? >> 8),
        'Invocation:', @dsvg_invocation); }

    # create the depth cache
    unlink $dpth if -f $dpth;
    if (tie my %bml_depth_db, 'DB_File', $dpth, O_RDWR | O_CREAT) {
      # save the depth
      while (my ($k, $v) = each(%$bml_depth)) {
        $bml_depth_db{$k} = $v; }
      untie %bml_depth_db; }
    else {
      # delete the depth cache
      Error('I/O', 'dpth', undef, "Couldn't create the depth cache ($dpth) for $bml_jobname.tex, message was '$!'; deleting $dpth");
      unlink $dpth if -f $dpth; } }

  &$bml_ProgressSpindown('BookML images');

  return;
}

sub BMLImageEnvironment {
  my ($gullet, $names) = @_;
  my @names = split(/,/, ToString($names));
  for my $name (@names) {
    AtBeginDocument(sub {
        RequirePackage('graphicx');
        DefMacroI(T_CS("\\begin{$name}"), undef, sub {
            my ($ingullet) = @_;
            while ($ingullet->readUntil(T_CS('\end'))) {
              my $arg = $ingullet->readArg;
              last if (ToString($arg) eq $name);
            }
            return T_CS('\bml@includeimage');
        });
    });
  }
  return;    # or perltidy complains
}

DefPrimitive('\bmlImageEnvironment{}', \&BMLImageEnvironment);

BMLImageEnvironment(undef, 'preview');    # predefined by the preview package
BMLImageEnvironment(undef, 'bmlimage');

# Alternative text
DefConstructor('\bmlDescription Semiverbatim', sub {
    my ($document, $text) = @_;
    my $node = $document->getLastChildElement($document->getElement);
    $document->setAttribute($node, 'description', ToString($text));
});

# Add class to previous node
DefConstructor('\bmlPlusClass Semiverbatim', sub {
    my ($document, $class) = @_;
    my $node = $document->getLastChildElement($document->getElement);
    $document->addClass($node, ToString($class));
});

# Disable MathJax locally
DefConstructor('\bmlDisableMathJax', sub {
    my ($document) = @_;
    my $node       = $document->getElement;
    my @eqnodes    = $document->findnode('ancestor-or-self::ltx:equation[1]//ltx:Math', $node);
    if (!@eqnodes) {
      @eqnodes = ($node); }
    for my $eqnode (@eqnodes) {
      $document->addClass($eqnode, 'bml_disable_mathjax'); }
}, reversion => '');

# Unicode variation sequences
DefMathI('\emptyset', undef, "\x{2205}\x{FE00}", role => 'ID', meaning => 'empty-set');

if ($LaTeXML::VERSION < v0.8.8) {
  DefMathI('*', undef, "\x{2217}", role => 'MULOP', meaning => 'times'); }

1;