docutils-users — General discussions, questions, help requests.

Re: [Docutils-users] installation strategy

[Guenter M. <mi...@us...>]

On 2023-08-29, Alan G. Isaac wrote:
> Latest docutils from Subversion repository (vis svn update).
> Installed with
> 	python312 setup.py install
> Subsequent message from pip:
> 	DEPRECATION: Loading egg at c:\program files\python312\lib\site-packages\docutils-0.21b0.dev0-py3.12.egg is deprecated. pip 23.3 will enforce this behaviour 
> change. A possible replacement is to use pip for package installation.

Where did you get the egg from?

> I searched but did not find an answer to the question:
> what does this mean, and how to address it?

Latest tips at
https://docutils.sourceforge.io/README.html#installation

[Docutils-users] installation strategy

[Alan G. I. <ala...@gm...>]

Latest docutils from Subversion repository (vis svn update).
Installed with
	python312 setup.py install
Subsequent message from pip:
	DEPRECATION: Loading egg at c:\program files\python312\lib\site-packages\docutils-0.21b0.dev0-py3.12.egg is deprecated. pip 23.3 will enforce this behaviour 
change. A possible replacement is to use pip for package installation.

I searched but did not find an answer to the question:
what does this mean, and how to address it?

Thanks,
Alan

Re: [Docutils-users] docutils install under 3.12b failed

[Alan G. I. <ala...@gm...>]

Hi Guenter,
Thank you for you patient and helpful analysis!
Alan Isaac

On 5/29/2023 4:21 PM, Guenter Milde via Docutils-users wrote:
> It seems a mix up of Python 3.11 and 3.12
> 
>>     File "C:\Program Files\Python311\Scripts\rst2html5.py", line 4, in <module>
>>     File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 3326, in <module>
> With one Python version expecting/containing Docutils 0.20b.dev and the
> other 0.20.2b.dev.
> 
> 

Re: [Docutils-users] docutils install under 3.12b failed

[Guenter M. <mi...@us...>]

Dear Alan,

On 2023-05-28, Alan G. Isaac wrote:
> I should be clearer. The installation appeared to succeed,
> but I cannot run rst2html5.py.  Sorry for the previous
> misleading info.

It seems a mix up of Python 3.11 and 3.12

>    File "C:\Program Files\Python311\Scripts\rst2html5.py", line 4, in <module>
>    File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 3326, in <module>

With one Python version expecting/containing Docutils 0.20b.dev and the
other 0.20.2b.dev.


> pkg_resources.VersionConflict: (docutils 0.20.2b0.dev0 (c:\program files\python312\lib\site-packages\docutils-0.20.2b0.dev0-py3.12.egg), 
> Requirement.parse('docutils==0.20b0.dev0'))

You may consider running the `docutils` command instead, or specify the
Python version like, e.g., `python3.11 -m docutils --help`.

Günter

Re: [Docutils-users] docutils install under 3.12b failed

[Guenter M. <mi...@us...>]

On 2023-05-28, Alan G. Isaac wrote:
> I should be clearer. The installation appeared to succeed,
> but I cannot run rst2html5.py.  Sorry for the previous
> misleading info.

Maybe it has something to do with your rst2html5.py?

> Traceback (most recent call last):
>    File "C:\Program Files\Python311\Scripts\rst2html5.py", line 4, in <module>
>      __import__('pkg_resources').run_script('docutils==0.20b0.dev0', 'rst2html5.py')
>      ^^^^^^^^^^^^^^^^^^^^^^^^^^^

Line 4 of the rst2html5.py distributed with Docutils is contains just a
comment:

     #    Copying and distribution of this file, with or without modification,

This may be due to an obsolete 3rd-party script or some
code prepended during the installation under Windows.


Also, you seem to run a mix of Python 3.11 and 3.12:

>    File "C:\Program Files\Python311\Scripts\rst2html5.py", line 4, in <module>
                                  ^^^
vs.

>    File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 3326, in <module>
                                  ^^^

Which version of Python did you use to install/update the Docutils package?


You might try ``python3.11 -m docutils --version`` 
and ``python3.12 -m docutils --version`` to find out if
the installation works under the respective python versions.


You can also try whether using the shell command ``docutils`` instead of ``rst2html5.py``
helps.

Günter

Re: [Docutils-users] docutils install under 3.12b failed

[Alan G. I. <ala...@gm...>]

I should be clearer. The installation appeared to succeed,
but I cannot run rst2html5.py.  Sorry for the previous
misleading info.

Alan Isaac

Traceback (most recent call last):
   File "C:\Program Files\Python311\Scripts\rst2html5.py", line 4, in <module>
     __import__('pkg_resources').run_script('docutils==0.20b0.dev0', 'rst2html5.py')
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 3326, in <module>
     @_call_aside
      ^^^^^^^^^^^
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 3301, in _call_aside
     f(*args, **kwargs)
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 3339, in _initialize_master_working_set
     working_set = WorkingSet._build_master()
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 631, in _build_master
     return cls._build_from_requirements(__requires__)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 644, in _build_from_requirements
     dists = ws.resolve(reqs, Environment())
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 827, in resolve
     dist = self._resolve_dist(
            ^^^^^^^^^^^^^^^^^^^
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 868, in _resolve_dist
     raise DistributionNotFound(req, requirers)
pkg_resources.DistributionNotFound: The 'docutils==0.20b0.dev0' distribution was not found and is required by the application
Prepare to write C:\Users\aisaac\dpt\www\notes\toml-intro.html
Traceback (most recent call last):
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 629, in _build_master
     ws.require(__requires__)
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 966, in require
     needed = self.resolve(parse_requirements(requirements))
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 827, in resolve
     dist = self._resolve_dist(
            ^^^^^^^^^^^^^^^^^^^
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 873, in _resolve_dist
     raise VersionConflict(dist, req).with_context(dependent_req)
pkg_resources.VersionConflict: (docutils 0.20.2b0.dev0 (c:\program files\python312\lib\site-packages\docutils-0.20.2b0.dev0-py3.12.egg), 
Requirement.parse('docutils==0.20b0.dev0'))

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
   File "C:\Program Files\Python311\Scripts\rst2html5.py", line 4, in <module>
     __import__('pkg_resources').run_script('docutils==0.20b0.dev0', 'rst2html5.py')
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 3326, in <module>
     @_call_aside
      ^^^^^^^^^^^
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 3301, in _call_aside
     f(*args, **kwargs)
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 3339, in _initialize_master_working_set
     working_set = WorkingSet._build_master()
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 631, in _build_master
     return cls._build_from_requirements(__requires__)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 644, in _build_from_requirements
     dists = ws.resolve(reqs, Environment())
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 827, in resolve
     dist = self._resolve_dist(
            ^^^^^^^^^^^^^^^^^^^
   File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 868, in _resolve_dist
     raise DistributionNotFound(req, requirers)
pkg_resources.DistributionNotFound: The 'docutils==0.20b0.dev0' distribution was not found and is required by the application

[Docutils-users] docutils install under 3.12b failed

[Alan G. I. <ala...@gm...>]

I SVN updated docutils and then attempted to install and got the following error.
Suggestions?

File "C:\Program Files\Python312\Lib\site-packages\pkg_resources\__init__.py", line 873, in _resolve_dist
     raise VersionConflict(dist, req).with_context(dependent_req)
pkg_resources.VersionConflict: (docutils 0.20.2b0.dev0 (c:\program files\python312\lib\site-packages\docutils-0.20.2b0.dev0-py3.12.egg), 
Requirement.parse('docutils==0.20b0.dev0'))

Thank you,
Alan Isaac

[Docutils-users] docutils release 0.20.1 on pip and sourceforge

[engelbert g. <eng...@gm...>]

Hei 0.20.1 is out

a small bug fix release


* docutils/MANIFEST.in

  - Include tox.ini and docutils.conf in the source package
    (cf. bug #467 and bug #461).

* tools/rst2odt_prepstyles.py

  - Moved to ``docutils/writers/odf_odt/prepstyles.py``.
    Replaced with a provisional backwards compatibility script.

* no developer files from my local system, no html-files in the
egg-directory

cheers
 e

[Docutils-users] docutils release 0.20 is out on pip

[engelbert g. <eng...@gm...>]

hello,

after the quiet test period, 0.20 is the new release

Nothing changed from rc1 aside from dropping the postfix

cheers
 e


*Release Notes*
Note

Docutils 0.20 is the last version supporting Python 3.7 and 3.8.

    General

        Support Python 3.11 (patch #198 by Hugo van Kemenade).

    Output changes:

    HTML5:

        Use dpub-ARIA role "doc-footnote" (instead of ARIA role "note") for
footnotes.
    LaTeX:

        Do not load the inputenc package in UTF-8 encoded LaTeX sources.
(UTF-8 is the default encoding for LaTeX2e since 2018).

    Configuration changes:

        Settings in the [latex2e writer] configuration file section are now
ignored by the "xetex" writer. Place common settings in section [latex
writers].

        New command line setting output. Obsoletes the <destination>
positional argument (cf. future changes).

    utils.find_file_in_dirs() now returns a POSIX path also on Windows;
utils.get_stylesheet_list() no longer converts \ to /.

    docutils/languages/ docutils/parsers/rst/languages/

        Support Ukrainian. Patch by Dmytro Kazanzhy.

    test/coverage.sh

        Removed. Use the coverage.py project instead, coverage run
test/alltests.py and coverage report.

    tools/

        Moved quicktest.py to tools/dev/.


Detailed changes in https://docutils.sourceforge.io/HISTORY.html

[Docutils-users] docutils 0.20rc1 released

[engelbert g. <eng...@gm...>]

The release candidate is on pip

When installing with pip add the --pre option::

  pip install --pre docutils

cheers
 e

*Release Notes*

Note

Docutils 0.20 is the last version supporting Python 3.7 and 3.8.

   -

   General
   -

      Support Python 3.11 (patch #198 by Hugo van Kemenade).
      -

   Output changes:
   HTML5:

   Use dpub-ARIA role "doc-footnote" (instead of ARIA role "note") for
   footnotes.
   LaTeX:

   Do not load the inputenc package in UTF-8 encoded LaTeX sources. (UTF-8
   is the default encoding for LaTeX2e since 2018).
   -

   Configuration changes:
   -

      Settings in the [latex2e writer] configuration file section are now
      ignored by the "xetex" writer. Place common settings in section [latex
      writers]
      <https://docutils.sourceforge.io/docs/user/config.html#latex-writers>.
      -

      New command line setting output
      <https://docutils.sourceforge.io/docs/user/config.html#output>.
      Obsoletes the <destination> positional argument (cf. future changes
      <https://docutils.sourceforge.io/RELEASE-NOTES.html#command-line-usage-pattern>
      ).
      -

   utils.find_file_in_dirs() now returns a POSIX path also on Windows;
   utils.get_stylesheet_list() no longer converts \ to /.
   -

   docutils/languages/ docutils/parsers/rst/languages/
   -

      Support Ukrainian. Patch by Dmytro Kazanzhy.
      -

   test/coverage.sh
   -

      Removed. Use the coverage.py <https://pypi.org/project/coverage/>
      project instead, coverage run test/alltests.py and coverage report.
      -

   tools/
   -

      Moved quicktest.py to tools/dev/.


Detailed changes in https://docutils.sourceforge.io/HISTORY.html

[Docutils-users] release 0.20 plan

[engelbert g. <eng...@gm...>]

hello everyone

0.20 is in it's final

* rc1 before the weekend may 6./7.
* release on tuesday , next may 9 or if someone needs more test time,  may
16.

all the best
 e

[Docutils-users] New myst-docutils release

[Chris S. <chr...@ho...>]

Hi all 👋,

I'm pleased to announce a new release of myst-parser (and myst-docutils),
that brings a number of exciting new features, improvements, and upgrades 🎉
https://myst-parser.readthedocs.io

- 📚 Rewritten documentation, with a clearer structure, many more examples, rich hover tips, and a new live preview page (powered by pyscript)
  - The code base API is also now fully documented by https://sphinx-autodoc2.readthedocs.io/, which even allows for MyST docstrings!
- ⬆️ Add Sphinx 6 support
- 📄 Extended docutils (single-page) support
- 🔗 Extended Markdown links, including intersphinx support, e.g. `[text](inv:name#target)`
- `{}` New attributes syntax, to extend common Markdown syntaxes, e.g. `![image](image.png){#id .class width=100px}`

For a full list of changes, see: https://github.com/executablebooks/MyST-Parser/blob/master/CHANGELOG.md

Happy parsing! 🤖
Executable books team

Re: [Docutils-users] latex write docinfo

[Guenter M. <mi...@us...>]

On 2023-01-19, Alan G. Isaac wrote:
> On 1/18/2023 5:05 AM, Guenter Milde via Docutils-users wrote:
>> Dear Alan,

>> On 2023-01-14, Alan G. Isaac wrote:
>>> In the latex writer, in
>>> 	LaTeXTranslator.depart_document
>>> might it be considered to move the docinfo section
>>> to a separate method?

This is now done at [r9324].

Please keep in mind:

* The new functions are not part of the public API. Like all undocumented
  objects (i.e. elements without a docstring), they are only provisional,
  without the promise of backwards compatibility.

* As a general rule, if subclassing a Translator class:
    Safe subclassing: when overriding methods,
    treat ``visit_*`` and ``depart_*`` methods as a unit
    to prevent breaks due to internal changes.


Günter

Re: [Docutils-users] latex write docinfo

[Alan G. I. <ala...@gm...>]

On 1/18/2023 5:05 AM, Guenter Milde via Docutils-users wrote:
> Dear Alan,
> 
> On 2023-01-14, Alan G. Isaac wrote:
>> In the latex writer, in
>> 	LaTeXTranslator.depart_document
>> might it be considered to move the docinfo section
>> to a separate method? Say `depart_document_docinfo`
>> or something like that?
> 
>> Motivation: it is the only part of the method that
>> rst2beamer changes, but there has been churn in
>> the other parts of `depart_document`. (So there
>> was really no need for the rst2beamer method to
>> get out of sync as it has.)
> 
> Something like the patch below?
> 
> Günter



> --
> 
> From: milde <mi...@us...>
> Date: Wed, 18 Jan 2023 10:57:51 +0100
> Subject: [PATCH] LaTeX writer: outsourcing of some code from `depart_document()`.
> 
> Move parts of the spaghetti code in `LaTeXTranslator.depart_document()
> to new auxiliary methods `LaTeXTranslator.append_title()` and
> `LaTeXTranslator.append_bibliography()`.
> ---
>   docutils/docutils/writers/latex2e/__init__.py | 72 ++++++++++++++++++++++++++++++++++++++++++++----------------------------
>   1 file changed, 44 insertions(+), 28 deletions(-)
> 
> diff --git a/docutils/docutils/writers/latex2e/__init__.py b/docutils/docutils/writers/latex2e/__init__.py
> index d46272a..4386620 100644
> --- a/docutils/docutils/writers/latex2e/__init__.py
> +++ b/docutils/docutils/writers/latex2e/__init__.py
> @@ -1995,5 +1995,5 @@ class LaTeXTranslator(nodes.NodeVisitor):
>   
>       def depart_document(self, node):
> -        # Complete header with information gained from walkabout
> +        # Complete "parts" with information gained from walkabout
>           # * language setup
>           if (self.babel.otherlanguages
> @@ -2011,30 +2011,49 @@ class LaTeXTranslator(nodes.NodeVisitor):
>           if self.pdfinfo:
>               self.pdfsetup += [r'\hypersetup{'] + self.pdfinfo + ['}']
> -        # Complete body
> -        # * document title (with "use_latex_docinfo" also
> -        #   'author', 'organization', 'contact', 'address' and 'date')
> -        if self.title or (
> -           self.use_latex_docinfo and (self.author_stack or self.date)):
> -            # \title (empty \title prevents error with \maketitle)
> -            title = [''.join(self.title)]
> -            if self.title:
> -                title += self.title_labels
> -            if self.subtitle:
> -                title += [r'\\',
> +        # * title (including author(s) and date if using "latex_docinfo")
> +        self.append_title()  # see below
> +        # * bibliography
> +        self.append_bibliogaphy()  # see below
> +        # * make sure to generate a toc file if needed for local contents:
> +        if 'minitoc' in self.requirements and not self.has_latex_toc:
> +            self.out.append('\n\\faketableofcontents % for local ToCs\n')
> +
> +    def append_title(self):
> +        # Append ``\title``, ``\author``, and ``\date`` to "titledata"
> +        # and ``\maketitle`` to "body_pre_docinfo" parts.
> +        #
> +        # Auxiliary function called by `self.depart_document()`.
> +        if not (self.title
> +                or (self.use_latex_docinfo
> +                    and (self.author_stack or self.date))):
> +            return  # do nothing, there is no title data
> +        # We need all three of ``\title``, ``\author``, and ``\date``
> +        # (even if empty) to prevent errors and/or automatic display
> +        # of the current date by \maketitle.
> +        # \title
> +        title_arg = [''.join(self.title)]  # ensure len == 1
> +        if self.title:
> +            title_arg += self.title_labels
> +        if self.subtitle:
> +            title_arg += [r'\\',
>                             r'\DUdocumentsubtitle{%s}' % ''.join(self.subtitle),
>                             ] + self.subtitle_labels
> -            self.titledata.append(r'\title{%s}' % '%\n  '.join(title))
> -            # \author (empty \author prevents warning with \maketitle)
> -            authors = ['\\\\\n'.join(author_entry)
> -                       for author_entry in self.author_stack]
> -            self.titledata.append(r'\author{%s}' %
> -                                  ' \\and\n'.join(authors))
> -            # \date (empty \date prevents defaulting to \today)
> -            self.titledata.append(r'\date{%s}' % ', '.join(self.date))
> -            # \maketitle in the body formats title with LaTeX
> -            self.body_pre_docinfo.append('\\maketitle\n')
> -
> -        # * bibliography
> -        #   TODO insertion point of bibliography should be configurable.
> +        self.titledata.append(r'\title{%s}' % '%\n  '.join(title_arg))
> +        # \author
> +        author_arg = ['\\\\\n'.join(author_entry)
> +                      for author_entry in self.author_stack]
> +        self.titledata.append(r'\author{%s}' %
> +                              ' \\and\n'.join(author_arg))
> +        # \date
> +        self.titledata.append(r'\date{%s}' % ', '.join(self.date))
> +        # \maketitle
> +        # Must be in the document body. We add it to `body_pre_docinfo`
> +        # to allow templates to put `titledata` into the document preamble.
> +        self.body_pre_docinfo.append('\\maketitle\n')
> +
> +    def append_bibliogaphy(self):
> +        # Add bibliography at end of document.
> +        # TODO insertion point should be configurable.
> +        # Auxiliary function called by `depart_document`.
>           if self.bibtex and self._bibitems:
>               self.out.append('\n\\bibliographystyle{%s}\n' % self.bibtex[0])
> @@ -2054,7 +2073,4 @@ class LaTeXTranslator(nodes.NodeVisitor):
>                                   (bibitem[0], cite_key, bibitem[1]))
>               self.out.append('\\end{thebibliography}\n')
> -        # * make sure to generate a toc file if needed for local contents:
> -        if 'minitoc' in self.requirements and not self.has_latex_toc:
> -            self.out.append('\n\\faketableofcontents % for local ToCs\n')
>   
>       def visit_emphasis(self, node):
> --
> libgit2 1.1.0
> 



Yes, that seems much better to me.
Please announce when/if you apply it.
Thanks! Alan

Re: [Docutils-users] latex write docinfo

[Guenter M. <mi...@us...>]

Dear Alan,

On 2023-01-14, Alan G. Isaac wrote:
> In the latex writer, in
> 	LaTeXTranslator.depart_document
> might it be considered to move the docinfo section
> to a separate method? Say `depart_document_docinfo`
> or something like that?

> Motivation: it is the only part of the method that
> rst2beamer changes, but there has been churn in
> the other parts of `depart_document`. (So there
> was really no need for the rst2beamer method to
> get out of sync as it has.)

Something like the patch below?

Günter

--

From: milde <mi...@us...>
Date: Wed, 18 Jan 2023 10:57:51 +0100
Subject: [PATCH] LaTeX writer: outsourcing of some code from `depart_document()`.

Move parts of the spaghetti code in `LaTeXTranslator.depart_document()
to new auxiliary methods `LaTeXTranslator.append_title()` and
`LaTeXTranslator.append_bibliography()`.
---
 docutils/docutils/writers/latex2e/__init__.py | 72 ++++++++++++++++++++++++++++++++++++++++++++----------------------------
 1 file changed, 44 insertions(+), 28 deletions(-)

diff --git a/docutils/docutils/writers/latex2e/__init__.py b/docutils/docutils/writers/latex2e/__init__.py
index d46272a..4386620 100644
--- a/docutils/docutils/writers/latex2e/__init__.py
+++ b/docutils/docutils/writers/latex2e/__init__.py
@@ -1995,5 +1995,5 @@ class LaTeXTranslator(nodes.NodeVisitor):
 
     def depart_document(self, node):
-        # Complete header with information gained from walkabout
+        # Complete "parts" with information gained from walkabout
         # * language setup
         if (self.babel.otherlanguages
@@ -2011,30 +2011,49 @@ class LaTeXTranslator(nodes.NodeVisitor):
         if self.pdfinfo:
             self.pdfsetup += [r'\hypersetup{'] + self.pdfinfo + ['}']
-        # Complete body
-        # * document title (with "use_latex_docinfo" also
-        #   'author', 'organization', 'contact', 'address' and 'date')
-        if self.title or (
-           self.use_latex_docinfo and (self.author_stack or self.date)):
-            # \title (empty \title prevents error with \maketitle)
-            title = [''.join(self.title)]
-            if self.title:
-                title += self.title_labels
-            if self.subtitle:
-                title += [r'\\',
+        # * title (including author(s) and date if using "latex_docinfo")
+        self.append_title()  # see below
+        # * bibliography
+        self.append_bibliogaphy()  # see below
+        # * make sure to generate a toc file if needed for local contents:
+        if 'minitoc' in self.requirements and not self.has_latex_toc:
+            self.out.append('\n\\faketableofcontents % for local ToCs\n')
+
+    def append_title(self):
+        # Append ``\title``, ``\author``, and ``\date`` to "titledata"
+        # and ``\maketitle`` to "body_pre_docinfo" parts.
+        #
+        # Auxiliary function called by `self.depart_document()`.
+        if not (self.title
+                or (self.use_latex_docinfo
+                    and (self.author_stack or self.date))):
+            return  # do nothing, there is no title data
+        # We need all three of ``\title``, ``\author``, and ``\date``
+        # (even if empty) to prevent errors and/or automatic display
+        # of the current date by \maketitle.
+        # \title
+        title_arg = [''.join(self.title)]  # ensure len == 1
+        if self.title:
+            title_arg += self.title_labels
+        if self.subtitle:
+            title_arg += [r'\\',
                           r'\DUdocumentsubtitle{%s}' % ''.join(self.subtitle),
                           ] + self.subtitle_labels
-            self.titledata.append(r'\title{%s}' % '%\n  '.join(title))
-            # \author (empty \author prevents warning with \maketitle)
-            authors = ['\\\\\n'.join(author_entry)
-                       for author_entry in self.author_stack]
-            self.titledata.append(r'\author{%s}' %
-                                  ' \\and\n'.join(authors))
-            # \date (empty \date prevents defaulting to \today)
-            self.titledata.append(r'\date{%s}' % ', '.join(self.date))
-            # \maketitle in the body formats title with LaTeX
-            self.body_pre_docinfo.append('\\maketitle\n')
-
-        # * bibliography
-        #   TODO insertion point of bibliography should be configurable.
+        self.titledata.append(r'\title{%s}' % '%\n  '.join(title_arg))
+        # \author
+        author_arg = ['\\\\\n'.join(author_entry)
+                      for author_entry in self.author_stack]
+        self.titledata.append(r'\author{%s}' %
+                              ' \\and\n'.join(author_arg))
+        # \date
+        self.titledata.append(r'\date{%s}' % ', '.join(self.date))
+        # \maketitle
+        # Must be in the document body. We add it to `body_pre_docinfo`
+        # to allow templates to put `titledata` into the document preamble.
+        self.body_pre_docinfo.append('\\maketitle\n')
+
+    def append_bibliogaphy(self):
+        # Add bibliography at end of document.
+        # TODO insertion point should be configurable.
+        # Auxiliary function called by `depart_document`.
         if self.bibtex and self._bibitems:
             self.out.append('\n\\bibliographystyle{%s}\n' % self.bibtex[0])
@@ -2054,7 +2073,4 @@ class LaTeXTranslator(nodes.NodeVisitor):
                                 (bibitem[0], cite_key, bibitem[1]))
             self.out.append('\\end{thebibliography}\n')
-        # * make sure to generate a toc file if needed for local contents:
-        if 'minitoc' in self.requirements and not self.has_latex_toc:
-            self.out.append('\n\\faketableofcontents % for local ToCs\n')
 
     def visit_emphasis(self, node):
--
libgit2 1.1.0

[Docutils-users] Tests under Windows (was: latex writer style sheets)

[Guenter M. <mi...@us...>]

On 2023-01-16, Alan G. Isaac wrote:

> One test failed in ``alltests.py``. If I understand correctly, the
> result is correct, but the expected result needs fixing.

Could you try again with [r9323]?

Thanks,

Günter Milde

Re: [Docutils-users] latex writer style sheets

[Alan G. I. <ala...@gm...>]

On 1/16/2023 5:45 PM, Guenter Milde via Docutils-users wrote:
> Could you try with --stylesheet-path and also try running the test suite
> (docutils/tests/alltests.py), please?



Done. I ran into only the following problem:
One test failed in ``alltests.py``. If I understand correctly, the
result is correct, but the expected result needs fixing.
Alan


======================================================================
FAIL: test_find_file_in_dirs (test_utils.HelperFunctionTests.test_find_file_in_dirs)
----------------------------------------------------------------------
Traceback (most recent call last):
   File "D:\software\svn\docutils-code\docutils\test\test_utils.py", line 361, in test_find_file_in_dirs
     self.assertEqual(utils.find_file_in_dirs('alltests.py', dirs),
AssertionError: 'D:/software/svn/docutils-code/docutils/test/alltests.py' != 'D:\\software\\svn\\docutils-code\\docutils\\test\\alltests.py'
- D:/software/svn/docutils-code/docutils/test/alltests.py
?   ^        ^   ^             ^        ^    ^
+ D:\software\svn\docutils-code\docutils\test\alltests.py
?   ^        ^   ^             ^        ^    ^


----------------------------------------------------------------------
Ran 1751 tests in 4.267s

FAILED (failures=1, skipped=2)

Re: [Docutils-users] latex writer style sheets

[Guenter M. <mi...@us...>]

On 2023-01-16, Alan G. Isaac wrote:
> On 1/16/2023 4:29 AM, Guenter Milde via Docutils-users wrote:
>> Dear Alan Isaac,

>> thank you for the bug report and fix proposal.


>> The commit [r9316] implements a version that avoids fixes side-effects
>> that broke the test suite with the original proposal and tries to clarify
>> the documentation.

>> Could you please test and tell if this is what you intended
>> (I don't have Windows).

> This works for me.
> Note: I use --styleshseet, not --stylesheet-path
> I did try out the latter just fyi, and it worked,
> but I did not try out the relative-path expansion.

Could you try with --stylesheet-path and also try running the test suite
(docutils/tests/alltests.py), please?

Günter

Re: [Docutils-users] latex writer style sheets

[Alan G. I. <ala...@gm...>]

On 1/16/2023 4:29 AM, Guenter Milde via Docutils-users wrote:
> Dear Alan Isaac,
> 
> thank you for the bug report and fix proposal.
> 
> 
> The commit [r9316] implements a version that avoids fixes side-effects
> that broke the test suite with the original proposal and tries to clarify
> the documentation.
> 
> Could you please test and tell if this is what you intended
> (I don't have Windows).
> 



This works for me.
Note: I use --styleshseet, not --stylesheet-path
I did try out the latter just fyi, and it worked,
but I did not try out the relative-path expansion.

Thanks! Alan

Re: [Docutils-users] latex writer style sheets

[Guenter M. <mi...@us...>]

Dear Alan Isaac,

thank you for the bug report and fix proposal.

On 2023-01-14, Alan G. Isaac wrote:
> This is fixed by changing the return of LaTeXTranslator.stylesheet_call to
> 	return cmd % path.as_posix()
> (I.e., by converting the path to a posix representation.)

This change would mean that with 
``rst2latex --stylesheet=C:\tmp\test.sty``
we will get
   \usepackage{C:/tmp/test}
i.e. a conversion of backwards to forward slashes instead of a "literal" use
as announced for "--stylesheet" arguments with the HTML writers.
However, I believe this would be "the right thing" as LaTeX struggles with
the backwards slashes anyway.

The commit [r9316] implements a version that avoids fixes side-effects 
that broke the test suite with the original proposal and tries to clarify
the documentation.

Could you please test and tell if this is what you intended
(I don't have Windows).

Thanks again,
Günter Milde


> On 1/14/2023 12:39 PM, Alan G. Isaac wrote:
>> With current docutils on Windows:
>>    --stylesheet=C:/Users/aisaac/svn/aisaac/mydocs/372/372slides
>> is producing
>>    %%% User specified packages and stylesheets
>>    \usepackage{C:\Users\aisaac\svn\aisaac\mydocs\372\372slides}

>> The forward slashes need to be retained, of course.

>> This might (?) be related to this in the history:

>> docutils/utils/__init__.py

>>      find_file_in_dirs() now returns a POSIX path also on Windows; get_stylesheet_list() no longer converts "" to "/".

>> If so, that is a breaking change.

>> Alan Isaac


> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users

> Please use "Reply All" to reply to the list.

Re: [Docutils-users] latex + pygments

[Guenter M. <mi...@us...>]

On 2023-01-15, Alan G. Isaac wrote:
> What is the current status of pygments support
> for LaTeX writers?

Syntax highlighting with Pygments is implemented in Docutils since
version 0.9. 

Code is parsed by the Pygments syntax highlighter and tokens are
stored in nested inline elements with class arguments according to their
syntactic category. 

As inline elements are supported by all writers, no change is required on
the writer side.

The actual highlighting requires a style-sheet (e.g. one generated by
Pygments, see the sandbox/stylesheets for examples).

See 
https://docutils.sourceforge.io/docs/ref/rst/directives.html#code
https://docutils.sourceforge.io/docs/user/config.html#syntax-highlight

and just try it out.

Günter Milde

[Docutils-users] latex + pygments

[Alan G. I. <ala...@gm...>]

What is the current status of pygments support
for LaTeX writers? I couldn't find much in the
history, and search made it seem that this
https://docutils.sourceforge.io/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/rst2latex-pygments
(in the sandbox) is the basic answer.

Note that I am not advocating for or against support.
I am just trying to understand whether it is dormant
or not.

Thanks! Alan

[Docutils-users] latex write docinfo

[Alan G. I. <ala...@gm...>]

In the latex writer, in
	LaTeXTranslator.depart_document
might it be considered to move the docinfo section
to a separate method? Say `depart_document_docinfo`
or something like that?

Motivation: it is the only part of the method that
rst2beamer changes, but there has been churn in
the other parts of `depart_document`. (So there
was really no need for the rst2beamer method to
get out of sync as it has.)

Thanks for considering,
Alan Isaac

Re: [Docutils-users] rst2beamer problem

[Guenter M. <mi...@us...>]

On 2023-01-14, Alan G. Isaac wrote:
> I'm using current docutils.
> rst2beamer uses the LaTeX writer.

> Has a ``_use_latex_citations`` attribute
> been removed from the docutils LaTeXTranslator?

The name has been normalized with the other "use_latex_..." attributes
in r8880 from 05.11.21

Günter

Re: [Docutils-users] latex writer style sheets

[Alan G. I. <ala...@gm...>]

This is fixed by changing the return of LaTeXTranslator.stylesheet_call to
	return cmd % path.as_posix()
(I.e., by converting the path to a posix representation.)
Alan Isaac


On 1/14/2023 12:39 PM, Alan G. Isaac wrote:
> With current docutils on Windows:
>    --stylesheet=C:/Users/aisaac/svn/aisaac/mydocs/372/372slides
> is producing
>    %%% User specified packages and stylesheets
>    \usepackage{C:\Users\aisaac\svn\aisaac\mydocs\372\372slides}
> 
> The forward slashes need to be retained, of course.
> 
> This might (?) be related to this in the history:
> 
> docutils/utils/__init__.py
> 
>      find_file_in_dirs() now returns a POSIX path also on Windows; get_stylesheet_list() no longer converts "" to "/".
> 
> If so, that is a breaking change.
> 
> Alan Isaac