CODEWITHSUNDEEP
latexpdf-generationpython-sphinxline-breaksrestructuredtext
etherpunk
etherpunk

Reputation: 43

How to render LaTeX/PDF with a forced line break on a definition list in reStructuredText

I want to render a pdf file in reStructuredText with a proper line break, such that:

Keyword
    Definition

This renders correctly with a Read the Docs template, but it doesn't produce the line break when using default settings and make latexpdf. Is there a simple function I can apply to the LaTeX output options in conf.py for this issue?

Note: I already submitted this question on TeX and was told to try Stack Overflow. The snippet above should be the shortest code required to reproduce my use case. As I said, these are the default settings as far as I know. I haven't made any significant changes. The lack of line break over definition lists seems to be the intended output for LaTeX pdf files.

Upvotes: 2

Views: 1689

Answers (3)

user4184837
user4184837

Reputation:

You can achieve that with a substitution to inject raw LaTeX code.

Keyword
    |br| Definition

Keyword2
    |br| Long definition long definition long definition long definition long
    definition long definition long definition long definition long definition
    long definition long definition long definition long definition long
    definition long definition long definition long definition long definition
    long definition long definition long definition long definition long
    definition long definition long definition


.. |br| raw:: latex

        \mbox{}\newline

This produces in PDF:

enter image description here

Note that the raw LaTeX code is not injected into other targets, only the latexpdf target.

Upvotes: 1

Brecht Machiels
Brecht Machiels

Reputation: 3410

Using the rinohtype PDF builder for Sphinx allows for fine control of style aspects such as these. The default style sheet actually inserts line breaks between a keyword and its definition in definition lists. Otherwise the style of the produced PDF is very similar to the output of the LaTeX builder. You can create your own style sheet and template configuration to customize the look of the PDF to your needs.

(Full disclosure: I am the author of rinohtype)

Upvotes: 3

Steve Piercy
Steve Piercy

Reputation: 15055

Here's a partial answer, to the limit of my knowledge. I hope it gets you further along.

By default the conversion applies a bold style to the term, and the definition of the term is inline with the term and line wraps with an indent on subsequent lines. See screenshot below for example output from the PDF for Pyramid documentation.PDF for Pyramid documentation

When you do make latexpdf you invoke two processors in succession, converting reST files to a LaTeX file, then running those files through pdflatex to generate the PDF.

Here's what appears for the first glossary entry in pyramid.tex for the first step:

\item[{ACE\index{ACE|textbf}}] \leavevmode\phantomsection\label{\detokenize{glossary:term-ace}}
An \sphinxstyleemphasis{access control entry}.  An access control entry is one element
in an {\hyperref[\detokenize{glossary:term-acl}]{\sphinxtermref{ACL}}}.  An access control entry is a three-tuple that
describes three things: an \sphinxstyleemphasis{action} (one of either \sphinxcode{Allow} or
\sphinxcode{Deny}), a {\hyperref[\detokenize{glossary:term-principal}]{\sphinxtermref{principal}}} (a string describing a user or
group), and a {\hyperref[\detokenize{glossary:term-permission}]{\sphinxtermref{permission}}}.  For example the ACE, \sphinxcode{(Allow,
'bob', 'read')} is a member of an ACL that indicates that the
principal \sphinxcode{bob} is allowed the permission \sphinxcode{read} against the
resource the ACL is attached to.

The question now boils down to how to change that output so that it can be styled as you desire. And for that, you'll need to parse through the Sphinx documentation on LaTeX customization. How to do that is beyond my knowledge.

Upvotes: 1

Related Questions