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

Re: [Docutils-users] Inline internal target with custom target name

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

Dear Tobias,

On 2024-02-17, Tobias Deiminger wrote:

> a short question on inline internal targets. Consider this example:

>  A short generic target _`is` going to cause conflicts. A target with
>  same name but different meaning _`is` likely to be defined somewhere
>  else.

> To avoid such ambiguous targets, is it possible to assign custom target
> names to inline internal targets that differ from their inline text?

I don't know of any way to achieve the exact result except raw HTML::

  .. role:: raw-html (raw)
     :format: html
  
  This short generic target 
  :raw-html:`<span class="target" id="is-2">is</span>`
  hopefully not going to cause conflicts. 

However, in most situations, it would be OK to simply use a larger part of
the sentence as target::

  A _`longer generic target` is not going to cause conflicts.
  
put the target on the containing block element::
  
  .. _block target:

  A "block target" with an id that differs from the content.
  
  .. container::
     :name: container-target
     
     (Almost) all directives accept the "name" option to specify a target
     name.
     
Hope this helps,
     
Günter     

[Docutils-users] Inline internal target with custom target name

[Tobias D. <hax...@po...>]

Hi,
                                                                    
a short question on inline internal targets. Consider this example:
   
 A short generic target  _`is` going to cause conflicts. A target with same name
 but different meaning _`is` likely to be defined somewhere else.

To avoid such ambiguous targets, is it possible to assign custom target names to
inline internal targets that differ from their inline text?

Tobias

PS: Thanks for making docutils!

Re: [Docutils-users] installation strategy

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

It was like "refrigerator blindness": I saw only what
I expected to see. Thanks for your willingness to
be so explicit.
Alan


On 8/30/2023 5:43 AM, Guenter Milde via Docutils-users wrote:
> The linked documentation tells you:
> 
>    * To install a `development version`_*from source*:
>    
>      1. Open a shell
>    
>      2. Go to the directory containing the file ``setup.py``.
>    
>      3. Install the package with **one** of the following commands::
>    
>             pip install -e .  # editable install
>             pip install .     # regular install
>             python setup.py   # regular install with setuptools
> 
> and ``pip install --help`` explains what an "editable install" is:
> 
>    -e, --editable <path/url>   Install a project in editable mode (i.e.
>                                setuptools "develop mode") from a local project
>                                path or a VCS url.

Re: [Docutils-users] installation strategy

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

Dear Alan,

On 2023-08-29, Alan G. Isaac wrote:
> On 8/29/2023 5:01 PM, Guenter Milde via Docutils-users wrote:
>> 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.

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

> On 8/29/2023 5:01 PM, Guenter Milde via Docutils-users wrote:
>> Latest tips at
>> https://docutils.sourceforge.io/README.html#installation

> Sure, but to install the current code on Subversion,
> I cannot use pip.  Right??

Actually, no. The linked documentation tells you:

  * To install a `development version`_ *from source*:
  
    1. Open a shell
  
    2. Go to the directory containing the file ``setup.py``.
  
    3. Install the package with **one** of the following commands::
  
           pip install -e .  # editable install
           pip install .     # regular install
           python setup.py   # regular install with setuptools

and ``pip install --help`` explains what an "editable install" is:

  -e, --editable <path/url>   Install a project in editable mode (i.e.
                              setuptools "develop mode") from a local project
                              path or a VCS url.


> I suspect (??) this serves as an alert to the
> docutils project that it must change how it
> uses setuptools before pip 23.3 is released.

Thank you for the pointer. The Docutils project distributes "wheels"
instead of "eggs" since 2015¹, so we should be safe for now.

We actually plan to replace "setup.py" in one of the next releases
https://sourceforge.net/p/docutils/patches/186/

Thanks,
Günter

¹Hence my question where you got the egg from.

Re: [Docutils-users] installation strategy

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

> 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.
> 

On 8/29/2023 5:01 PM, Guenter Milde via Docutils-users wrote:
> Where did you get the egg from?


You?  :-)
It is created when I run
	python312 setup.py install
(As I have done for many years.)



> On 2023-08-29, Alan G. Isaac wrote:
>> I searched but did not find an answer to the question:
>> what does this mean, and how to address it?

On 8/29/2023 5:01 PM, Guenter Milde via Docutils-users wrote:
> Latest tips at
> https://docutils.sourceforge.io/README.html#installation

Sure, but to install the current code on Subversion,
I cannot use pip.  Right??

I suspect (??) this serves as an alert to the
docutils project that it must change how it
uses setuptools before pip 23.3 is released.

Thanks,
Alan

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.