The current implementation of custom roles in the latex2e writer produces
LaTeX code that fails to compile if no special stylesheet is provided.
IMO, this is a bug. E.g. the LaTeX file produced by the functional test
for latex2e fails to compile!
The patch below introduces a "dispatcher makro" ``\inlinenode`` that
calls class-name specific LaTeX macros, but **only if they exist**.
I.e.::
.. role:: custom3
:class: special custom3 exceptional
Special :custom3:`interpreted text`.
becomes::
Special \inlinenode{special,custom,exceptional}{interpreted text}.
wich expands to the equivalent of::
Special {\docutilsrolespecial \docutilsrolecustom
\docutilsroleexceptional interpreted text}.
with the special feature that unknown ``docutilsrole*`` commands are
silently ignored.
Discussion
==========
Backwards compatibility
-----------------------
* Is this feature used at all (under LaTeX)?
* Do we need to care for backwards compatibility? How far (weighting
improved interface against full compatibility)?
Naming
------
* Is there an abbreviation for Docutils (like DU, say)?
* Should the dispatcher command be called \inlinenode, \DUinlinenode or
\DUspan?
* Could we shorten \docutilsrole* to e.g. \DUrole* or use the more
generic name \DUclass*?
Preamble "noise"
----------------
The patch introduces the concept of "fallback" definitions, that can be
overwritten by defining in the style sheet with ``\newcommand`` (as
opposed to ``\renewcommand``).
This allows to make the insertion of the fallback definition optional
without errors if the stylesheet has a custom version (in a future step).
Multiple classes
----------------
The current implementation translates the above example to
Special \docutilsrolespecial{\docutilsrolecustom{%
\docutilsroleexceptional{interpreted text}}}.
It cannot be reproduced with reasonable effort.
* is this nesting compatible with the "order does not matter" concept for
classes in CSS?
* LaTeX styling uses different commands for macros with or without
arguments, e.g.
{\boldface foo} <--> \textbf{foo}
would it be better to put the node content in an extra pair of braces
to be backwards compatible in case of just one class argument?
({\boldface foo} and {\boldface {foo}} result in the same PDF output.)
Günter
Exec: svn 'diff' '__init__.py' 2>&1
Dir: /home/milde/Code/Python/docutils-svn/docutils/docutils/writers/latex2e/
Index: __init__.py
===================================================================
--- __init__.py (Revision 5680)
+++ __init__.py (Arbeitskopie)
@@ -366,6 +366,22 @@
]
}
+latex_fallbacks = {}
+latex_fallbacks['inlinenode'] = r"""
+\makeatletter
+\providecommand{\inlinenode}[2]{%
+ {% group ("span") to limit the scope of styling commands
+ \@for\node@...{%
+ \ifcsname docutilsrole\node@...%
+ \csname docutilsrole\node@...%
+ \fi%
+ }%
+ #2% node content
+ }% close "span"
+}
+\makeatother"""
+
+
class DocumentClass:
"""Details of a LaTeX document class."""
@@ -761,6 +777,12 @@
self.head_prefix.append(open(stylesheet).read())
else:
self.head_prefix.append(self.stylesheet % (stylesheet))
+
+ # Fallback|default definitions for docutils-specific latex objects
+ # (Ignored if there is a definition in the stylesheet)
+ # TODO insert only required commands and environments
+ self.head_prefix.append(latex_fallbacks['inlinenode'])
+
# hyperref after stylesheet
self.head_prefix.append( self.linking % (
self.colorlinks, self.hyperlink_color, self.hyperlink_color))
@@ -2207,14 +2229,12 @@
self.body.append('\n')
def visit_inline(self, node): # titlereference
- classes = node.get('classes', ['Unknown', ])
- for cls in classes:
- self.body.append( '\\docutilsrole%s{' % cls)
- self.context.append('}'*len(classes))
-
+ classes = node.get('classes', [])
+ self.body.append(r'\inlinenode{%s}{' %','.join(classes))
+
def depart_inline(self, node):
- self.body.append(self.context.pop())
-
+ self.body.append('}')
+
def visit_rubric(self, node):
self.body.append('\\rubric{')
self.context.append('}\n')
|