DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:latexport

latexport Plugin

Compatible with DokuWiki

  • 2018-04-22 "Greebo" yes
  • 2017-02-19 "Frusterick Manners" yes
  • 2016-06-26 "Elenor Of Tsort" unknown
  • 2015-08-10 "Detritus" unknown

plugin A latex export renderer plugin to export latex documents from Dokuwiki

Last updated on
2018-04-26
Provides
Render
Repository
Source

Similar to dokutexit, latexit

Tagged with ebook, export, latex

Purpose and limitations

The main objectives of this plugin are:

  • It is possible to export a page or a set of pages as a structure of latex files and images.
  • Export forces as little presentation choices as possible, allowing user to make their own styles.
  • Mapping as naturally as possible the dokuwiki formatting into sensible latex formatting.
  • Latex scripting is readable.

The main limitation of the plugin is that it is not possible to directly download a finished PDF file. Anyway, with the procedure described below, you can obtain a PDF version in less than a minute.

Other limitations are:

  • Exported files assume that certain packages are available (listed below).
  • Text wrapping in table cells is not supported. Latex has issues with text wrapping multi-column cells. They're possible to overcome when you write the Latex document manually, but I haven't been able to found a satisfactory automated solution. In the end I had to choose between rowspan/colspan and text wrapping, and I chose the former.
  • I did an opinionated choice about how to map a navigable page hierarchy into a readable document structure. After testing it with two very big documents (more than 20 chapters, more than 200 pages), I believe it works quite well. I hope it will work also for you.

Installation

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

Alternatively, use git to clone this project into the plugin repository:

cd /wherever/is/dokuwiki/lib/plugins
git clone [obtain the repository url] latexport

Finally, you can also download the latest version as a ZIP archive and extract it into the plugins folder.

The plugin doesn't require any specific configuration or access rights.

Friendly plugins

The following plugins are not required, but add nice functionalities to latexport:

  • MathJax Plugin: To edit mathematical expressions.
  • Anchor Plugin: To refer to any place in the text. However, you need a small modification to it, described below.

Hacking anchor

To install anchor plugin, you already edited manually your plugin library, so you won't be scared of changing the render method as follows:

function render($mode, Doku_Renderer $renderer, $data) {
    if ($mode == 'latexport') {
        $renderer->anchor($data[0], $data[1]);
    } else {
        $renderer->doc .= 
            '<a name="' .
            htmlspecialchars($data[0]) . 
            '">' .
            htmlspecialchars($data[1]) . 
            '</a>';			
    }
}

Using the plugin to export pages as latex

After installing the plugin, export one page by calling an url as follows:

This downloads a ZIP archive with the following structure:

  • The name of the archive is the same as the page. In this example it is my_page.zip
  • The aaa.tex file, which corresponds to the exported page.
  • Each of the linked pages are represented by a file name_of_the_linked_page.tex
  • One folder named images, containing all printable media.

Installing TeX on your local system

Unless you know better I suggest to use TeX Live, which provides a fully functional, ready to use, well configured TeX engine. It exists for almost all platforms.

Creating a PDF file based on the exported latex

Follow this procedure to export Dokuwiki pages into a PDF file:

  • Download the zip archive from the page. You can either type the url in your browser and save the content in an appropriate place, or use a command similar to:
cd working_folder
curl -o content.zip www.xxx.yyy/path/to/my_page?do=export_latexport_tex
  • Unzip the archive into a destination folder, either with your favorite application, or using command line:
mkdir content
unzip content.zip -d content/
  • Prepare a root document with your styles and any other content that you want in your document, and save it besides the folder where you extracted the latex archive. Below I show you an simplistic example. Mind the graphicspath command, that specifies the destination folder plus the images folder. Mind also the import command, specifying the destination folder and the root page. Save it as root.tex or any other name that you see fit:
\documentclass{book}
 
\usepackage{import}                 % To import an external document.
\usepackage[french]{babel}          % To help with hyphenation.
\usepackage{soul}                   % To provide nice hyphenation.
\usepackage{hyperref}               % To have hyperlinks to internet.
\usepackage{array}                  % To have better presentation in tables.
\usepackage{csquotes}               % To display quotes.
\usepackage{multirow}               % To have rowspan in tables.
\usepackage{makecell}               % To have colspan in tables.
\usepackage{tabulary}               % To make tables.
\usepackage{fontspec}               % To use local system fonts.
\usepackage{listings}               % To show source code.
\usepackage[dvipsnames]{xcolor}     % To define nice colors.
\usepackage[export]{adjustbox}      % To resize images.
\usepackage{graphicx}               % To import images.
 
\graphicspath{ {content/images/} }  % Where the images are
\lstdefinestyle{c-style}{}          % Define styles for each used source code language
 
\begin{document}
\import{content/}{aaa.tex}
\end{document}
  • To launch the PDF generation, execute lualatex from your working folder. Execute it twice if the document contains an index, a list of figures, a table of contents or cross references (this is a standard latex requirement):
cd working_folder
lualatex root.tex
lualatex root.tex
  • If everything went correctly, you should have a PDF containing the exported page(s)

Syntax

The plugin doesn't define any new syntax. It does define mappings between usual Dokuwiki syntax and Latex syntax. Most of the time it consists into straight forward mapping: foot notes into foot notes, italic into italic, quotes into quotes and code blocks into code blocks. I've listed less intuitive elements in the next points.

See also suggestions about Structuring dokuwiki to look good both online and printed.

Mapping Dokuwiki's headers into TeX's document structure

When exporting a page, the latexport plugin transforms headers into sections and chapters using the following rule:

  • H1:
    • The first H1 opens the main matter. The text of header is ignored.
    • The second H1 opens the appendix.
    • The third and next H1 are considered chapters in the appendix.
  • H2:
    • Opens a part. The text of header is placed as title of the part.
    • When following the third or next H1, they're considered chapters in the appendix.
  • H3: Opens a chapter. The text of header is placed as title of the chapter.
  • H4: Opens a section. The text of header is placed as title of the section.
  • H5: Opens a subsection. The text of header is placed as title of the part.
  • Lesser headings: Open a subsection.

Including a page into another

Unordered list item containing only an internal link includes the destination page, using the current level of heading as the base level.

===== General instructions =====  
  * [[path:to:a:destination:page1|Link title is only visible online]]  
  * [[path:to:a:destination:page2|Link title is only visible online]]
  * [[more:like:this|etc.]]

In the destination page:

  • H1 opens a chapter, section, subsection, etc depending on the level of heading in the referring page where the link is placed. Text of header is used as title of the heading.
  • H1 never opens a level higher than chapter.
  • Lower header levels open a lower level headings.

Cross-referencing

You can place an internal link to another heading of the same page. For example:

====A heading====
Bla bla bla For more information see [[#Another heading]]. 
Bla bla bla.
Bla bla bla
 
====Another heading====
More information about bla bla bla.

You can place an internal link to another page. For example:

====A heading====
Bla bla bla For more information see [[path:to:the:other:page]]. 
Bla bla bla.
Bla bla bla

You can place an internal link to a specific heading of another page. For example:

====A heading====
Bla bla bla For more information see [[path:to:the:other:page#Specific heading]]. 
Bla bla bla.
Bla bla bla

Finally, you can use the anchor Plugin to place an ancor link to any point of a page. For example:

====A heading====
Bla bla bla For more information see [[path:to:the:other:page#anchor_name]]. 
Bla bla bla.
Bla bla bla
 
Further down in the text, or any page {{anchor:anchor_name:text}}

Internal links in Dokuwiki are translated in TeX as cross references:

  • When the link points to a page or heading, then the cross reference mentions part/chapter/section number.
  • When yoy use the anchor syntax, then the cross reference mentions a page number.

Pictures

Pictures are exported as centered figures with the caption underneath:

{{ :path:to:image.png |Caption}}

Size matters:

  • When resulting resolution is 240 ppi or better, images are exported with the same width as the text.
  • Smaller images are exported centered and with a smaller width.
  • Landscape images whose height would be enough to grant 240 ppi or better are rotated 90º and scaled to fit a whole page.
  • For more information about ppi, see https://en.wikipedia.org/wiki/Pixel_density

If you place several images without line breaking, they're exported as one single figure with as many images in it. In this case the size is not checked.

{{ :path:to:image1.png |Caption}} {{ :path:to:image2.png |Caption}}

External links are rendered as… external links:

  • In the PDF they will be clickable.
  • When printed, they've a special font.

If you include external links, be careful to explicitly use the external link markup. If they contain local characters, use them instead of hex encoding. For example:

  • The following link is correctly handled:
Visit this nice web page: [[https://fr.wikipedia.org/wiki/Convertisseur_analogique-numérique]]
  • The following link will pose problems:
Visit this nice web page: [[https://fr.wikipedia.org/wiki/Convertisseur_analogique-num%C3%A9rique]]

Writing mathematical expressions

Use the MathJax Plugin to write mathematical expressions. They are mapped into the TeX with very little changes:

  • Inline formulas delimited in Dokuwiki with $ … $ are exported to TeX as \( … \).
  • Inline formulas delimited in Dokuwiki with \( … \) are exported unchanged to TeX.
  • Display formulas delimited in Dokuwiki with $$ … $$ and \[ … \] are exported to TeX as \begin{equation} … \end{equation}.
  • Explicit \tag{.} command, needed in Dokuwiki to make visible references to equations, is removed during export to TeX, as it is not supported outside the amsmath package, and not needed.
  • Display formulas explicitly delimited in Dokuwiki with \begin{xx} … \end{xx} are exported unchanged.

Blocks of code

In Dokuwiki, blocks of code are written as:

<code pascal>
Program HelloWorld(output);
begin
  writeln('Hello, world!');
end.

</code>

This is exported to TeX as:

\begin{lstlisting}[language=pascal, style=pascal-style]
Program HelloWorld(output);
begin
  writeln('Hello, world!');
end.
\end{lstlisting}

Should you need to configure the presentation of the code, you can either redefine the language or use the style. For example you may use this snippet:

\usepackage{listings}
\usepackage[dvipsnames]{xcolor}
 
\definecolor{light-gray}{gray}{0.95}
 
\lstdefinestyle{pascal-style}{
  belowcaptionskip=1\baselineskip,
  breaklines=true,
  frame=L,
  xleftmargin=\parindent,
  language=Pascal,
  showstringspaces=false,
  basicstyle=\footnotesize\ttfamily,
  keywordstyle=\bfseries\color{green},
  commentstyle=\itshape\color{purple},
  identifierstyle=\color{blue},
  stringstyle=\color{orange},
  backgroundcolor=\color{light-gray},   
}

See more information here:

Using system fonts

To use system fonts, and not be restricted to the ones packaged in Latex, use the fontspecpackage:

\usepackage{fontspec}
\setmainfont{Lucida Bright}

To know the name of the font:

  1. Open the Font Book
  2. Locate your desired font
  3. Right click on it, and select Show in Finder
  4. Right click on the file and click on Get Info
  5. Copy the path to the font file, open a console, and type:
otfinfo -i '/Path/To/The/File/Name of the font.ttf'
Family:              Lucida Bright
Subfamily:           Demibold
Full name:           Lucida Bright Demibold
PostScript name:     LucidaBright-Demi
Version:             Version 1.69
Unique ID:           Lucida Bright Demibold
Trademark:           Lucida® is a registered trademark of Bigelow & Holmes Inc.
Copyright:           © 1991 by Bigelow & Holmes Inc. Pat. Des. 289,422. 
                     All Rights Reserved. © 1990-1991 Type Solutions, Inc. All Rights Reserved.
Vendor ID:           B&H

Use the font family name as main font, as in the example above.

Configuration and Settings

There are no configuration or settings with this plugin

Development

Development version of dokuwiki

To retrieve the development version of dokuwiki you need to have git installed. Then follow instructions in https://www.dokuwiki.org/devel:git

  • Go to your development folder, checkout the development version and switch to the stable branch.
git checkout https://github.com/splitbrain/dokuwiki.git
git checkout stable

This should have created a dokuwiki folder with all sources, including a _test folder with unit tests.

Configure the development version as you would do with the normal version.

Unit testing

As plugin has a quite complex behavior, it is tested with a PHPUnit test suite included with PHAR

  • Install PHPUnit from the PHAR:
wget https://phar.phpunit.de/phpunit-5.phar
chmod +x phpunit-5.7.26.phar
sudo mv phpunit-5.7.26.phar /usr/local/bin/phpunit
  • Verify the installation:
phpunit --version
PHPUnit 5.7.26 by Sebastian Bergmann and contributors.
  • Unit tests are integrated in Dokuwiki. To execute them:
cd /wherever/is/dokuwiki/_test
phpunit --group plugin_latexport
phpunit --group plugin_latexport --testdox

Change Log

FAQ

[discussions should ideally be deleted and turned into FAQ entries along the way]

Discussion

Could be placed on an external page (e.g. plugin:pluginname:discussion) to have a distinction between user comments and author docs

plugin/latexport.txt · Last modified: 2018-05-28 19:49 by Klap-in