SF.net SVN: docutils:[10004 ] trunk/docutils

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.



_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins