diff options
| -rw-r--r-- | docutils/HISTORY.txt | 3 | ||||
| -rw-r--r-- | docutils/docutils/writers/latex2e/__init__.py | 36 | ||||
| -rw-r--r-- | docutils/test/functional/expected/latex_cornercases.tex | 4 | ||||
| -rw-r--r-- | docutils/test/functional/expected/latex_leavevmode.tex | 408 | ||||
| -rw-r--r-- | docutils/test/functional/expected/latex_memoir.tex | 20 | ||||
| -rw-r--r-- | docutils/test/functional/expected/standalone_rst_latex.tex | 20 | ||||
| -rw-r--r-- | docutils/test/functional/expected/standalone_rst_xetex.tex | 20 | ||||
| -rw-r--r-- | docutils/test/functional/input/latex_leavevmode.txt | 164 | ||||
| -rw-r--r-- | docutils/test/functional/tests/latex_leavevmode.py | 10 |
9 files changed, 649 insertions, 36 deletions
diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt index 7772d4ed2..ab63c0933 100644 --- a/docutils/HISTORY.txt +++ b/docutils/HISTORY.txt @@ -156,6 +156,9 @@ Version 0.17b1 is True. (This did happen when publishing from a doctree.) - Set PDF document properties from "meta" directive content. + + - Apply version of patch #176 "LaTeX writer: Append \leavevmode to + non-docinfo field names" by John Thorvald Wodder II. * docutils/writers/manpage.py diff --git a/docutils/docutils/writers/latex2e/__init__.py b/docutils/docutils/writers/latex2e/__init__.py index 1556d10bd..5f0aa1408 100644 --- a/docutils/docutils/writers/latex2e/__init__.py +++ b/docutils/docutils/writers/latex2e/__init__.py @@ -1577,6 +1577,30 @@ class LaTeXTranslator(nodes.NodeVisitor): def pop_output_collector(self): self.out = self.out_stack.pop() + def term_postfix(self, node): + """ + Return LaTeX code required between term or field name and content. + + In a LaTeX "description" environment (used for definition + lists and non-docinfo field lists), a ``\\leavevmode`` + between an item's label and content ensures the correct + placement of certain block constructs. + """ + for child in node: + if not isinstance(child, (nodes.Invisible, nodes.footnote, + nodes.citation)): + break + else: + return '' + if isinstance(child, (nodes.image)): + return '\\leavevmode\n' # Images get an additional newline. + if isinstance(child, (nodes.container, nodes.compound)): + return self.term_postfix(child) + if not isinstance(child, + (nodes.paragraph, nodes.math_block)): + return r'\leavevmode' + return '' + # Visitor methods # --------------- @@ -2130,7 +2154,8 @@ class LaTeXTranslator(nodes.NodeVisitor): pass def visit_field_body(self, node): - pass + if not isinstance(node.parent.parent, nodes.docinfo): + self.out.append(self.term_postfix(node)) def depart_field_body(self, node): if self.out is self.docinfo: @@ -2970,9 +2995,12 @@ class LaTeXTranslator(nodes.NodeVisitor): self.out.append('\\item[{') def depart_term(self, node): - # \leavevmode results in a line break if the - # term is followed by an item list. - self.out.append('}] \\leavevmode ') + self.out.append('}] ') + # Do we need a \leavevmode (line break if the field body begins + # with a list or environment)? + next_node = node.next_node(descend=False, siblings=True) + if not isinstance(next_node, nodes.classifier): + self.out.append(self.term_postfix(next_node)) def visit_tgroup(self, node): pass diff --git a/docutils/test/functional/expected/latex_cornercases.tex b/docutils/test/functional/expected/latex_cornercases.tex index bc9ef36af..5621bb156 100644 --- a/docutils/test/functional/expected/latex_cornercases.tex +++ b/docutils/test/functional/expected/latex_cornercases.tex @@ -437,7 +437,7 @@ cell 1, 2 } \begin{description} -\item[{definition:}] \leavevmode +\item[{definition:}] list \end{description} @@ -490,7 +490,7 @@ cell 1, 2 } \begin{description} -\item[{definition:}] \leavevmode +\item[{definition:}] list \end{description} diff --git a/docutils/test/functional/expected/latex_leavevmode.tex b/docutils/test/functional/expected/latex_leavevmode.tex new file mode 100644 index 000000000..57daf1349 --- /dev/null +++ b/docutils/test/functional/expected/latex_leavevmode.tex @@ -0,0 +1,408 @@ +\documentclass[a4paper]{article} +% generated by Docutils <http://docutils.sourceforge.net/> +\usepackage{cmap} % fix search and cut-and-paste in Acrobat +\usepackage{ifthen} +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\usepackage{alltt} +\usepackage{amsmath} +\usepackage{float} % extended float configuration +\floatplacement{figure}{H} % place figures here definitely +\usepackage{graphicx} +\setcounter{secnumdepth}{0} +\usepackage{longtable,ltcaption,array} +\setlength{\extrarowheight}{2pt} +\newlength{\DUtablewidth} % internal use in tables +\usepackage{tabularx} + +%%% Custom LaTeX preamble +% PDF Standard Fonts +\usepackage{mathptmx} % Times +\usepackage[scaled=.90]{helvet} +\usepackage{courier} + +%%% User specified packages and stylesheets + +%%% Fallback definitions for Docutils-specific commands + +% class handling for environments (block-level elements) +% \begin{DUclass}{spam} tries \DUCLASSspam and +% \end{DUclass}{spam} tries \endDUCLASSspam +\ifx\DUclass\undefined % poor man's "provideenvironment" + \newenvironment{DUclass}[1]% + {% "#1" does not work in end-part of environment. + \def\DocutilsClassFunctionName{DUCLASS#1} + \csname \DocutilsClassFunctionName \endcsname}% + {\csname end\DocutilsClassFunctionName \endcsname}% +\fi + +% Provide a length variable and set default, if it is new +\providecommand*{\DUprovidelength}[2]{ + \ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{} +} + +% abstract title +\providecommand*{\DUtitleabstract}[1]{\centerline{\textbf{#1}}} + +% admonition (specially marked topic) +\providecommand{\DUadmonition}[2][class-arg]{% + % try \DUadmonition#1{#2}: + \ifcsname DUadmonition#1\endcsname% + \csname DUadmonition#1\endcsname{#2}% + \else + \begin{center} + \fbox{\parbox{0.9\linewidth}{#2}} + \end{center} + \fi +} + +% width of docinfo table +\DUprovidelength{\DUdocinfowidth}{0.9\linewidth} + +% field list environment (for separate configuration of `field lists`) +\ifthenelse{\isundefined{\DUfieldlist}}{ + \newenvironment{DUfieldlist}% + {\quote\description} + {\enddescription\endquote} +}{} + +% numerical or symbol footnotes with hyperlinks and backlinks +\providecommand*{\DUfootnotemark}[3]{% + \raisebox{1em}{\hypertarget{#1}{}}% + \hyperlink{#2}{\textsuperscript{#3}}% +} +\providecommand{\DUfootnotetext}[4]{% + \begingroup% + \renewcommand{\thefootnote}{% + \protect\raisebox{1em}{\protect\hypertarget{#1}{}}% + \protect\hyperlink{#2}{#3}}% + \footnotetext{#4}% + \endgroup% +} + +% custom inline roles: \DUrole{#1}{#2} tries \DUrole#1{#2} +\providecommand*{\DUrole}[2]{% + \ifcsname DUrole#1\endcsname% + \csname DUrole#1\endcsname{#2}% + \else% + #2% + \fi% +} + +% line block environment +\DUprovidelength{\DUlineblockindent}{2.5em} +\ifthenelse{\isundefined{\DUlineblock}}{ + \newenvironment{DUlineblock}[1]{% + \list{}{\setlength{\partopsep}{\parskip} + \addtolength{\partopsep}{\baselineskip} + \setlength{\topsep}{0pt} + \setlength{\itemsep}{0.15\baselineskip} + \setlength{\parsep}{0pt} + \setlength{\leftmargin}{#1}} + \raggedright + } + {\endlist} +}{} + +% list of command line options +\providecommand*{\DUoptionlistlabel}[1]{\bfseries #1 \hfill} +\DUprovidelength{\DUoptionlistindent}{3cm} +\ifthenelse{\isundefined{\DUoptionlist}}{ + \newenvironment{DUoptionlist}{% + \list{}{\setlength{\labelwidth}{\DUoptionlistindent} + \setlength{\rightmargin}{1cm} + \setlength{\leftmargin}{\rightmargin} + \addtolength{\leftmargin}{\labelwidth} + \addtolength{\leftmargin}{\labelsep} + \renewcommand{\makelabel}{\DUoptionlistlabel}} + } + {\endlist} +}{} + +% informal heading +\providecommand*{\DUrubric}[1]{\subsubsection*{\emph{#1}}} + +% title for topics, admonitions, unsupported section levels, and sidebar +\providecommand*{\DUtitle}[2][class-arg]{% + % call \DUtitle#1{#2} if it exists: + \ifcsname DUtitle#1\endcsname% + \csname DUtitle#1\endcsname{#2}% + \else + \smallskip\noindent\textbf{#2}\smallskip% + \fi +} + +% titlereference standard role +\providecommand*{\DUroletitlereference}[1]{\textsl{#1}} + +% hyperlinks: +\ifthenelse{\isundefined{\hypersetup}}{ + \usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref} + \usepackage{bookmark} + \urlstyle{same} % normal text font (alternatives: tt, rm, sf) +}{} +\hypersetup{ + pdftitle={Styling of Elements in Definition- or Field-List}, + pdfauthor={Hänsel;Gretel} +} + +%%% Body +\begin{document} +\title{Styling of Elements in Definition- or Field-List% + \label{styling-of-elements-in-definition-or-field-list}} +\author{} +\date{} +\maketitle + +% Docinfo +\begin{center} +\begin{tabularx}{\DUdocinfowidth}{lX} +\textbf{Author}: & + Hänsel \\ +\textbf{Author}: & + Gretel \\ +\textbf{Address}: & + {\raggedright +123 Example Street\\ +Example, EX Canada } \\ +\textbf{Generic Docinfo List Field}: & +\begin{itemize} +\item This is a list. + +\item It does not require \texttt{\textbackslash{}leavevmode} because it is in the docinfo. +\end{itemize} +\\ +\end{tabularx} +\end{center} + +\begin{DUclass}{abstract} +\begin{quote} +\DUtitle[abstract]{Abstract} + +Test that \texttt{\textbackslash{}leavevmode} is inserted after the term or field-name +when required for correct placement of the item. +\end{quote} +\end{DUclass} + + +\section{Elements needing \texttt{\textbackslash{}leavevmode}% + \label{elements-needing-leavevmode}% +} + +\begin{DUfieldlist} +\item[{Bullet List:}]\leavevmode +\begin{itemize} +\item This is a bullet list nested in a field list. + +\item It needs \texttt{\textbackslash{}leavevmode} so that it will start on a new line +after the term. + +\item Without \texttt{\textbackslash{}leavevmode}, the first bullet would be on the same line as +the term, and the following bullets would not line up. +\end{itemize} + +\item[{Enumerated List:}]\leavevmode +\begin{enumerate} +\item This is an enumerated list. + +\item All lists need \texttt{\textbackslash{}leavevmode}. +\end{enumerate} + +\item[{Field List:}]\leavevmode +\begin{DUfieldlist} +\item[{Field List:}] +Like this one + +\item[{Needs \texttt{\textbackslash{}leavevmode}:}] +Yes +\end{DUfieldlist} + +\item[{empty:}]\end{DUfieldlist} + +\begin{description} +\item[{Definition List}] \leavevmode +\begin{description} +\item[{Nested}] +inside another definition list. + +\item[{Needs \texttt{\textbackslash{}leavevmode}?}] \leavevmode +\begin{description} +\item[{Yes.}] +Independent of the nesting level. + +\end{description} + +\end{description} + +\item[{Option List}] \leavevmode +\begin{DUoptionlist} +\item[-h] Show help + +\item[-v] Be verbose + +\item[-{}-rare] a) This description starts with an enumeration +c) but does not need \texttt{\textbackslash{}leavevmode}. +\end{DUoptionlist} + +\item[{Literal Block}] \leavevmode +\begin{quote} +\begin{alltt} +_needs_leavevmode = True +\end{alltt} +\end{quote} + +\item[{Doctest Block}] \leavevmode +\begin{quote} +\begin{alltt} +>>> needs_leavevmode(nodes.doctest_block) +True +\end{alltt} +\end{quote} + +\item[{Line Block}] \leavevmode +\begin{DUlineblock}{0em} +\item[] Needs “\texttt{\textbackslash{}leavevmode}”, +\item[] so that all lines start with the same indent. +\end{DUlineblock} + +\item[{Block Quote}] \leavevmode +% + +\begin{quote} +Block Quotes need “\texttt{\textbackslash{}leavevmode}”, too, +so that all lines start with the same indent. +\end{quote} + +\item[{Table}] \leavevmode +\setlength{\DUtablewidth}{\linewidth}% +\begin{longtable*}{|p{0.051\DUtablewidth}|p{0.051\DUtablewidth}|} +\hline + +1 + & +2 + \\ +\hline + +3 + & +4 + \\ +\hline +\end{longtable*} + +\item[{Figure}] \leavevmode +\begin{figure} +\noindent\makebox[\linewidth][c]{\includegraphics{../../../docs/user/rst/images/title.png}} +\caption{A figure} +\end{figure} + +\item[{Image}] \leavevmode + +\includegraphics{../../../docs/user/rst/images/title.png} + +\item[{Rubric}] \leavevmode +\DUrubric{A Rubric} + +\item[{Admonition}] \leavevmode +\DUadmonition[note]{ +\DUtitle[note]{Note} + +Admonitions need to be preceded by \texttt{\textbackslash{}leavevmode}. +Otherwise, the term ends up centered above the admonition box. + +So do \emph{System Messages}, as they use the “DUadmonition” +LaTeX environment. +} + +\end{description} + + +\section{Elements not needing \texttt{\textbackslash{}leavevmode}% + \label{elements-not-needing-leavevmode}% +} + +\begin{description} +\item[{Paragraph}] +Paragraphs don’t need \texttt{\textbackslash{}leavevmode}. They are meant +to start after the term and have a hanging indent. + +\begin{itemize} +\item Subsequent elements don’t need \texttt{\textbackslash{}leavevmode} either. +\end{itemize} + +\item[{Math Block}] % +\begin{equation*} +\sum_{i=1}^n i = \frac{n^2+n}{2} +\end{equation*} +LaTeX starts math blocks (both single-line and multiline) in a new +paragraph automatically, with or without \texttt{\textbackslash{}leavevmode}, so +\texttt{\textbackslash{}leavevmode} isn’t needed. + +\item[{Term with Classifier: classifier}] \leavevmode +\begin{itemize} +\item After a \emph{classifier}, \texttt{\textbackslash{}leavevmode} is not required. + +\item This holds for all elements that normally need \texttt{\textbackslash{}leavevmode}. +\end{itemize} + +\end{description} + + +\section{Ambiguous cases% + \label{ambiguous-cases}% +} + +\begin{description} +\item[{Comment and Target}] \leavevmode +% This is ignored. + +\begin{itemize} +\item Comments and other “Invisible” nodes (substitution definitions, +targets, pending) must be skipped when determining whether a +\texttt{\textbackslash{}leavevmode} is required. +\end{itemize} + +\item[{Substitution Definition and Class directive}] +\DUrole{test}{Is \texttt{\textbackslash{}leavevmode} required? Answer: No (because a paragraph follows).} + +\item[{Compound}] +\begin{DUclass}{compound} +\DUroletitlereference{Compound} and \DUroletitlereference{Container} wrap around other block elements. +They get a \texttt{\textbackslash{}leavevmode}, if the first nested element is a +list or similar. +\end{DUclass} + +\item[{Container}] \leavevmode +\begin{DUclass}{my-class} + +\begin{itemize} +\item This list inside a container requires a \texttt{\textbackslash{}leavevmode}. +\end{itemize} +\end{DUclass} + +\item[{Footnote}] % +\DUfootnotetext{f1}{f1}{1}{\phantomsection\label{f1}% +This footnote will move to the bottom of the page. +} + +A \texttt{\textbackslash{}leavevmode} is required, if the first list item value is a +footnote and a list or similar follows. + +\item[{Citation}] \leavevmode\begin{figure}[b]\raisebox{1em}{\hypertarget{example73}{}}[example73] +No Name, “Citations move to the bottom as well”, +Musterstadt, 1973. +\end{figure} + +\begin{itemize} +\item A \texttt{\textbackslash{}leavevmode} is required, if the first list item value is a +citation and a list or similar follows. +\end{itemize} + +\item[{Raw Block Text}] \leavevmode +“Raw” blocks are always preceded by +\verb|\leavevmode|, just in case. + +\end{description} + +\end{document} diff --git a/docutils/test/functional/expected/latex_memoir.tex b/docutils/test/functional/expected/latex_memoir.tex index 3cad8b6f0..60d64eeaf 100644 --- a/docutils/test/functional/expected/latex_memoir.tex +++ b/docutils/test/functional/expected/latex_memoir.tex @@ -464,18 +464,18 @@ Paragraph 2 of item 2. } \begin{description} -\item[{Term}] \leavevmode +\item[{Term}] Definition -\item[{Term}] \leavevmode (\textbf{classifier}) +\item[{Term}] (\textbf{classifier}) Definition paragraph 1. Definition paragraph 2. -\item[{Term}] \leavevmode +\item[{Term}] Definition -\item[{Term}] \leavevmode (\textbf{classifier one})(\textbf{classifier two}) +\item[{Term}] (\textbf{classifier one})(\textbf{classifier two}) Definition \end{description} @@ -1374,7 +1374,7 @@ list, \end{DUfieldlist} a paragraph, \begin{description} -\item[{a definition}] \leavevmode +\item[{a definition}] list, \end{description} @@ -1840,7 +1840,7 @@ with the \emph{wave function} $\Psi $, describes how the quantum state of a physical system changes in time. \begin{description} -\item[{Math-Accents:}] \leavevmode +\item[{Math-Accents:}] \leavevmode \setlength{\DUtablewidth}{\linewidth}% \begin{longtable*}{p{0.315\DUtablewidth}p{0.315\DUtablewidth}p{0.315\DUtablewidth}} @@ -2188,7 +2188,7 @@ is contained in a quote \end{quote} \begin{description} -\item[{In a definition list:}] \leavevmode +\item[{In a definition list:}] \leavevmode \begin{DUoptionlist} \item[-{}-help] show help @@ -2646,10 +2646,10 @@ Compare the items in the following lists: \end{itemize} \begin{description} -\item[{simple}] \leavevmode +\item[{simple}] description term -\item[{{[}bracketed{]}}] \leavevmode +\item[{{[}bracketed{]}}] description term \end{description} @@ -2719,7 +2719,7 @@ Long URLs should be wrapped in the PDF. This can be achieved with the (name) of a reference node equals the link URL. \begin{description} -\item[{Example:}] \leavevmode +\item[{Example:}] a long URL that should wrap in the output \url{http://docutils.sourceforge.net/docs/user/latex.html\#id79} diff --git a/docutils/test/functional/expected/standalone_rst_latex.tex b/docutils/test/functional/expected/standalone_rst_latex.tex index 95a45b359..24387c141 100644 --- a/docutils/test/functional/expected/standalone_rst_latex.tex +++ b/docutils/test/functional/expected/standalone_rst_latex.tex @@ -468,18 +468,18 @@ Paragraph 2 of item 2. } \begin{description} -\item[{Term}] \leavevmode +\item[{Term}] Definition -\item[{Term}] \leavevmode (\textbf{classifier}) +\item[{Term}] (\textbf{classifier}) Definition paragraph 1. Definition paragraph 2. -\item[{Term}] \leavevmode +\item[{Term}] Definition -\item[{Term}] \leavevmode (\textbf{classifier one})(\textbf{classifier two}) +\item[{Term}] (\textbf{classifier one})(\textbf{classifier two}) Definition \end{description} @@ -1378,7 +1378,7 @@ list, \end{DUfieldlist} a paragraph, \begin{description} -\item[{a definition}] \leavevmode +\item[{a definition}] list, \end{description} @@ -1844,7 +1844,7 @@ with the \emph{wave function} $\Psi $, describes how the quantum state of a physical system changes in time. \begin{description} -\item[{Math-Accents:}] \leavevmode +\item[{Math-Accents:}] \leavevmode \setlength{\DUtablewidth}{\linewidth}% \begin{longtable*}{p{0.315\DUtablewidth}p{0.315\DUtablewidth}p{0.315\DUtablewidth}} @@ -2192,7 +2192,7 @@ is contained in a quote \end{quote} \begin{description} -\item[{In a definition list:}] \leavevmode +\item[{In a definition list:}] \leavevmode \begin{DUoptionlist} \item[-{}-help] show help @@ -2650,10 +2650,10 @@ Compare the items in the following lists: \end{itemize} \begin{description} -\item[{simple}] \leavevmode +\item[{simple}] description term -\item[{{[}bracketed{]}}] \leavevmode +\item[{{[}bracketed{]}}] description term \end{description} @@ -2723,7 +2723,7 @@ Long URLs should be wrapped in the PDF. This can be achieved with the (name) of a reference node equals the link URL. \begin{description} -\item[{Example:}] \leavevmode +\item[{Example:}] a long URL that should wrap in the output \url{http://docutils.sourceforge.net/docs/user/latex.html\#id79} diff --git a/docutils/test/functional/expected/standalone_rst_xetex.tex b/docutils/test/functional/expected/standalone_rst_xetex.tex index 4bbb8b940..bed8f2718 100644 --- a/docutils/test/functional/expected/standalone_rst_xetex.tex +++ b/docutils/test/functional/expected/standalone_rst_xetex.tex @@ -327,18 +327,18 @@ Paragraph 2 of item 2. } \begin{description} -\item[{Term}] \leavevmode +\item[{Term}] Definition -\item[{Term}] \leavevmode (\textbf{classifier}) +\item[{Term}] (\textbf{classifier}) Definition paragraph 1. Definition paragraph 2. -\item[{Term}] \leavevmode +\item[{Term}] Definition -\item[{Term}] \leavevmode (\textbf{classifier one})(\textbf{classifier two}) +\item[{Term}] (\textbf{classifier one})(\textbf{classifier two}) Definition \end{description} @@ -1261,7 +1261,7 @@ list, \end{DUfieldlist} a paragraph, \begin{description} -\item[{a definition}] \leavevmode +\item[{a definition}] list, \end{description} @@ -1728,7 +1728,7 @@ with the \emph{wave function} $\Psi $, describes how the quantum state of a physical system changes in time. \begin{description} -\item[{Math-Accents:}] \leavevmode +\item[{Math-Accents:}] \leavevmode \setlength{\DUtablewidth}{\linewidth}% \begin{longtable*}{p{0.315\DUtablewidth}p{0.315\DUtablewidth}p{0.315\DUtablewidth}} @@ -2076,7 +2076,7 @@ is contained in a quote \end{quote} \begin{description} -\item[{In a definition list:}] \leavevmode +\item[{In a definition list:}] \leavevmode \begin{DUoptionlist} \item[--help] show help @@ -2534,10 +2534,10 @@ Compare the items in the following lists: \end{itemize} \begin{description} -\item[{simple}] \leavevmode +\item[{simple}] description term -\item[{{[}bracketed{]}}] \leavevmode +\item[{{[}bracketed{]}}] description term \end{description} @@ -2607,7 +2607,7 @@ Long URLs should be wrapped in the PDF. This can be achieved with the (name) of a reference node equals the link URL. \begin{description} -\item[{Example:}] \leavevmode +\item[{Example:}] a long URL that should wrap in the output \url{http://docutils.sourceforge.net/docs/user/latex.html\#id79} diff --git a/docutils/test/functional/input/latex_leavevmode.txt b/docutils/test/functional/input/latex_leavevmode.txt new file mode 100644 index 000000000..618c8950e --- /dev/null +++ b/docutils/test/functional/input/latex_leavevmode.txt @@ -0,0 +1,164 @@ +Styling of Elements in Definition- or Field-List +================================================ + +:Authors: Hänsel, Gretel +:Address: 123 Example Street + Example, EX Canada +:Generic Docinfo List Field: + - This is a list. + - It does not require ``\leavevmode`` because it is in the docinfo. +:Abstract: + Test that ``\leavevmode`` is inserted after the term or field-name + when required for correct placement of the item. + +Elements needing ``\leavevmode`` +******************************** + +:Bullet List: + - This is a bullet list nested in a field list. + - It needs ``\leavevmode`` so that it will start on a new line + after the term. + - Without ``\leavevmode``, the first bullet would be on the same line as + the term, and the following bullets would not line up. + +:Enumerated List: + 1. This is an enumerated list. + 2. All lists need ``\leavevmode``. + +:Field List: + :Field List: Like this one + :Needs ``\leavevmode``: Yes + +:empty: + +Definition List + Nested + inside another definition list. + Needs ``\leavevmode``? + Yes. + Independent of the nesting level. + +Option List + -h Show help + -v Be verbose + --rare a) This description starts with an enumeration + c) but does not need ``\leavevmode``. + +Literal Block + :: + + _needs_leavevmode = True + +Doctest Block + >>> needs_leavevmode(nodes.doctest_block) + True + +Line Block + | Needs "``\leavevmode``", + | so that all lines start with the same indent. + +Block Quote + .. + + Block Quotes need "``\leavevmode``", too, + so that all lines start with the same indent. + +Table + +---+---+ + | 1 | 2 | + +---+---+ + | 3 | 4 | + +---+---+ + +Figure + .. figure:: ../../../docs/user/rst/images/title.png + + A figure + +Image + .. image:: ../../../docs/user/rst/images/title.png + +Rubric + .. rubric:: A Rubric + +Admonition + .. note:: + + Admonitions need to be preceded by ``\leavevmode``. + Otherwise, the term ends up centered above the admonition box. + + So do *System Messages*, as they use the "DUadmonition" + LaTeX environment. + + +Elements not needing ``\leavevmode`` +************************************ + +Paragraph + Paragraphs don't need ``\leavevmode``. They are meant + to start after the term and have a hanging indent. + + * Subsequent elements don't need ``\leavevmode`` either. + +Math Block + .. math:: + + \sum_{i=1}^n i = \frac{n^2+n}{2} + + LaTeX starts math blocks (both single-line and multiline) in a new + paragraph automatically, with or without ``\leavevmode``, so + ``\leavevmode`` isn't needed. + +Term with Classifier: classifier + - After a *classifier*, ``\leavevmode`` is not required. + - This holds for all elements that normally need ``\leavevmode``. + +Ambiguous cases +*************** + +Comment and Target + .. This is ignored. + + .. _foo: + + * Comments and other "Invisible" nodes (substitution definitions, + targets, pending) must be skipped when determining whether a + ``\leavevmode`` is required. + +Substitution Definition and Class directive + .. |no-leavevmode| replace:: No (because a paragraph follows). + + .. class:: test + + Is ``\leavevmode`` required? Answer: |no-leavevmode| + +Compound + .. compound:: + + `Compound` and `Container` wrap around other block elements. + They get a ``\leavevmode``, if the first nested element is a + list or similar. + +Container + .. container:: my-class + + * This list inside a container requires a ``\leavevmode``. + +Footnote + .. [#f1] This footnote will move to the bottom of the page. + + A ``\leavevmode`` is required, if the first list item value is a + footnote and a list or similar follows. + +Citation + .. [example73] No Name, "Citations move to the bottom as well", + Musterstadt, 1973. + + * A ``\leavevmode`` is required, if the first list item value is a + citation and a list or similar follows. + +Raw Block Text + .. raw:: latex + + “Raw” blocks are always preceded by + \verb|\leavevmode|, just in case. diff --git a/docutils/test/functional/tests/latex_leavevmode.py b/docutils/test/functional/tests/latex_leavevmode.py new file mode 100644 index 000000000..64ec4a72a --- /dev/null +++ b/docutils/test/functional/tests/latex_leavevmode.py @@ -0,0 +1,10 @@ +# Source and destination file names. +test_source = "latex_leavevmode.txt" +test_destination = "latex_leavevmode.tex" + +# Keyword parameters passed to publish_file. +writer_name = "latex" + +# Settings +# use "smartquotes" transition: +settings_overrides['smart_quotes'] = True |