Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[10004] trunk/docutils
|
From: <mi...@us...> - 2024-12-18 22:03:21
|
Revision: 10004
http://sourceforge.net/p/docutils/code/10004
Author: milde
Date: 2024-12-18 22:03:18 +0000 (Wed, 18 Dec 2024)
Log Message:
-----------
Add "template" to the parts returned by the LaTeX writers.
`writers.latex2e.Writer.assemble_parts()` now also returns the
"template" that is used to generate the output document from the
(other) parts.
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/docs/api/publisher.rst
trunk/docutils/docs/user/config.rst
trunk/docutils/docs/user/latex.rst
trunk/docutils/docutils/writers/latex2e/__init__.py
trunk/docutils/test/test_writers/test_latex2e_parts.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2024-12-18 22:03:08 UTC (rev 10003)
+++ trunk/docutils/HISTORY.rst 2024-12-18 22:03:18 UTC (rev 10004)
@@ -179,6 +179,7 @@
for citation references resolved with BibTeX (cf. `use_bibtex`_ setting).
- Support SVG image inclusion with the "svg" LaTeX package (see the
`stylesheet`__ configuration setting).
+ - Add "template" to the parts returned by `Writer.assemble_parts()`.
.. _reference-label: docs/user/config.html#reference-label
__ docs/user/config.html#stylesheet-latex-writers
@@ -3438,7 +3439,7 @@
* docutils/writers/__init__.py:
- - Added assemble_parts method to the Writer class to allow for
+ - Added assemble_parts() method to the Writer class to allow for
access to a documents individual parts.
- Documented & set default for ``Writer.output`` attribute.
Modified: trunk/docutils/docs/api/publisher.rst
===================================================================
--- trunk/docutils/docs/api/publisher.rst 2024-12-18 22:03:08 UTC (rev 10003)
+++ trunk/docutils/docs/api/publisher.rst 2024-12-18 22:03:18 UTC (rev 10004)
@@ -412,10 +412,11 @@
`"footer"`_ and a description list for the `"docinfo"`_ part.
-Parts Provided by the (Xe)LaTeX Writers
-```````````````````````````````````````
+Parts Provided by the LaTeX Writers
+```````````````````````````````````
-All parts returned by the (Xe)LaTeX writers are of data type `str`.
+All parts returned by the LaTeX writers ("latex" writer and "xelatex"
+writer) are of data type `str`.
_`"abstract"`
Formatted content of the "abstract" `bibliographic field`_.
@@ -435,11 +436,11 @@
Formatted content of the "dedication" `bibliographic field`_.
"docinfo"
- Bibliographic data, i.e. the `\<docinfo>`_ element's content,
- rendered as a table.
+ `Bibliographic data`_ except `"abstract"`_ and `"dedication"`_
+ (i.e. the `\<docinfo>`_ element's content), rendered as a table.
- With ``--use-latex-docinfo`` the <author>, <organization>,
- <contact>, <address" and <date> are moved to `"titledata"`_.
+ If the use_latex_docinfo_ setting is True, <author>, <organization>,
+ <contact>, <address>, and <date> are moved to `"titledata"`_.
"fallbacks"
Fallback definitions for Docutils-specific LaTeX commands and environments.
@@ -448,7 +449,7 @@
The declaration of documentclass and document options.
"latex_preamble"
- The argument of the ``--latex-preamble`` option.
+ The argument of the latex_preamble_ setting.
"pdfsetup"
PDF properties ("hyperref" package setup).
@@ -462,6 +463,13 @@
"subtitle"
Document subtitle text and any inline markup.
+"template"
+ Content of the template__ file.
+ The output document (i.e. part `"whole"`_) is generated from the
+ template by substituting placeholders with the corresponding
+ parts using `string.Template.substitute()`_.
+ New in Docutils 0.22.
+
"title"
Document title text and any inline markup.
@@ -468,19 +476,15 @@
_`"titledata"`
The combined title data in ``\title``, ``\author``, and ``\date`` macros.
- With ``--use-latex-docinfo``, this includes the <author>,
- <organization>, <contact>, <address" and <date> docinfo items.
+ If use_latex_docinfo_ is True, "titledata" includes content from
+ the `\<docinfo>`_ elements <author>, <organization>, <contact>,
+ <address>, and <date>.
-See the template files default.tex_, titlepage.tex_, titlingpage.tex_,
-and xelatex.tex_ for examples how these parts are combined
-into a valid LaTeX document.
+__ ../user/config.html#template-latex-writers
+.. _string.Template.substitute():
+ https://docs.python.org/3/library/string.html#template-strings
-.. _default.tex: ../../docutils/writers/latex2e/default.tex
-.. _titlepage.tex: ../../docutils/writers/latex2e/titlepage.tex
-.. _titlingpage.tex: ../../docutils/writers/latex2e/titlingpage.tex
-.. _xelatex.tex: ../../docutils/writers/latex2e/xelatex.tex
-
publish_programmatically()
--------------------------
@@ -671,6 +675,7 @@
.. _nodes.document: ../ref/doctree.html#document
.. _"source" attribute: ../ref/doctree.html#source
+.. _bibliographic data:
.. _bibliographic field:
../ref/rst/restructuredtext.html#bibliographic-fields
@@ -677,12 +682,14 @@
.. _Docutils Configuration: ../user/config.html
.. _configuration files: ../user/config.html#configuration-files
.. _input_encoding: ../user/config.html#input-encoding
+.. _latex_preamble: ../user/config.html#latex-preamble
.. _output_encoding: ../user/config.html#output-encoding
.. _output_encoding_error_handler:
../user/config.html#output-encoding-error-handler
+.. _parser component name: ../user/config.html#parser
+.. _reader component name: ../user/config.html#reader
.. _template: ../user/config.html#template
-.. _reader component name: ../user/config.html#reader
-.. _parser component name: ../user/config.html#parser
+.. _use_latex_docinfo: ../user/config.html#use-latex-docinfo
.. _writer component name: ../user/config.html#writer-docutils-application
.. _command-line applications: ../user/tools.html
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2024-12-18 22:03:08 UTC (rev 10003)
+++ trunk/docutils/docs/user/config.rst 2024-12-18 22:03:18 UTC (rev 10004)
@@ -629,8 +629,8 @@
source_link
-----------
-Include a "View document source" link in the document footer. URL will
-be relative to the destination.
+Include a "View document source" link in the document footer. The URL will
+be relative to the output_path_ (if specified) or the current work directory.
:Default: None (disabled).
:Options: ``--source-link``, ``-s``, ``--no-source-link``.
@@ -1940,9 +1940,27 @@
template
~~~~~~~~
-Path [#pwd]_ to template file, which must be encoded in UTF-8.
+
+Path [#pwd]_ to a template file, which must be encoded in UTF-8.
See also `template [html writers]`_.
+Relative paths are searched in the working directory and the "latex2e"
+writer directory.
+Docutils provides the template files default.tex_, titlepage.tex_,
+titlingpage.tex_, and xelatex.tex_.
+The output document is generated from the template by
+substituting placeholders with the corresponding parts__
+using `string.Template`_.substitute().
+
+__ ../api/publisher.html#parts-provided-by-the-latex-writers
+.. _string.Template:
+ https://docs.python.org/3/library/string.html#template-strings
+.. _default.tex: ../../docutils/writers/latex2e/default.tex
+.. _titlepage.tex: ../../docutils/writers/latex2e/titlepage.tex
+.. _titlingpage.tex: ../../docutils/writers/latex2e/titlingpage.tex
+.. _xelatex.tex: ../../docutils/writers/latex2e/xelatex.tex
+
+
:Default: writer dependent (see `[latex2e writer]`_, `[xetex writer]`_).
:Option: ``--template``.
@@ -2017,10 +2035,9 @@
\usepackage{courier}
:template__:
- "default.tex" in the ``docutils/writers/latex2e/`` directory
- (installed automatically).
+ default.tex_.
- __ `template [latex writers]`_
+__ `template [latex writers]`_
font_encoding
@@ -2056,13 +2073,8 @@
The optional argument ``HyphenChar=None`` to the monospace font
prevents word hyphenation in literal text.
-:template__: "xelatex.tex" in the ``docutils/writers/latex2e/`` directory
- (installed automatically).
+:template__: xelatex.tex_.
- .. TODO: show full path with ``--help`` (like in the HTML
- writers) and add the following line: for the exact
- machine-specific path, use the ``--help`` option).
-
.. _Linux Libertine: http://www.linuxlibertine.org/
__ `template [latex writers]`_
Modified: trunk/docutils/docs/user/latex.rst
===================================================================
--- trunk/docutils/docs/user/latex.rst 2024-12-18 22:03:08 UTC (rev 10003)
+++ trunk/docutils/docs/user/latex.rst 2024-12-18 22:03:18 UTC (rev 10004)
@@ -1792,7 +1792,7 @@
``--output-encoding=OUTPUT-ENCODING``
Default:
- "utf-8"
+ "utf-8" (LaTeX's default input encoding)
Example:
Encode the LaTeX source file with the ISO `latin-1` (west european)
@@ -1812,9 +1812,6 @@
characters than does "utf8". It is, however, a non-standard
extension and no longer developed.
- Currently, the "latex2e" writer inserts ``\usepackage[utf8]{inputenc}``
- into the LaTeX source if it is UTF-8 encoded.
-
.. with utf8x:
If LaTeX issues a Warning about unloaded/unknown characters adding ::
Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py 2024-12-18 22:03:08 UTC (rev 10003)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py 2024-12-18 22:03:18 UTC (rev 10004)
@@ -286,14 +286,10 @@
# copy parts
for part in self.visitor_attributes:
setattr(self, part, getattr(visitor, part))
- # get template string from file
- templatepath = Path(self.document.settings.template)
- if not templatepath.exists():
- templatepath = self.default_template_path / templatepath.name
- template = templatepath.read_text(encoding='utf-8')
# fill template
self.assemble_parts() # create dictionary of parts
- self.output = string.Template(template).substitute(self.parts)
+ self.output = string.Template(self.parts['template']
+ ).substitute(self.parts)
def assemble_parts(self) -> None:
"""Assemble the `self.parts` dictionary of output fragments."""
@@ -309,6 +305,11 @@
else:
# body contains inline elements, so join without newline
self.parts[part] = ''.join(lines)
+ # get template string from file
+ templatepath = Path(self.document.settings.template)
+ if not templatepath.exists():
+ templatepath = self.default_template_path / templatepath.name
+ self.parts['template'] = templatepath.read_text(encoding='utf-8')
class Babel:
@@ -1558,13 +1559,6 @@
"""Cleanse, encode, and return attribute value text."""
return self.encode(whitespace.sub(' ', text))
- # TODO: is this used anywhere? -> update (use template) or delete
- ## def astext(self):
- ## """Assemble document parts and return as string."""
- ## head = '\n'.join(self.head_prefix + self.stylesheet + self.head)
- ## body = ''.join(self.body_prefix + self.body + self.body_suffix)
- ## return head + '\n' + body
-
def is_inline(self, node):
"""Check whether a node represents an inline or block-level element"""
return isinstance(node.parent, nodes.TextElement)
Modified: trunk/docutils/test/test_writers/test_latex2e_parts.py
===================================================================
--- trunk/docutils/test/test_writers/test_latex2e_parts.py 2024-12-18 22:03:08 UTC (rev 10003)
+++ trunk/docutils/test/test_writers/test_latex2e_parts.py 2024-12-18 22:03:18 UTC (rev 10004)
@@ -69,6 +69,22 @@
'requirements': '\\usepackage[T1]{fontenc}\n',
'stylesheet': '',
'subtitle': '',
+ 'template': """\
+$head_prefix% generated by Docutils <https://docutils.sourceforge.io/>
+\\usepackage{cmap} % fix search and cut-and-paste in Acrobat
+$requirements
+%%% Custom LaTeX preamble
+$latex_preamble
+%%% User specified packages and stylesheets
+$stylesheet
+%%% Fallback definitions for Docutils-specific commands
+$fallbacks
+$pdfsetup
+%%% Body
+\\begin{document}
+$titledata$body_pre_docinfo$docinfo$dedication$abstract$body
+\\end{document}
+""",
'title': '',
'titledata': '',
'version': f'{docutils.__version__}',
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
