doc/todo/Move_teximg_latex_preamble_to_config_file.mdwn

   1 The [[plugins/teximg]] plugin currently has a TODO in the source code to make the preamble configurable.  The included [[patch]] makes this change.
   2
   3 The patch also makes some other changes:
   4
   5   - The default latex preamble is changed to the international standard `article` class from the European `scrartcl` class.
   6   - Removed the non-standard `mhchem` package from the default preamble.
   7   - Allow the use of `dvipng` rather than `dvips` and `convert` (`convert` is not a standard part of a latex install).  This is configurable.
   8
   9 -- [[Will]]
  10
  11 > I like making this configurable. I do fear that changing what's included
  12 > by default could break some existing uses of teximg? That needs to be
  13 > considered, and either the breakage documented in NEWS, or avoided. Also,
  14 > if mchem is dropped, I think the suggests on texlive-science in
  15 > debian/control should probably go? --[[Joey]]
  16
  17 >> Yes, changing the defaults could break some existing uses.  I think in
  18 >> this case, documenting in NEWS and dropping texlive-science is the
  19 >> best option.  In fact, NEWS should probably document the config
  20 >> setting to return things to how they were.
  21 >>
  22 >> The reason I prefer dropping `mchem` rather than keeping it is that `mchem`
  23 >> is non-standard.  Now that things are configurable and it is easy to
  24 >> add in if you want it, having only standard packages by default is a
  25 >> good thing.  Here is a proposed NEWS entry:
  26
  27 File: TexImg standard preamble changed
  28
  29 The [[plugins/teximg]] [[plugin]] now has a configurable LaTeX preamble.
  30 As part of this change the `mchem` LaTeX package has been removed from
  31 the default LaTeX preamble as it wasn't included in many TeX installations.
  32
  33 The previous behaviour can be restored by adding the following to your ikiwiki setup:
  34
  35         teximg_prefix => '\documentclass{scrartcl}
  36                 \usepackage[version=3]{mhchem}
  37                 \usepackage{amsmath}
  38                 \usepackage{amsfonts}
  39                 \usepackage{amssymb}
  40                 \pagestyle{empty}
  41                 \begin{document}',
  42
  43 In addition, the rendering mechanism has been changed to use `dvipng` by default.
  44 If you would like to return to the old rendering mechanism using `dvips` and `convert`
  45 then you should add the following line to your ikiwiki setup:
  46
  47         teximg_dvipng => 0,
  48
  49 The LaTeX postfix is unchanged, but is also now configurable using `teximg_postfix`.
  50 Happy TeXing.
  51
  52 >> I think that about covers it.  -- [[Will]]
  53
  54     diff --git a/IkiWiki/Plugin/teximg.pm b/IkiWiki/Plugin/teximg.pm
  55     index 369c108..8c3379f 100644
  56     --- a/IkiWiki/Plugin/teximg.pm
  57     +++ b/IkiWiki/Plugin/teximg.pm
  58     @@ -10,6 +10,18 @@ use File::Temp qw(tempdir);
  59      use HTML::Entities;
  60      use IkiWiki 2.00;
  61
  62     +my $default_prefix = <<EOPREFIX
  63     +\\documentclass{article}
  64     +\\usepackage{amsmath}
  65     +\\usepackage{amsfonts}
  66     +\\usepackage{amssymb}
  67     +\\pagestyle{empty}
  68     +\\begin{document}
  69     +EOPREFIX
  70     +;
  71     +
  72     +my $default_postfix = '\\end{document}';
  73     +
  74      sub import { #{{{
  75         hook(type => "getsetup", id => "teximg", call => \&getsetup);
  76         hook(type => "preprocess", id => "teximg", call => \&preprocess);
  77     @@ -21,6 +33,26 @@ sub getsetup () { #{{{
  78                         safe => 1,
  79                         rebuild => undef,
  80                 },
  81     +           teximg_dvipng => {
  82     +                   type => "boolean",
  83     +                   description => "Should teximg use dvipng to render, or dvips and convert?",
  84     +                   safe => 0,
  85     +                   rebuild => 0,
  86     +           },
  87     +           teximg_prefix => {
  88     +                   type => "string",
  89     +                   example => $default_prefix,
  90     +                   description => "LaTeX prefix for teximg plugin",
  91     +                   safe => 0, # Not sure how secure LaTeX is...
  92     +                   rebuild => 1,
  93     +           },
  94     +           teximg_postfix => {
  95     +                   type => "string",
  96     +                   example => $default_postfix,
  97     +                   description => "LaTeX postfix for teximg plugin",
  98     +                   safe => 0, # Not sure how secure LaTeX is...
  99     +                   rebuild => 1,
 100     +           },
 101      } #}}}
 102
 103      sub preprocess (@) { #{{{
 104     @@ -105,25 +137,35 @@ sub gen_image ($$$$) { #{{{
 105         my $digest = shift;
 106         my $imagedir = shift;
 107
 108     -   #TODO This should move into the setup file.
 109     -   my $tex = '\documentclass['.$height.'pt]{scrartcl}';
 110     -   $tex .= '\usepackage[version=3]{mhchem}';
 111     -   $tex .= '\usepackage{amsmath}';
 112     -   $tex .= '\usepackage{amsfonts}';
 113     -   $tex .= '\usepackage{amssymb}';
 114     -   $tex .= '\pagestyle{empty}';
 115     -   $tex .= '\begin{document}';
 116     +   if (!defined $config{teximg_prefix}) {
 117     +           $config{teximg_prefix} = $default_prefix;
 118     +   }
 119     +   if (!defined $config{teximg_postfix}) {
 120     +           $config{teximg_postfix} = $default_postfix;
 121     +   }
 122     +   if (!defined $config{teximg_dvipng}) {
 123     +           # TODO: Can we detect whether dvipng or convert is in the path?
 124     +           $config{teximg_dvipng} = 1;
 125     +   }
 126     +
 127     +   my $tex = $config{teximg_prefix};
 128         $tex .= '$$'.$code.'$$';
 129     -   $tex .= '\end{document}';
 130     +   $tex .= $config{teximg_postfix};
 131     +   $tex =~ s!\\documentclass{article}!\\documentclass[${height}pt]{article}!g;
 132     +   $tex =~ s!\\documentclass{scrartcl}!\\documentclass[${height}pt]{scrartcl}!g;
 133
 134         my $tmp = eval { create_tmp_dir($digest) };
 135         if (! $@ &&
 136     -       writefile("$digest.tex", $tmp, $tex) &&
 137     -       system("cd $tmp; latex --interaction=nonstopmode $tmp/$digest.tex > /dev/null") == 0 &&
 138     -       system("dvips -E $tmp/$digest.dvi -o $tmp/$digest.ps 2> $tmp/$digest.log") == 0 &&
 139     -       # ensure destination directory exists
 140     -       writefile("$imagedir/$digest.png", $config{destdir}, "") &&
 141     -       system("convert -density 120  -trim -transparent \"#FFFFFF\" $tmp/$digest.ps $config{destdir}/$imagedir/$digest.png > $tmp/$digest.log") == 0) {
 142     +           writefile("$digest.tex", $tmp, $tex) &&
 143     +           system("cd $tmp; latex --interaction=nonstopmode $tmp/$digest.tex > /dev/null") == 0 &&
 144     +           # ensure destination directory exists
 145     +           writefile("$imagedir/$digest.png", $config{destdir}, "") &&
 146     +           (($config{teximg_dvipng} &&
 147     +                   system("dvipng -D 120 -bg Transparent -T tight -o $config{destdir}/$imagedir/$digest.png $tmp/$digest.dvi > $tmp/$digest.log") == 0
 148     +                   ) ||
 149     +           (!$config{teximg_dvipng} &&
 150     +                   system("dvips -E $tmp/$digest.dvi -o $tmp/$digest.ps 2> $tmp/$digest.log") == 0 &&
 151     +                   system("convert -density 120  -trim -transparent \"#FFFFFF\" $tmp/$digest.ps $config{destdir}/$imagedir/$digest.png > $tmp/$digest.log") == 0))) {
 152                 return 1;
 153         }
 154         else {
 155
 156 [[done]]