Notes sur la conversion RST vers LaTeX/PDF

Dans ce document, le script permettant de lancer la conversion est baptisé rst2latex.py (voir ci-dessus).

Commande sous Linux :

rst2latex.py rst_doc.txt rst_doc.tex

Commande sous Linux :

pdflatex rst_doc.tex

ou :

pdftex rst_doc.tex

Dans les deux cas, vous obtenez un fichier rst_doc.pdf.

Latex2e.py propose deux options :

Par défaut, Latex-Writer produit un fichier LaTeX permettant l'incorporation d'une feuille de styles style.tex. Cette feuille doit se trouver dans le même répertoire que le document source.

On peut y ajouter toute une série de macro et autres personnalisations.

Le contenu de style.tex sera inséré par la balise \input{style.tex} lors de la conversion du document LaTeX vers d'autres format.

Voici le préambule du document LaTeX :

\documentclass[10pt]{article}
\usepackage{babel}
\usepackage{shortvrb}
\usepackage[latin1]{inputenc}
\usepackage{tabularx}
\usepackage{longtable}
\setlength{\extrarowheight}{2pt}
\usepackage{amsmath}
\usepackage{graphicx}
\usepackage{color}
\usepackage{multirow}
\usepackage[colorlinks,linkcolor=blue]{hyperref}
\usepackage[a4paper,margin=2cm,nohead]{geometry}
%% generator Docutils: http://docutils.sourceforge.net/
\newlength{\admwidth}
\addtolength{\admwidth}{0.9\textwidth}
\newcommand{\optionlistlabel}[1]{\bf #1 \hfill}
\newenvironment{optionlist}[1]
{\begin{list}{}
  {\setlength{\labelwidth}{#1}
   \setlength{\rightmargin}{1cm}
   \setlength{\leftmargin}{\rightmargin}
   \addtolength{\leftmargin}{\labelwidth}
   \addtolength{\leftmargin}{\labelsep}
   \renewcommand{\makelabel}{\optionlistlabel}}
}{\end{list}}
% begin: floats for footnotes tweaking.
\setlength{\floatsep}{0.5em}
\setlength{\textfloatsep}{\fill}
\addtolength{\textfloatsep}{3em}
\renewcommand{\textfraction}{0.5}
\renewcommand{\topfraction}{0.5}
\renewcommand{\bottomfraction}{0.5}
\setcounter{totalnumber}{50}
\setcounter{topnumber}{50}
\setcounter{bottomnumber}{50}
% end floats for footnotes
\input{style.tex} <================== STYLE.TEX

\title{Conversion reStructuredText vers Docbook}
\author{}
\date{}
\hypersetup{
pdftitle={Conversion reStructuredText vers Docbook},
pdfauthor={Éric Bellot}
}
\raggedbottom
\begin{document}
......[coupé]

On peut modifier certains paramètres grâce à la feuille style.tex. Toutefois, certains d'entre eux ne peuvent être modifiés qu'en intervenant directement dans le script Latex2e.py... ce qui n'est pas élégant.

On trouve, par exemple, dans la classe LaTeXTranslator du script un certain nombre de paramètres :

d_class = 'article'    # document.settings.stylesheet
d_options = '10pt'  # papersize, fontsize
d_paper = 'a4paper'
d_margins = '2cm'
d_stylesheet_path = '~/texmf/style.tex'
# for pdflatex some other package. pslatex

On peut les modifier pour obtenir un document LaTeX à son goût.

Voici mes personalisations :

d_class = 'article'
d_options = '11pt'   <=================================== ICI
d_paper = 'a4paper'
d_margins = '2.5cm'   <================================== ICI
d_stylesheet_path = '/home/ebellot/texmf/style.tex'  <=== ET LÀ

Ce module est fournit en standard avec les distributions. Toutefois, il ne fournit pas autant de fonctionnalités que le module Frenchle (voir plus bas)

Modifiez le script Latex2e.py pour ajouter le nom du paquetage de francisation de LaTeX (french).

Dans le début du script ajoutez la ligne suivante à la variable _ISO639_TO_BABEL :

'fr': 'french',

Vous devez obtenir quelque chose comme :

_ISO639_TO_BABEL = {
    'fr': 'french',
    'no': 'norsk',
    'gd': 'scottish',
    .....

Cela permettra de modifier la balise \documentclass du fichier LaTeX :

\documentclass[10pt,french]{article}
                 _____^

On peut, plus simplement ajouter la ligne suivante dans la feuille de styles :

\usepackage{french}

Il suffit alors de réaliser la conversion en ajoutant l'otion -l fr dans la ligne de commande :

rst2latex.py -l fr rst_doc.txt rst_doc.tex

Par défaut, les fontes sont embarquées au format Bitmap dans le PDF. L'impression est déplorable et lente. On peut utiliser les fontes Almost European et l'extension Aeguill ("guillemets pour AE"), les fontes sont vectorielles donc beaucoup plus légères ^[1]. Pour cela, on ajoute la ligne suivante dans le fichier style.tex :

\usepackage[ae]{aeguill}

Possible title underline, too short for the title. Treating it as ordinary text because it's so short.

On peut aussi utiliser les fontes AE sans le paquetage des guillemets :

\usepackage{ae}

L'impression devient rapide et la sortie est superbe.

Au lieu d'embarquer les fontes dans le documents -- c'est lourd --, on peut utiliser les fontes Postscript d'Adobe (Times, etc.). Tous les lecteurs PDF les supportent par défaut.

Possible title underline, too short for the title. Treating it as ordinary text because it's so short.

Il suffit de saisir la balise suivante dans le fichier style.tex :

\usepackage{times}

On aura soin de retirer la ligne concernant les fontes AE, par exemple en la commentant :

%\usepackage{ae}

Résultat : un fichier PDF de 77 Ko avec les fontes AE ne fait plus que 24 Ko avec le paquetage Times.

L'économie à un prix. Le fichier obtenu est typographiquement beaucoup moins élégant...

J'ai testé pas mal de paquetages Eurosym, Eurosans, etc. Toutefois, c'est avec le paquetage standard Marvosym que j'ai obtenu les meilleurs résultats.

En effets, les autres posent des problèmes lors de la conversion au format PDF avec PDFLatex. Soit la conversion plante pour des raisons ésotériques et fastidieuses à résoudre (fontes manquantes, encodage incorrect, etc.), soit c'est le fichier produit qui fonctionne mal avec les lecteurs PDF courants : XPDF, KGhostView et Acrobat Reader 4.05 ^[2].

Avec le paquetage Marvosym, pas de problème. Mieux, il est présent en standard dans les distributions.

Un lien du type http://www.domain.org/index.htm#ancre produira une erreur lors de la conversion LaTeX => PDF. C'est le "#" qui ne passe pas.

Problème résolu. Il faut modifier le script Latex2e.py dans la fonction visit_reference en rajoutant un slash devant le "#" :

Lorsqu'on place deux tirets successifs dans un literal inline, les tirets sont convertis en un tiret long dans la sortie. Par exemple, le double-tiret disparaît du code --use-latex-toc=1 alors qu'il est correctement conservé dans un bloc litéral :

--use-latex-toc=1

Ce comportement est souhaitable dans le texte courant mais regrettable dans du code.

Latex-Writer convertit les literaux inline avec la balise testtt{...} alors que l'utilisation du mode verbatim serait peut-être préférable \verb|...|.

Ce problème ne se pose qu'avec l'encodage T1 (et AE qui l'utilise).

Seules les options --use-latex-toc et --footnote-references sont pour l'instant fonctionnelles. Consulter le latex2e BUGS TODOS and other animals pour plus de détail sur l'avancement du projet.