Redmine

I have been working on a modification for the docpu-plugin (http://www.redmine.org/plugins/redmine_doc_pu) and the mathjax-Plugin (http://www.redmine.org/issues/1994) for the past week. Now after I finally got it to work, I want to share my experiences and maybe find some suggestions on what I could have done better.

Here is what I wanted to do:

• Oranise the wiki as a linear tree, with each subsection and subsubsection on a different wiki-page.
• Include all images in the pdf-document, and set imagecaptions where specified.
• Convert all wiki-pagelinks to references inside the pdf-document, except for those at the end of each page.
• The pfd-properties should be set according to the document-properties in docpu.
• LaTeX-Expressions should be displayed correctly in the wiki and the pdf-document.

I was working with redmine 1.0.1 on debian squeeze. Because of my very poor knowledge of Ruby, I had to do most of the actual work with bash-scripts. Here is the first script, for installing the docpu-plugin:

install_docpu.sh

#!/bin/bash

## This script installs and configures the docpu-plugin for redmine on Debian. First, all the packages needed will be installed with aptitude, then the configurations and permissions will be set.

aptitude update

# All the required software is installed here
aptitude install texlive-latex-base
aptitude install texlive-latex-extra
aptitude install libredcloth-ruby

# Download, install and configure the doc_pu plugin:
wget -O /usr/share/redmine/vendor/plugins/docpu.zip http://www.redmine.org/attachments/4975/redmine_doc_pu_v003.zip
unzip /usr/share/redmine/vendor/plugins/docpu.zip -d /usr/share/redmine/vendor/plugins/
rm /usr/share/redmine/vendor/plugins/docpu.zip
chmod -R 755 /usr/share/redmine/vendor/plugins/redmine_doc_pu
mkdir /usr/share/redmine/files
chown www-data:www-data /usr/share/redmine/files

# This part of the script assumes that pdfscript.sh and doc_pu_controller.rb are in the same directory as install_docpu.sh
cp ./pdfscript.sh /usr/share/redmine/pdfscript.sh
cp ./doc_pu_controller.rb /usr/share/redmine/vendor/plugins/redmine_doc_pu/app/controllers/doc_pu_controller.rb

# Here, the webserver and database will be reconfigured.
cd /usr/share/redmine/
rake db:migrate_plugins RAILS_ENV=production
/etc/init.d/apache2 reload
/etc/init.d/apache2 restart

The second script deals with modifying the LaTeX-output of docpu in order to get rid of some unwanted behavior:

pdfscript.sh

#!/bin/bash

# This script converts the output of the doc_pu plugin to a pdf file with the following properties:
# -> Images are embedded into the file.
# -> Inline LaTeX commands are preserved.
# -> Links after LINKDELIMITER on each page are ignored.
# -> Internal references are resolved into hyperlinks.
# -> Pdfattributes for Author and Title are set.
# -> Move the resultfile to the filepath specified by the first argument.

LINKDELIMITER=/^Links:$/

# Create a clean working directory an populate it with the contents of the files directory. Grant all permissions on this directory, to allow pdflatex to access and write all its contents.
rm -rf /usr/share/redmine/files/docpu_currentbuild
mkdir /usr/share/redmine/files/docpu_currentbuild
chmod -R 777 /usr/share/redmine/files/docpu_currentbuild
cp /usr/share/redmine/files/template.tex /usr/share/redmine/files/docpu_currentbuild
cp /usr/share/redmine/files/document.tex /usr/share/redmine/files/docpu_currentbuild

# Copy the required images into the correct directory. This is necessary because all references in the .tex-file are local, and therefore the images have to be in the same directory as the .tex-file in order to be included in the pdf.
cp /var/lib/redmine/default/files/* /usr/share/redmine/files/docpu_currentbuild/
cd /usr/share/redmine/files/docpu_currentbuild/

## These substitutions are necessary because doc_pu will escape all '$' and '\' Symbols when exporting to LaTeX. If LaTeX-Expressions like '$expression$' or '\[expression\]' are used, they will be interpreted as plaintext if these escapes are not removed.

# ...Substitute '$$expression$$' for '\$\$expression\$\$'.
sed 's/\\\$\\\$\(.*\)\\\$\\\$/\$\$\1\$\$/g' ./document.tex > ./output.tex
rm ./document.tex
mv ./output.tex ./document.tex

# ...Substitute '$expression$' for '\$expression\$'.
sed 's/\\\$\(.*\)\\\$/\$\1\$/g' ./document.tex > ./output.tex
rm ./document.tex
mv ./output.tex ./document.tex

# ...Substitute '\' for '\textbackslash{}'.
sed 's/\\textbackslash{}/\\/g' ./document.tex > ./output.tex
rm ./document.tex
mv ./output.tex ./document.tex

# Remove all links at the end. The primary porpose of this step is to increase readability in the linear document.
sed "$LINKDELIMITER,/\\s/d" ./document.tex > ./output.tex
rm ./document.tex
mv ./output.tex ./document.tex

# Add the missing labels. This is necessary for the internal references to work.
sed 's/section{\([^\]*\)}$/section{\1} \\label{page:\1}/' ./document.tex > ./output.tex
rm ./document.tex
mv ./output.tex ./document.tex

# Grant all permissions on the new file (otherwise, redmine will not be able to modify it later on).
chmod 777 ./document.tex

# Author und Title are added to the pdf properties.
sed 's/\\title{\(.*\)} \\author{\(.*\)} \\usepackage{hyperref}/\\title{\1} \\author{\1} \\usepackage\[pdftex,pdfauthor={\2},pdftitle={\1}\]{hyperref}/' ./template.tex > ./output.tex
rm ./template.tex
mv ./output.tex ./template.tex

# Grant all permissions on the new file (otherwise, redmine will not be able to modify it later on).
chmod 777 ./template.tex

# Call pdflatex twice. The second call will use the corrected backreferences of the first call.
pdflatex ./template.tex
pdflatex ./template.tex

# Replace the document originally created with pdflatex with our modified version. Now, the "View document" command of doc_pu should return the modified file.
mv ./template.pdf $1

The third file is essentially a modified version of the original doc_pu_controller.rb. The only change is to add the two lines

output = `/usr/share/redmine/pdfscript.sh #{@doc.filepath}`
@log.push({:line => output, :msg => nil})

to the build_remote function, right before

render :partial => "log"

is called.

Now, the pdf-output should work as desired, if the correct permissions for document publishing are set. The last script is a modified version of the mathjax-Plugin. The changes to this Plugin essentially enable the $expression$-Syntax and the HTML-output for Firefox. Replace the "var config"- and "script src"-lines by the following:

script.src=\"http://cdn.mathjax.org/mathjax/1.1-latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML-full\";

var config = 'MathJax.Hub.Config({ tex2jax: { inlineMath: [ [\"$\",\"$\"] ]}, MMLorHTML: { prefer: { Firefox: \"HTML\" } } }); MathJax.Hub.Startup.onload();';

After restarting the webserver, all intended LaTeX-Expressions should render correctly.

I know that this approach to the problem is less than optimal: Editing the ruby-source directly to achieve the desired result would definitly be the better solution, but maybe the shellscripts I provided will help someone with more experience in the language to do this.