Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[10285] trunk/docutils
|
From: <mi...@us...> - 2026-01-07 07:52:52
|
Revision: 10285
http://sourceforge.net/p/docutils/code/10285
Author: milde
Date: 2026-01-07 07:52:49 +0000 (Wed, 07 Jan 2026)
Log Message:
-----------
Move LaTeX styling for "html-roles" definitions to docutils.sty.
The "standard definition file" "html-roles.txt" contained a "raw" directive
with LaTeX macros for the styling of the "semantic markup" roles added by
this file. This leads to WARNING messages, if applications disable the "raw"
directive for security reasons.
Move the definitions to the LaTex package/stylefile "docutils.sty" and
ensure that relevant definitions are loaded on demand.
Nice side effects:
* works also if any of the roles are defined via the "role" directive
* less overhead if just some of the roles are used.
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/ref/rst/definitions.rst
trunk/docutils/docutils/parsers/rst/include/html-roles.txt
trunk/docutils/docutils/writers/latex2e/__init__.py
trunk/docutils/docutils/writers/latex2e/docutils.sty
trunk/docutils/test/functional/expected/latex_cornercases.tex
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/length_units_latex.tex
trunk/docutils/test/functional/expected/standalone_rst_xetex.tex
trunk/docutils/test/functional/input/latex_cornercases.rst
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2026-01-07 07:52:27 UTC (rev 10284)
+++ trunk/docutils/HISTORY.rst 2026-01-07 07:52:49 UTC (rev 10285)
@@ -37,7 +37,12 @@
- Add source and line info to <table> elements.
- Fix bug #517: wrong "input_offset" when parsing table cell content.
+* docutils/writers/latex2e/*
+ - Default styling for "semantic inline markup roles" from the
+ ``html-roles.txt`` standard definition file.
+
+
Release 0.22.4 (2025-12-18)
===========================
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2026-01-07 07:52:27 UTC (rev 10284)
+++ trunk/docutils/RELEASE-NOTES.rst 2026-01-07 07:52:49 UTC (rev 10285)
@@ -298,6 +298,8 @@
- Only write ``\label`` commands for explicit IDs and IDs that are
referenced in the current document (i.e. not for un-referenced
section titles).
+ - Support the "semantic inline markup roles" from the ``html-roles.txt``
+ `standard definition file`_.
Removed objects
`parsers.rst.directives.tables.CSVTable.check_requirements()`
@@ -1451,10 +1453,8 @@
* Length units are now supported for image_ sizes.
-* Added `standard definition files`__ for special characters etc.
+* Added `standard definition files`_ for special characters etc.
- __ docs/ref/rst/definitions.html
-
Internationalization:
* Added Japanese and Simplified Chinese language mappings, and support
@@ -1585,7 +1585,8 @@
docs/ref/rst/directives.html#including-an-external-document-fragment
.. _"widths" option: docs/ref/rst/directives.html#table
-.. _Standard definition file: docs/ref/rst/definitions.html
+.. _standard definition file:
+.. _standard definition files: docs/ref/rst/definitions.html
.. _LaTeX syntax for mathematics: docs/ref/rst/mathematics.html
.. _configuration settings: docs/user/config.html
Modified: trunk/docutils/docs/ref/rst/definitions.rst
===================================================================
--- trunk/docutils/docs/ref/rst/definitions.rst 2026-01-07 07:52:27 UTC (rev 10284)
+++ trunk/docutils/docs/ref/rst/definitions.rst 2026-01-07 07:52:49 UTC (rev 10285)
@@ -172,9 +172,11 @@
.. _reStructuredText interpreted text roles: roles.html
-Additional roles for HTML
--------------------------
+.. _Additional roles for HTML:
+Semantic Inline Markup Roles
+----------------------------
+
The "html-roles.txt_" standard definitions file provides role
definitions for semantic `HTML inline markup elements`__ and
`tags for representation of edits to the document`__ that
@@ -182,16 +184,11 @@
(except for elements requiring an additional attribute).
The additional roles work out of the box with the `"html5" writer`_
-that selects the corresponding HTML element.
-LaTeX styling definitions are included. For best results add
-the LaTeX packages soul_ and xcolor_ to the `stylesheet setting`__.
+(selects the corresponding HTML element) and the LaTeX writers.
.. _html-roles.txt: ../../../docutils/parsers/rst/include/html-roles.txt
__ https://html.spec.whatwg.org/multipage/text-level-semantics.html
__ https://html.spec.whatwg.org/multipage/edits.html
-__ ../../user/config.html#stylesheet-2
-.. _soul: https://ctan.org/pkg/soul
-.. _xcolor: https://ctan.org/pkg/xcolor
.. class:: field-indent-4em
Modified: trunk/docutils/docutils/parsers/rst/include/html-roles.txt
===================================================================
--- trunk/docutils/docutils/parsers/rst/include/html-roles.txt 2026-01-07 07:52:27 UTC (rev 10284)
+++ trunk/docutils/docutils/parsers/rst/include/html-roles.txt 2026-01-07 07:52:49 UTC (rev 10285)
@@ -18,28 +18,3 @@
.. role:: u
.. role:: s
.. role:: var
-
-.. raw:: latex
-
- % Definitions for semantic HTML inline markup and representation of edits
- % (standard definition file "html-roles.txt").
- % Add "soul" to the "stylesheet" setting for markup test that wraps
- % and "xcolor" for yellow highlighting with :mark:`me`.
- \providecommand{\DUroleb}{\textbf}
- \providecommand{\DUroledel}{\st}
- \providecommand{\DUroledfn}{\emph}
- \providecommand{\DUrolei}{\textit}
- \providecommand{\DUroleins}{\ul}
- \providecommand{\DUrolekbd}{\texttt}
- \providecommand{\DUrolemark}{\hl}
- \providecommand{\DUroleq}[1]{“#1”}
- \providecommand{\DUroles}{\st}
- \providecommand{\DUrolesmall}[1]{{\footnotesize #1}}
- \providecommand{\DUroleu}{\underline}
- \providecommand{\DUrolevar}{\textit}
- % fallback definitions
- \providecommand{\ul}{\underline}
- \providecommand{\hl}{\underline} % highlight/mark
- \providecommand{\st}[1]{% strikethrough
- \raisebox{1ex}{\underline{\smash{\raisebox{-1ex}{#1}}}}%
- }
Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py 2026-01-07 07:52:27 UTC (rev 10284)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py 2026-01-07 07:52:49 UTC (rev 10285)
@@ -621,7 +621,7 @@
block_name = line.rstrip(':')
if not block_name:
continue
- definitions = _read_block(fp)
+ definitions = _read_block(fp) # all lines up to the next empty one
if block_name in ('color', 'float', 'table', 'textcomp'):
definitions = definitions.strip()
# print('Block: `%s`'% block_name)
@@ -1365,7 +1365,7 @@
else:
# require a minimal version:
self.fallbacks['_docutils.sty'] = (
- r'\usepackage{docutils}[2025-08-06]')
+ r'\usepackage{docutils}[2025-12-10]')
self.stylesheet = [self.stylesheet_call(path)
for path in stylesheet_list]
@@ -2556,6 +2556,12 @@
self.out.append(r'\foreignlanguage{%s}{' % language)
else:
self.provide_fallback('inline')
+ if hasattr(PreambleCmds, f'inline role {cls}'):
+ self.provide_fallback(f'inline role {cls}')
+ if cls in ('del', 'ins', 'mark', 's', 'u'):
+ self.requirements['soul'] = r'\usepackage{soul}'
+ if cls == 'mark':
+ self.requirements['color'] = PreambleCmds.color
self.out.append(r'\DUrole{%s}{' % cls)
def depart_inline(self, node) -> None:
Modified: trunk/docutils/docutils/writers/latex2e/docutils.sty
===================================================================
--- trunk/docutils/docutils/writers/latex2e/docutils.sty 2026-01-07 07:52:27 UTC (rev 10284)
+++ trunk/docutils/docutils/writers/latex2e/docutils.sty 2026-01-07 07:52:49 UTC (rev 10285)
@@ -22,7 +22,7 @@
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{docutils}
- [2025-08-06 macros for Docutils LaTeX output]
+ [2025-12-10 macros for Docutils LaTeX output]
% Helpers
% -------
@@ -149,6 +149,69 @@
\fi%
}
+% Definitions for `semantic HTML inline markup`__ and representation of edits
+%
+% __ https://docutils.sourceforge.io/docs/ref/rst/definitions.html#additional-roles-for-html
+
+% inline role b::
+
+\providecommand{\DUroleb}{\textbf}
+
+% inline role del::
+
+\providecommand{\DUroledel}{\st}
+
+% inline role dfn::
+
+\providecommand{\DUroledfn}{\emph}
+
+% inline role i::
+
+\providecommand{\DUrolei}{\textit}
+
+% inline role ins::
+
+\providecommand{\DUroleins}{\ul}
+
+% inline role kbd::
+
+\providecommand{\DUrolekbd}{\texttt}
+
+% inline role mark::
+
+\providecommand{\DUrolemark}{\hl}
+
+% inline role q::
+
+\providecommand{\DUroleq}[1]{“#1”}
+
+% inline role s::
+
+\providecommand{\DUroles}{\st}
+
+% inline role small::
+
+\providecommand{\DUrolesmall}[1]{{\footnotesize #1}}
+
+% inline role st::
+
+\providecommand{\DUroledel}{\st}
+
+% inline role u::
+
+\providecommand{\DUroleu}{\ul}
+
+% inline role var::
+
+\providecommand{\DUrolevar}{\textit}
+
+% Fallback hacks (Docutils loads "soul" for better implementation)
+\providecommand{\hl}{\underline}
+\providecommand{\st}[1]{%
+ \raisebox{1ex}{\underline{\smash{\raisebox{-1ex}{#1}}}}%
+}
+\providecommand{\ul}{\underline}
+
% legend::
% legend environment (in figures and formal tables)
Modified: trunk/docutils/test/functional/expected/latex_cornercases.tex
===================================================================
--- trunk/docutils/test/functional/expected/latex_cornercases.tex 2026-01-07 07:52:27 UTC (rev 10284)
+++ trunk/docutils/test/functional/expected/latex_cornercases.tex 2026-01-07 07:52:49 UTC (rev 10285)
@@ -7,6 +7,7 @@
\DeclareUnicodeCharacter{2663}{\ensuremath{\clubsuit}}
\usepackage{alltt}
\usepackage{amsmath}
+\usepackage{color}
\usepackage{float} % extended float configuration
\floatplacement{figure}{H} % place figures here definitely
\usepackage{graphicx}
@@ -13,6 +14,7 @@
\usepackage{multirow}
\usepackage{pifont}
\setcounter{secnumdepth}{0}
+\usepackage{soul}
\usepackage{longtable,ltcaption,array}
\setlength{\extrarowheight}{2pt}
\newlength{\DUtablewidth} % internal use in tables
@@ -65,6 +67,39 @@
}
\fi
+% custom inline roles: \DUrole{#1}{#2} tries \DUrole#1{#2}
+\providecommand*{\DUrole}[2]{%
+ \ifcsname DUrole#1\endcsname%
+ \csname DUrole#1\endcsname{#2}%
+ \else%
+ #2%
+ \fi%
+}
+
+\providecommand{\DUroleb}{\textbf}
+
+\providecommand{\DUroledel}{\st}
+
+\providecommand{\DUroledfn}{\emph}
+
+\providecommand{\DUrolei}{\textit}
+
+\providecommand{\DUroleins}{\ul}
+
+\providecommand{\DUrolekbd}{\texttt}
+
+\providecommand{\DUrolemark}{\hl}
+
+\providecommand{\DUroleq}[1]{“#1”}
+
+\providecommand{\DUroles}{\st}
+
+\providecommand{\DUrolesmall}[1]{{\footnotesize #1}}
+
+\providecommand{\DUroleu}{\ul}
+
+\providecommand{\DUrolevar}{\textit}
+
% legend environment (in figures and formal tables)
\ifdefined\DUlegend
\else
@@ -290,6 +325,152 @@
\includegraphics[width=1\linewidth]{../../../docs/user/rst/images/title.png}
+\section{Additional text roles}
+
+Including the \textquotedbl{}html-roles.txt\textquotedbl{} standard definition file adds
+roles matching semantic HTML inline markup elements.
+
+% Standard definition file for additional roles matching HTML tags.
+%
+% :Copyright: © 2025 Günter Milde.
+% :License: Released under the terms of the
+% `2-Clause BSD license <http://www.spdx.org/licenses/BSD-2-Clause>`__
+
+\setlength{\DUtablewidth}{\dimexpr\linewidth-4\arrayrulewidth\relax}%
+\begin{longtable*}{|p{\DUcolumnwidth{0.102}}|p{\DUcolumnwidth{0.271}}|p{\DUcolumnwidth{0.627}}|}
+\hline
+\textbf{%
+Role
+} & \textbf{%
+Example
+} & \textbf{%
+Notes
+} \\
+\hline
+\endfirsthead
+\hline
+\textbf{%
+Role
+} & \textbf{%
+Example
+} & \textbf{%
+Notes
+} \\
+\hline
+\endhead
+\multicolumn{3}{p{\DUcolumnwidth{1.000}}}{\raggedleft\ldots continued on next page}\\
+\endfoot
+\endlastfoot
+
+del
+ &
+\DUrole{del}{removed}
+ &
+removed content
+ \\
+\hline
+
+ins
+ &
+\DUrole{ins}{inserted}
+ &
+editional additions
+ \\
+\hline
+
+b
+ &
+\DUrole{b}{keyword}
+ &
+highlight \DUrole{b}{key words}
+without marking them up as important
+ \\
+\hline
+
+dfn
+ &
+\DUrole{dfn}{dfn}
+ &
+the defining instance of a term
+ \\
+\hline
+
+i
+ &
+\DUrole{i}{rôle}
+ &
+\DUrole{i}{voix alternative}
+ \\
+\hline
+
+kbd
+ &
+\texttt{\DUrole{kbd}{Ctrl X}}
+ &
+user input
+ \\
+\hline
+
+mark
+ &
+\DUrole{mark}{up}
+ &
+highlight a \DUrole{mark}{run of text}
+ \\
+\hline
+
+q
+ &
+\DUrole{q}{Tagline!}
+ &
+content quoted from another source
+ \\
+\hline
+
+s
+ &
+\DUrole{s}{strike}
+ &
+text that is inaccurate or
+no longer relevant
+ \\
+\hline
+
+samp
+ &
+\texttt{\DUrole{samp}{Ready!}}
+ &
+computer output
+ \\
+\hline
+
+small
+ &
+\DUrole{small}{print}
+ &
+side comments
+ \\
+\hline
+
+u
+ &
+\DUrole{u}{anotation}
+ &
+unarticulated annotations of, e.g,
+\DUrole{u}{comon mispellings}
+ \\
+\hline
+
+var
+ &
+\DUrole{var}{n}
+ &
+variables (or constants)
+ \\
+\hline
+\end{longtable*}
+
+
\section{Tables}
In contrast to HTML, LaTeX does not support line-breaks in tables with
Modified: trunk/docutils/test/functional/expected/latex_literal_block.tex
===================================================================
--- trunk/docutils/test/functional/expected/latex_literal_block.tex 2026-01-07 07:52:27 UTC (rev 10284)
+++ trunk/docutils/test/functional/expected/latex_literal_block.tex 2026-01-07 07:52:49 UTC (rev 10285)
@@ -19,7 +19,7 @@
%%% User specified packages and stylesheets
%%% Fallback definitions for Docutils-specific commands
-\usepackage{docutils}[2025-08-06]
+\usepackage{docutils}[2025-12-10]
% 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 2026-01-07 07:52:27 UTC (rev 10284)
+++ trunk/docutils/test/functional/expected/latex_literal_block_fancyvrb.tex 2026-01-07 07:52:49 UTC (rev 10285)
@@ -19,7 +19,7 @@
%%% User specified packages and stylesheets
%%% Fallback definitions for Docutils-specific commands
-\usepackage{docutils}[2025-08-06]
+\usepackage{docutils}[2025-12-10]
% 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 2026-01-07 07:52:27 UTC (rev 10284)
+++ trunk/docutils/test/functional/expected/latex_literal_block_listings.tex 2026-01-07 07:52:49 UTC (rev 10285)
@@ -25,7 +25,7 @@
%%% User specified packages and stylesheets
%%% Fallback definitions for Docutils-specific commands
-\usepackage{docutils}[2025-08-06]
+\usepackage{docutils}[2025-12-10]
% 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 2026-01-07 07:52:27 UTC (rev 10284)
+++ trunk/docutils/test/functional/expected/latex_literal_block_verbatim.tex 2026-01-07 07:52:49 UTC (rev 10285)
@@ -18,7 +18,7 @@
%%% User specified packages and stylesheets
%%% Fallback definitions for Docutils-specific commands
-\usepackage{docutils}[2025-08-06]
+\usepackage{docutils}[2025-12-10]
% 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 2026-01-07 07:52:27 UTC (rev 10284)
+++ trunk/docutils/test/functional/expected/latex_literal_block_verbatimtab.tex 2026-01-07 07:52:49 UTC (rev 10285)
@@ -19,7 +19,7 @@
%%% User specified packages and stylesheets
%%% Fallback definitions for Docutils-specific commands
-\usepackage{docutils}[2025-08-06]
+\usepackage{docutils}[2025-12-10]
% character width in monospaced font
\newlength{\ttemwidth}
Modified: trunk/docutils/test/functional/expected/length_units_latex.tex
===================================================================
--- trunk/docutils/test/functional/expected/length_units_latex.tex 2026-01-07 07:52:27 UTC (rev 10284)
+++ trunk/docutils/test/functional/expected/length_units_latex.tex 2026-01-07 07:52:49 UTC (rev 10285)
@@ -22,7 +22,7 @@
\usepackage{nohyperref}
%%% Fallback definitions for Docutils-specific commands
-\usepackage{docutils}[2025-08-06]
+\usepackage{docutils}[2025-12-10]
\ifdefined\DUchdimen % lengh unit "ch": width of a zero char
\else
Modified: trunk/docutils/test/functional/expected/standalone_rst_xetex.tex
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_xetex.tex 2026-01-07 07:52:27 UTC (rev 10284)
+++ trunk/docutils/test/functional/expected/standalone_rst_xetex.tex 2026-01-07 07:52:49 UTC (rev 10285)
@@ -33,7 +33,7 @@
%%% User specified packages and stylesheets
%%% Fallback definitions for Docutils-specific commands
-\usepackage{docutils}[2025-08-06]
+\usepackage{docutils}[2025-12-10]
\newcounter{enumv}
\DUprovidelength{\pdfpxdimen}{1bp}
Modified: trunk/docutils/test/functional/input/latex_cornercases.rst
===================================================================
--- trunk/docutils/test/functional/input/latex_cornercases.rst 2026-01-07 07:52:27 UTC (rev 10284)
+++ trunk/docutils/test/functional/input/latex_cornercases.rst 2026-01-07 07:52:49 UTC (rev 10285)
@@ -53,6 +53,36 @@
.. image:: ../../../docs/user/rst/images/title.png
:width: 100%
+
+Additional text roles
+=====================
+
+Including the "html-roles.txt" standard definition file adds
+roles matching semantic HTML inline markup elements.
+
+.. include:: <html-roles.txt>
+
+===== =============== ====================================
+Role Example Notes
+===== =============== ====================================
+del :del:`removed` removed content
+ins :ins:`inserted` editional additions
+b :b:`keyword` highlight :b:`key words`
+ without marking them up as important
+dfn :dfn:`dfn` the defining instance of a term
+i :i:`rôle` :i:`voix alternative`
+kbd :kbd:`Ctrl X` user input
+mark :mark:`up` highlight a :mark:`run of text`
+q :q:`Tagline!` content quoted from another source
+s :s:`strike` text that is inaccurate or
+ no longer relevant
+samp :samp:`Ready!` computer output
+small :small:`print` side comments
+u :u:`anotation` unarticulated annotations of, e.g,
+ :u:`comon mispellings`
+var :var:`n` variables (or constants)
+===== =============== ====================================
+
.. include:: data/tables_latex.rst
.. include:: data/nonalphanumeric.rst
.. include:: data/unicode.rst
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
