Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[8557] trunk/docutils
|
From: <mi...@us...> - 2020-09-04 16:58:27
|
Revision: 8557
http://sourceforge.net/p/docutils/code/8557
Author: milde
Date: 2020-09-04 16:58:24 +0000 (Fri, 04 Sep 2020)
Log Message:
-----------
LaTeX writer update
Fix workaround for section title of unsupported levels
with the new-style class handling (class wrapper instead of
class-argument for \DUtitle).
Require minimal version of "docutils.sty" to get a warning
in the LaTeX-log for obsolete files with the same name.
Update documentation.
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/RELEASE-NOTES.txt
trunk/docutils/docs/user/config.txt
trunk/docutils/docs/user/latex.txt
trunk/docutils/docutils/writers/latex2e/__init__.py
trunk/docutils/docutils/writers/latex2e/docutils.sty
trunk/docutils/test/functional/expected/latex_literal_block.tex
trunk/docutils/test/functional/expected/latex_literal_block_fancyvrb.tex
trunk/docutils/test/functional/expected/latex_literal_block_listings.tex
trunk/docutils/test/functional/expected/latex_literal_block_verbatim.tex
trunk/docutils/test/functional/expected/latex_literal_block_verbatimtab.tex
trunk/docutils/test/functional/expected/standalone_rst_xetex.tex
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2020-09-04 16:55:24 UTC (rev 8556)
+++ trunk/docutils/HISTORY.txt 2020-09-04 16:58:24 UTC (rev 8557)
@@ -95,9 +95,13 @@
.. _graphicx_option: docs/user/config.html#graphicx-option
- Most helper commands and element definitions are now defined in the
- LaTeX package `docutils.sty` and no longer inserted in the document
- preamble if the `stylesheet` setting lists "docutils".
+ LaTeX package `docutils.sty`_ and only inserted in the document
+ preamble if the `stylesheet`__ setting does not list "docutils".
+
+ .. _docutils.sty: https://ctan.org/pkg/docutils
+ __ docs/user/config.html#stylesheet-latex-writers
+
* docutils/writers/manpage.py
- Fix #394 fix missing new line after rubric.
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2020-09-04 16:55:24 UTC (rev 8556)
+++ trunk/docutils/RELEASE-NOTES.txt 2020-09-04 16:58:24 UTC (rev 8557)
@@ -109,9 +109,9 @@
__ docs/user/latex.html#classes
- Most helper commands and element definitions are now defined in the
- LaTeX package `docutils.sty` and no longer inserted in the document
- preamble if the stylesheet__ setting lists "docutils".
-
+ LaTeX package `docutils.sty`_ and only inserted in the document
+ preamble if the stylesheet__ setting does not lists "docutils".
+
__ docs/user/config.html#stylesheet-latex-writers
.. _setuptools: https://pypi.org/project/setuptools/
@@ -118,7 +118,7 @@
.. _pip: https://pypi.org/project/pip/
.. _legacy_class_functions: docs/user/config.html#legacy-class-functions
.. _graphicx_option: docs/user/config.html#graphicx-option
-.. docutils.sty: https://ctan.org/pkg/docutils (coming soon)
+.. _docutils.sty: https://ctan.org/pkg/docutils
Release 0.16 (2020-01-12)
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2020-09-04 16:55:24 UTC (rev 8556)
+++ trunk/docutils/docs/user/config.txt 2020-09-04 16:58:24 UTC (rev 8557)
@@ -1473,8 +1473,7 @@
LaTeX graphicx package option.
-Possible values are "dvips", "pdftex", "auto". "auto" includes LaTeX code
-to use "pdftex" if processing with pdf(la)tex and dvips otherwise.
+Possible values are "dvips", "pdftex", "dvipdfmx".
Default: "". Option: ``--graphicx-option``.
Modified: trunk/docutils/docs/user/latex.txt
===================================================================
--- trunk/docutils/docs/user/latex.txt 2020-09-04 16:55:24 UTC (rev 8556)
+++ trunk/docutils/docs/user/latex.txt 2020-09-04 16:58:24 UTC (rev 8557)
@@ -62,9 +62,12 @@
length) to allow customization. By convention, special macros use the
prefix ``\DU``\ [#]_.
+The `docutils.sty`_ LaTeX package providing required definitions is
+part of Docutils ≥ 0.17 and available on CTAN since 2020-09-04.
The generated LaTeX documents should be kept processable by a standard LaTeX
installation. Therefore fallback definitions are included after the `custom
-style sheets`_, if a macro is required in the document.
+style sheets`_, if a macro is required in the document and
+the `stylesheet`_ setting does not include "docutils".
* Custom `style sheets`_ can define alternative implementations with
``\newcommand``, ``\newenvironment``, and ``\newlength`` followed by
@@ -78,7 +81,10 @@
.. [#] DU for Documentation Utilities = Docutils
+.. _docutils.sty: https://ctan.org/pkg/docutils
+
+
Length units
------------
@@ -239,7 +245,7 @@
order of the class arguments cannot be ignored in LaTeX
* Class handling differs for some elements and class values:
-
+
* Class argument values starting with ``align-`` are transformed to
"align" argument values. Class argument values starting with
``language-`` set the elements language property.
@@ -442,10 +448,10 @@
Command:
``\DUadmonition`` (with legacy-class-functions_)
-
+
Environment:
``DUadmonition`` (with new-class-functions_)
-
+
.. _new-class-functions: legacy-class-functions_
Default:
@@ -466,9 +472,9 @@
\end{quote}
\fi
}
-
+
rsp with new-class-functions_::
-
+
\newenvironment{DUadmonition}%
{\begin{quote}}
{\end{quote}}
@@ -1569,7 +1575,7 @@
\subsubsection*{\centerline{\color{red}#1}}}
.. note::
- Class attribute values are ignored because the "classes_ wrapper"
+ Class attribute values are ignored because the "classes_ wrapper"
interferes with LaTeX's formatting (spacing/indendation) of text following
a section heading. Consider using a `topic element`_ or a container_.
@@ -1589,14 +1595,14 @@
===== ============= ================== ============= ==============
1 section part chapter part
2 subsection section section chapter
- 3 subsubsection subsection subsection section
- 4 paragraph subsubsection subsubsection subsection
+ 3 subsubsection subsection subsection section
+ 4 paragraph subsubsection subsubsection subsection
5 subparagraph paragraph paragraph subsubsection
- 6 DUtitle subparagraph subparagraph paragraph
- 7 DUtitle DUtitle DUtitle subparagraph
+ 6 DUtitle subparagraph subparagraph paragraph
+ 7 DUtitle DUtitle DUtitle subparagraph
===== ============= ================== ============= ==============
-
+
.. [#] One of the document classes 'book', 'memoir', 'report 'scrbook',
or 'scrreprt'.
@@ -1976,11 +1982,11 @@
* pdflatex_ and xelatex_ work with PNG, JPG, or PDF, but **not EPS**.
* Standard latex_ can include **only EPS** graphics, no other format.
* latex + dvipdfmx works with EPS and JPG (add 'dvipdfmx' to the
- documentoptions_ or graphicx_ setting
+ documentoptions_ or graphicx-option_ setting
and 'bmpsize' to the stylesheet_ setting).
If PDF-image inclusion in PDF files fails, specifying
-``--graphicx-option=pdftex`` or ``--graphicx-option=auto`` might help.
+``--graphicx-option=pdftex`` might help.
For details see grfguide.pdf_.
@@ -1995,8 +2001,8 @@
__ ../ref/rst/directives.html#images
.. _grfguide.pdf:
http://mirrors.ctan.org/macros/latex/required/graphics/grfguide.pdf
-.. _grffile:
- http://ctan.org/pkg/grffile
+.. _grffile: http://ctan.org/pkg/grffile
+.. _graphicx-option: config.html#graphicx-option
@@ -2089,7 +2095,7 @@
.. _pmboxdraw.pdf:
http://mirrors.ctan.org/macros/latex/contrib/pmboxdraw/pmboxdraw.pdf
-
+
Bugs and open issues
--------------------
Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py 2020-09-04 16:55:24 UTC (rev 8556)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py 2020-09-04 16:58:24 UTC (rev 8557)
@@ -784,9 +784,10 @@
"""
if level <= len(self.sections):
return self.sections[level-1]
- else: # unsupported levels
- return 'DUtitle[section%s]' % roman.toRoman(level)
+ # unsupported levels
+ return 'DUtitle'
+
class Table(object):
"""Manage a table while traversing.
@@ -1238,17 +1239,21 @@
# (the name `self.stylesheet` is singular because only one
# stylesheet was supported before Docutils 0.6).
stylesheet_list = utils.get_stylesheet_list(settings)
- self.fallback_stylesheet = [sheet for sheet in stylesheet_list
- if sheet == 'docutils']
- # docutils.sty is incompatible with legacy functions
- if self.fallback_stylesheet and self.settings.legacy_class_functions:
- self.fallback_stylesheet = []
+ if 'docutils' in stylesheet_list:
stylesheet_list = [sheet for sheet in stylesheet_list
if sheet != 'docutils']
+ if self.settings.legacy_class_functions:
+ # docutils.sty is incompatible with legacy functions
+ self.fallback_stylesheet = False
+ else:
+ self.fallback_stylesheet = True
+ # require a minimal version:
+ self.fallbacks['docutils.sty'
+ ] = r'\usepackage{docutils}[2020/08/28]'
+
self.stylesheet = [self.stylesheet_call(path)
for path in stylesheet_list]
-
# PDF setup
if self.hyperlink_color in ('0', 'false', 'False', ''):
self.hyperref_options = ''
@@ -2999,8 +3004,21 @@
else:
if hasattr(PreambleCmds, 'secnumdepth'):
self.requirements['secnumdepth'] = PreambleCmds.secnumdepth
- section_name = self.d_class.section(self.section_level)
+ level = self.section_level
+ section_name = self.d_class.section(level)
self.out.append('\n\n')
+ if level > len(self.d_class.sections):
+ # section level not supported by LaTeX
+ if self.settings.legacy_class_functions:
+ self.fallbacks['title'] = PreambleCmds.title_legacy
+ section_name += '[section%s]' % roman.toRoman(level)
+ else:
+ if not self.fallback_stylesheet:
+ self.fallbacks['title'] = PreambleCmds.title
+ self.fallbacks['DUclass'] = PreambleCmds.duclass
+ self.out.append('\\begin{DUclass}{section%s}\n'
+ % roman.toRoman(level))
+
# System messages heading in red:
if ('system-messages' in node.parent['classes']):
self.requirements['color'] = PreambleCmds.color
@@ -3009,21 +3027,19 @@
section_name, section_title))
else:
self.out.append(r'\%s{' % section_name)
- if self.section_level > len(self.d_class.sections):
- # section level not supported by LaTeX
- if not self.fallback_stylesheet:
- self.fallbacks['title'] = PreambleCmds.title
- # self.out.append('\\phantomsection%\n ')
+
# label and ToC entry:
bookmark = ['']
# add sections with unsupported level to toc and pdfbookmarks?
- ## if self.section_level > len(self.d_class.sections):
+ ## if level > len(self.d_class.sections):
## section_title = self.encode(node.astext())
## bookmark.append(r'\addcontentsline{toc}{%s}{%s}' %
## (section_name, section_title))
bookmark += self.ids_to_labels(node.parent, set_anchor=False)
self.context.append('%\n '.join(bookmark) + '%\n}\n')
-
+ if (level > len(self.d_class.sections)
+ and not self.settings.legacy_class_functions):
+ self.context[-1] += '\\end{DUclass}\n'
# MAYBE postfix paragraph and subparagraph with \leavemode to
# ensure floats stay in the section and text starts on a new line.
Modified: trunk/docutils/docutils/writers/latex2e/docutils.sty
===================================================================
--- trunk/docutils/docutils/writers/latex2e/docutils.sty 2020-09-04 16:55:24 UTC (rev 8556)
+++ trunk/docutils/docutils/writers/latex2e/docutils.sty 2020-09-04 16:58:24 UTC (rev 8557)
@@ -1,47 +1,15 @@
-% docutils.sty
-% ************
-% Style file for docutils LaTeX output
-% ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+%% docutils.sty: macros for Docutils LaTeX output.
+%%
+%% Copyright © 2020 Günter Milde
+%% Released under the terms of the `2-Clause BSD license`, in short:
+%%
+%% Copying and distribution of this file, with or without modification,
+%% are permitted in any medium without royalty provided the copyright
+%% notice and this notice are preserved.
+%% This file is offered as-is, without any warranty.
+
+% .. include:: README
%
-% :Copyright: © 2020 Günter Milde
-% :Licence: Released under the terms of the `2-Clause BSD license`_, in short:
-%
-% Copying and distribution of this file, with or without modification,
-% are permitted in any medium without royalty provided the copyright
-% notice and this notice are preserved.
-% This file is offered as-is, without any warranty.
-%
-% .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause
-%
-%
-% :Abstract:
-% Helper commands and element definitions for Docutils_ LaTeX output.
-%
-% :Changelog:
-% .. class:: borderless
-%
-% ====== ========== =========================================================
-% 0.1 2020-08-28 initial version
-% ====== ========== =========================================================
-%
-% Installation
-% ============
-%
-% Copy/Move/Link ``docutils.sty`` to a suitable place in the “TeX Directory
-% Structure” (TDS_) and run ``texhash``, or place it in the current working
-% directory (e.g. for testing).
-%
-% Usage
-% =====
-%
-% When generating LaTeX documents from reStructuredText sources,
-% specify this package with the `"stylesheet"`_ configuration_ option, e.g.
-% ``rst2latex --stylesheet=docutils``.
-% Alternatively, the Docutils `LaTeX writer` will extract required definitions
-% and insert them into the preamble of generated documents
-% (see `Docutils LaTeX Writer`_ for details).
-%
-%
% Implementation
% ==============
%
@@ -49,9 +17,8 @@
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{docutils}
- [2020/08/28 v0.1 macros for Docutils LaTeX output]
+ [2020/08/28 macros for Docutils LaTeX output]
-
% Helpers
% -------
%
@@ -116,8 +83,7 @@
% Elements
% --------
%
-% Definitions for unknown or to-be-configured Docutils elements
-% and roles (inline elements).
+% Definitions for unknown or to-be-configured Docutils elements.
%
% admonition::
@@ -254,22 +220,3 @@
\hspace*{\fill}\hrulefill\hspace*{\fill}
\vskip 0.5\baselineskip
}
-
-% References
-% ==========
-%
-% .. [Docutils] https://docutils.sourceforge.io/
-%
-% .. _Docutils Document Tree:
-% https://docutils.sourceforge.io/docs/ref/doctree.html
-%
-% .. _Docutils LaTeX Writer:
-% https://docutils.sourceforge.io/docs/user/latex.html
-%
-% .. _Configuration:
-% https://docutils.sourceforge.io/docs/user/config.html
-%
-% .. _"stylesheet":
-% https://docutils.sourceforge.io/docs/user/config.html#stylesheet-latex-writers
-%
-% .. _TDS: http://www.tex.ac.uk/cgi-bin/texfaq2html?label=tds
Modified: trunk/docutils/test/functional/expected/latex_literal_block.tex
===================================================================
--- trunk/docutils/test/functional/expected/latex_literal_block.tex 2020-09-04 16:55:24 UTC (rev 8556)
+++ trunk/docutils/test/functional/expected/latex_literal_block.tex 2020-09-04 16:58:24 UTC (rev 8557)
@@ -18,9 +18,9 @@
\usepackage{courier}
%%% User specified packages and stylesheets
-\usepackage{docutils}
%%% Fallback definitions for Docutils-specific commands
+\usepackage{docutils}[2020/08/28]
% character width in monospaced font
\newlength{\ttemwidth}
Modified: trunk/docutils/test/functional/expected/latex_literal_block_fancyvrb.tex
===================================================================
--- trunk/docutils/test/functional/expected/latex_literal_block_fancyvrb.tex 2020-09-04 16:55:24 UTC (rev 8556)
+++ trunk/docutils/test/functional/expected/latex_literal_block_fancyvrb.tex 2020-09-04 16:58:24 UTC (rev 8557)
@@ -18,9 +18,9 @@
\usepackage{courier}
%%% User specified packages and stylesheets
-\usepackage{docutils}
%%% Fallback definitions for Docutils-specific commands
+\usepackage{docutils}[2020/08/28]
% character width in monospaced font
\newlength{\ttemwidth}
Modified: trunk/docutils/test/functional/expected/latex_literal_block_listings.tex
===================================================================
--- trunk/docutils/test/functional/expected/latex_literal_block_listings.tex 2020-09-04 16:55:24 UTC (rev 8556)
+++ trunk/docutils/test/functional/expected/latex_literal_block_listings.tex 2020-09-04 16:58:24 UTC (rev 8557)
@@ -24,9 +24,9 @@
%%% User specified packages and stylesheets
-\usepackage{docutils}
%%% Fallback definitions for Docutils-specific commands
+\usepackage{docutils}[2020/08/28]
% character width in monospaced font
\newlength{\ttemwidth}
Modified: trunk/docutils/test/functional/expected/latex_literal_block_verbatim.tex
===================================================================
--- trunk/docutils/test/functional/expected/latex_literal_block_verbatim.tex 2020-09-04 16:55:24 UTC (rev 8556)
+++ trunk/docutils/test/functional/expected/latex_literal_block_verbatim.tex 2020-09-04 16:58:24 UTC (rev 8557)
@@ -17,9 +17,9 @@
\usepackage{courier}
%%% User specified packages and stylesheets
-\usepackage{docutils}
%%% Fallback definitions for Docutils-specific commands
+\usepackage{docutils}[2020/08/28]
% character width in monospaced font
\newlength{\ttemwidth}
Modified: trunk/docutils/test/functional/expected/latex_literal_block_verbatimtab.tex
===================================================================
--- trunk/docutils/test/functional/expected/latex_literal_block_verbatimtab.tex 2020-09-04 16:55:24 UTC (rev 8556)
+++ trunk/docutils/test/functional/expected/latex_literal_block_verbatimtab.tex 2020-09-04 16:58:24 UTC (rev 8557)
@@ -18,9 +18,9 @@
\usepackage{courier}
%%% User specified packages and stylesheets
-\usepackage{docutils}
%%% Fallback definitions for Docutils-specific commands
+\usepackage{docutils}[2020/08/28]
% character width in monospaced font
\newlength{\ttemwidth}
Modified: trunk/docutils/test/functional/expected/standalone_rst_xetex.tex
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_xetex.tex 2020-09-04 16:55:24 UTC (rev 8556)
+++ trunk/docutils/test/functional/expected/standalone_rst_xetex.tex 2020-09-04 16:58:24 UTC (rev 8557)
@@ -32,9 +32,9 @@
\setmonofont[HyphenChar=None,Scale=MatchLowercase]{DejaVu Sans Mono}
%%% User specified packages and stylesheets
-\usepackage{docutils}
%%% Fallback definitions for Docutils-specific commands
+\usepackage{docutils}[2020/08/28]
\newcounter{enumv}
\DUprovidelength{\pdfpxdimen}{1bp}
@@ -2725,9 +2725,11 @@
(depending on the document class)
-\DUtitle[sectionVI]{3.11.1.1.1.1 level 6%
+\begin{DUclass}{sectionVI}
+\DUtitle{3.11.1.1.1.1 level 6%
\label{level-6}%
}
+\end{DUclass}
an unsupported level.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
