[Doc-SIG] Generating customized LaTeX?

[Felix Wiemann]

Dinu Gherman wrote:

> I'm working on a project where I'd greatly benefit from generating
> customized LaTeX from ReST, mainly for using existing LaTeX macros,
> basically for stuff like itemized lists, tables, figures, and code
> listings.
>
> After briefly sniffing into docutils 0.4 I found a "newlatex2e"
> writer, which makes me wonder if this would be a better start than
> the older "latex2e" one?

Yes and no.

The new LaTeX writer uses LaTeX macros for almost everything, so you
customize most things by adding code to the user stylesheet.  For
overriding emphasis handling, you'd create a user stylesheet that reads:

    \newcommand{\DNemphasis}[1]{\emph{#1}}

\DNemphasis means *D*ocutils *N*ode whose name is "emphasis".

\emph{#1} is the default definition, replace it with anything you like.

The downsides of the new LaTeX writer are that it's not documented at
all, and that it's not feature-complete yet (though it behaves better
than the old LaTeX writer in several edge cases).  I'd be willing to
provide support, though.

> But the older one contains methods like
> LaTeXTranslator.visit_admonition(...) which seem useful to me (in this
> case for listings maybe). Maybe there is some short text describing
> how to derive such a customized version of a docutils writer?

If you want to use Python code for customization (which in my experience
is more unwieldy than LaTeX code but provides much better support for
logic), I'd suggest you use the old LaTeX writer for now.

Look at writers/s5_html/__init__.py and tools/rst2s5.py for hints on how
to create a derived writer.  (The S5 writer is derived from the
html4css1 writer.)

HTH & HAND,
Felix

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

"the number of contributors [...] is strongly and inversely correlated with the
number of hoops each project makes a contributing user go through."      -- ESR