Extension:Wiki2LaTeX/Documentation

From MediaWiki.org
Jump to: navigation, search

Wiki2LaTeX is a wiki-to-LaTeX converter. There are two major aspects to conversion: the wiki-to-LaTeX conversion itself, and the use of templates, which specify the formatting of the LaTeX document.

A large number of wiki markups are converted by Wiki2LaTeX. For example if the wiki document contains '''bold''', then this converts to \textbf{bold}, producing bold in the final LaTeX document. However, more complicated elements like tables, images and mathematics require more care in how the wiki markup is entered so that it will be converted to LaTeX in a way that produces nice-looking results. In addition, there are special tags specifically for LaTeX, for example, the <newpage/> creates a new page in the LaTeX document, which has no meaning in the wiki.

LaTeX templates are the way to specify the preamble of the LaTeX document. Wiki2LaTeX has a default "Magic" template, and additional custom templates may be created on the wiki.

Compatible Wiki Markup[edit]

Most basic wiki markup is correctly converted to LaTeX by Wiki2LaTeX, including the following:

  • '''bold'''
  • ''italics''
  • * bullet list
  • # numbered list
  • <br/>
  • <nowiki></nowiki>
  • preformat (with leading space)
  • <tt></tt>
  • <pre></pre>
  • <math></math>
  • <center></center>
  • <big></big>
  • <small></small>
  • <blockquote></blockquote>
  • == Level 1 ==
  • === Level 2===
  • ==== Level 3====
  • ===== Level 4=====
  • ====== Level 5======

Additional Capabilities[edit]

  • Tables can be included, but require special handling. Tables.
  • Images may be included, but only filetypes that pdflatex accepts.
  • Typesetting mathematics may be done, although equation arrays are difficult [1]
  • Wiki templates, those of the form {{MyTemplate}}
  • Prefix a section heading with a asterisk for unnumbered sections: == *Section Name ==

LaTeX Templates[edit]

Wiki2LaTeX allows the creation of custom LaTeX templates to control the formatting of the LaTeX document. Once custom templates have been created, they may be selected just before the LaTeX is compiled. The custom template specifies the content the the LaTeX preamble, that is, everything between \documentclass and \begin{document}.

A template is a page in the custom namespace LaTeX. Here is an example:

==LaTeX-Template==
<latexfile name="Main">
\documentclass[12pt, a4paper]{scrartcl}
\usepackage[utf8x]{inputenc} % This is very important!
\usepackage[T1]{fontenc}
\usepackage{tabularx} % Required for tables
\title{((PAGENAME))}
\begin{document}
((W2L_CONTENT))
\end{document}
</latexfile>

If this page has the name LaTeX:W2L_My Template then "My Template" will appear in the drop-down menu in the latex/pdf conversion page.

Various variables can be included in the template, the most important one is WikiContent or W2L_CONTENT which is replaced with the LaTeX-formatted content. In addition, PAGENAME can be used for the page title, as well other variables such as CURRENTYEAR, see magic words for more information.

Custom Template Variables[edit]

Custom template variables are defined on the wiki page, and referred to by the LaTeX template. For example, if the wiki page contains the following:

<templatevar vname="left">This is the left \LaTeX{} header</templatevar>
<templatevar vname="right">This is the right</templatevar>

and if the LaTeX template contains:

\pagestyle{myheadings}
\markboth{((left))}{((right))}

then headers will appear. Note that the custom variable may contain LaTeX markup, but wiki markup is ignored.

The variable names will appear in the wiki as:

left: This is the left \LaTeX{} header
right: This is the right

Wiki to LaTeX Conversion Summary[edit]

If you type this wiki.... ... you get this LaTeX ... which looks like
'''bold''' 
 <b>bold</b> 
 <strong>bold</strong> 

\textbf{bold}

bold

''italics'' 
 <i>italics</i> 
 <em>italics</strong></em>

\textit{italics}

italics

==Level 1==
===Level 2 ===
==== Level 3 ====

\section{Level 1}

\subsection{Level 2}

\subsubsection{Level 3}

OR

\chapter{Level 1}

\section{Level 2}

\subsection{Level 3}

<pre>''ignores''</pre> 

\begin{verbatim}

''ignore''

\end{verbatim}

''ignore''

List of bullets:
* First Bullet
* Second Bullet

A list of bullets:

\begin{itemize}

\item First Bullet

\item Second Bullet

\end{itemize}

List of bullets:

  • First Bullet
  • Second Bullet
Numbered list:
# First entry
# Second entry

Numbered list:

\begin{enumerate}

\item First entry

\item Second entry

\end{enumerate}

Numbered list:

  1. First entry
  2. Second entry
<nowiki>ignore 
 '''markup'''</nowiki>

ignore '''markup'''

line one <br/> line two

line one \\ line two

Use no spaces in <br/>. Mediawiki accepts <br /> with a space, but Wiki2LaTeX does not.

line one

line two

<math>e^{\pi i} = -1</math>.

\begin{math}

e^{\pi i} = -1

\end{math}.

.

<center>middle</center>

\begin{center}

middle

\end{center}

middle
<big>Text</big>

{\large

Text

}

Text

<small>Text</small>

{\small

Text

}

Text

[[Image:blocks.pdf | 
 15cm  | A figure of 
 some blocks.]]
\begin{center}

\resizebox{15cm}{!}{\includegraphics{/absolute/path/wiki/images/0/00/blocks.pdf}}\\ \textit{A figure of some blocks.} \end{center}

Conversions are performed by w2lParser.php. Please refer to the source code for further details.

Refer to Mediawiki help for a good list of wiki markups.

LaTeX-Specific Tags[edit]

Wiki2LaTeX adds wiki tags which are intended for LaTeX-export specifically.

Function wiki markup LaTeX Display in wiki

Do not indent paragraph

<noindent/>

{\noindent}

Nothing displayed

Start new page

<newpage/>

\clearpage{}


Raw LaTeX

<rawtex>{\tiny Little}</rawtex>

{\tiny Little}

{\tiny Little}

Labels and reference

<label>labelname</label>
<chapref>labelname</chapref>
<pageref>labelname</pageref>

\label{labelname}

\ref{labelname}

\page{labelname}

(Anker: name-of-label)

X.Y

S. XX

An example of using labels, in wiki is:

== Introduction <label>intro</label> ==
Section <chapref>intro</chapref> is the introduction, found on page <pageref>intro</pageref>.
It appears that <pageref> does not work because Wiki2LaTeX incorrectly translates <pageref> to \page instead of \pageref.

Wiki Markup Which Converts Different Than Expected[edit]

If you type this wiki.... ... you instead find out that
_preformat with a space

Converts to \begin{verbatim} without formatting; MediaWiki converts with formatting.

Use <pre> tag for more consistent conversion.

Wiki Markup Which Does Not Convert[edit]

Wiki2LaTeX does not convert some wiki markup, or does not convert the same way that MediaWiki does.

If you type this wiki.... ... you instead find out that
<u>underline</u>
<del>strikethrough</del>
<s>strikethrough</s>
<code>code</code>

Literally "<u>underline</u>" etc. will appear in the LaTeX source. Underline and strikethrough are not native to Latex, requiring separate packages, so this limitation is not surprising. However, Wiki2LaTeX's lack of support for <code> is surprising.

 <!-- a comment -->
Comments are not passed to LaTeX.

Advanced Topics[edit]

Here are some advanced topics:

Customizations[edit]

Various aspects of wiki2latex may be customized.

Change the default template[edit]

Normally, the "Magic" template is the default. Change the default selection to "My Tempate" by adding a line to w2lConfig.php

$w2lConfig['default_template'] = 'My Template';

Change the default-template or action on a per-article-basis[edit]

Adding a line like this to your w2lConfig.php-file adds the ability to choose template and action.

$w2lConfig['defaults'][] = array('search' => 'String to search', 'template'=>'Template', 'action'=>'w2lpdf');

Description:

  • 'search' => 'String to search': The string to search for in the title of the Wiki-Article. It is matched as spelled.
  • 'template'=>'Template': Replace 'Template' with your chosen template. You can choose any Template, that shows up in your template-box. Just pick the name (which in detail is: Wiki-Template-Pagename without W2L_). You can choose 'empty' to use a completely empty template. This only gives nice results, if your wiki-page contains a complete LaTeX-document head.
  • 'action'=>'w2lpdf': Pick the pre-selected action. You can choose between w2lpdf, w2ltextarea or w2ltex.

Please note: This feature has been integrated a long time ago and works. Be sure to fill out all three parameters, otherwise you might experience unexpected behaviour.