====== latexport Plugin ======

---- plugin ----
description: A latex export renderer plugin to export latex documents from DokuWiki
author     : Jean-Michel Gonet
email      : jmgonet@yahoo.com
type       : render
lastupdate : 2020-08-15
compatible : Hogfather, Frusterick Manners, Greebo
depends    : 
conflicts  : 
similar    : latexit, dokutexit
tags       : latex, export, ebook

downloadurl: https://github.com/jean-michel-gonet/dokuwiki-plugin-latexport/archive/1.0.6.zip
bugtracker : https://github.com/jean-michel-gonet/dokuwiki-plugin-latexport/issues
sourcerepo : https://github.com/jean-michel-gonet/dokuwiki-plugin-latexport
donationurl: 

screenshot_img : https://github.com/jean-michel-gonet/dokuwiki-plugin-latexport/releases/download/1.0.0/IMG_20180426_102920.jpg
----

===== 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 [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

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

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

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__:
  * [[plugin:mathjax|MathJax Plugin]]: To edit mathematical expressions.
  * [[plugin:anchor|Anchor Plugin]]: To refer to any place in the text. However, you need a small modification to it, described below.

==== Hacking anchor ====
For the anchor plugin to render nicely with latexport, you need to execute a small hack:

  * Install Anchor using the configuration manager.
  * With any text editor, look for the main _Anchor_ plugin file, which is in ''dokuwiki/lib/plugins/anchor/syntax.php''.
  * Change the ''render'' function as follows:

<code php>
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>';			
    }
}
</code>

===== Using the plugin to export pages as latex =====

After installing the plugin, export one page by calling an url as follows:
  * %%http://xxx.yyy.com/path/to/my_page?do=export_latexport_tex%%

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 [[https://tug.org/texlive/|TeX Live]], which provides a fully functional, ready to use, well configured TeX engine. It exists for almost all platforms (specific installers for MacOS and Windows are mentioned there)

==== 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:<code bash>
cd working_folder
curl -o content.zip "http://www.xxx.yyy/path/to/my_page?do=export_latexport_tex"
</code>
  * Unzip the archive into a destination folder, either with your favorite application, or using command line:<code bash>
mkdir content
unzip content.zip -d content/
</code>
  * 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:<code latex>
\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}
</code>
  * 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):<code bash>
cd working_folder
lualatex root.tex
lualatex root.tex
</code>
  * 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 [[plugin:latexport:structuring-latex-documents|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.

<code dokuwiki>
===== 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.]]
</code>

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:

<code dokuwiki>
====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.
</code>

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

<code dokuwiki>
====A heading====
Bla bla bla For more information see [[path:to:the:other:page]]. 
Bla bla bla.
Bla bla bla
</code>

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

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

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

<code dokuwiki>
====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}}
</code>

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:

<code dokuwiki>
{{ :path:to:image.png |Caption}}
</code>

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.

<code dokuwiki>
{{ :path:to:image1.png |Caption}} {{ :path:to:image2.png |Caption}}
</code>

==== External links ====

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:

<code dokuwiki>
Visit this nice web page: [[https://fr.wikipedia.org/wiki/Convertisseur_analogique-numérique]]
</code>

  * The following link will pose problems:
<code dokuwiki>
Visit this nice web page: [[https://fr.wikipedia.org/wiki/Convertisseur_analogique-num%C3%A9rique]]
</code>

==== Writing mathematical expressions ====

Use the [[plugin:mathjax|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 dokuwiki>
<code pascal>
Program HelloWorld(output);
begin
  writeln('Hello, world!');
end.
</code>
</code>

This is exported to TeX as:

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

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:

<code latex>
\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},   
}
</code>

See more information here:
  * https://en.wikibooks.org/wiki/LaTeX/Source_Code_Listings
  * https://en.wikibooks.org/wiki/LaTeX/Colors

==== Using system fonts ====

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

<code latex>
\usepackage{fontspec}
\setmainfont{Lucida Bright}
</code>

To know the name of the font:

  - Open the Font Book
  - Locate your desired font
  - Right click on it, and select Show in Finder
  - Right click on the file and click on Get Info
  - Copy the path to the font file, open a console, and type:

<code bash>
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
</code>

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.
<code bash>
git checkout https://github.com/splitbrain/dokuwiki.git
git checkout stable
</code>

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:
<code bash>
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
</code>

  * Verify the installation:
<code bash>
phpunit --version
PHPUnit 5.7.26 by Sebastian Bergmann and contributors.
</code>

  * Unit tests are integrated in Dokuwiki. To execute them:

<code bash>
cd /wherever/is/dokuwiki/_test
phpunit --group plugin_latexport
phpunit --group plugin_latexport --testdox
</code>

=== Change Log ===

{{rss>https://github.com/jean-michel-gonet/dokuwiki-plugin-latexport/releases.atom}}


===== 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//