Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[10112] trunk/docutils
|
From: <mi...@us...> - 2025-04-27 20:43:32
|
Revision: 10112
http://sourceforge.net/p/docutils/code/10112
Author: milde
Date: 2025-04-27 20:43:12 +0000 (Sun, 27 Apr 2025)
Log Message:
-----------
New "standard definition file" with additional role definition.
The new file "html-roles.txt" provides role definitions for
"semantic HTML inline markup elements" and
"tags for representation of edits to the document".
The additional roles "b", "bdi", "del", "dfn", "i", "ins",
"kbd", "mark", "q", "samp", "small", "u", "s", and "var"
work out of the box with the "html5" writer.
LaTeX styling definitions are inlcuded.
Modified Paths:
--------------
trunk/docutils/docs/dev/todo.rst
trunk/docutils/docs/ref/rst/definitions.rst
Added Paths:
-----------
trunk/docutils/docutils/parsers/rst/include/html-roles.txt
Modified: trunk/docutils/docs/dev/todo.rst
===================================================================
--- trunk/docutils/docs/dev/todo.rst 2025-04-25 22:52:19 UTC (rev 10111)
+++ trunk/docutils/docs/dev/todo.rst 2025-04-27 20:43:12 UTC (rev 10112)
@@ -1994,6 +1994,9 @@
.. |reST| acronym:: reST
:text: reStructuredText
+ 5. Use square brackets for positional and named options like AsciiDoc
+ (cf. https://sourceforge.net/p/docutils/feature-requests/68/).
+
What do we do for other formats than HTML which do not support
tool tips? Put the full text in parentheses?
Modified: trunk/docutils/docs/ref/rst/definitions.rst
===================================================================
--- trunk/docutils/docs/ref/rst/definitions.rst 2025-04-25 22:52:19 UTC (rev 10111)
+++ trunk/docutils/docs/ref/rst/definitions.rst 2025-04-27 20:43:12 UTC (rev 10112)
@@ -1,4 +1,5 @@
.. include:: ../../header2.rst
+.. include:: <html-roles.txt>
============================================
reStructuredText Standard Definition Files
@@ -161,8 +162,66 @@
.. _xhtml1-symbol.txt: ../../../docutils/parsers/rst/include/xhtml1-symbol.txt
+Role Definitions
+================
+
+Role definitions use the `"role" directive`_ to provide additional
+`reStructuredText interpreted text roles`_.
+
+.. _"role" directive: directives.html#role
+.. _reStructuredText interpreted text roles: roles.html
+
+
+Additional roles for HTML
+-------------------------
+
+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
+do not have a corresponding standard rST role
+(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`__.
+
+.. _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
+
+:b: highlight :b:`key words` without marking them up as important
+:bdi: text :bdi:`directionality` isolation [#attribute-optional]_
+:del: :del:`represents` removed content [#attribute-optional]_
+:dfn: :dfn:`dfn` represents the defining instance of a term
+ [#attribute-optional]_
+:i: :i:`voix alternative`
+:ins: :ins:`editional` additions [#attribute-optional]_
+:kbd: user input like :kbd:`Ctrl X`
+:mark: :mark:`highlight` a run of text
+:q: represents :q:`phrasing content quoted from another source`
+ [#attribute-optional]_
+:s: text that is no longer accurate, :s:`or no longer relevant`
+:samp: computer output like :samp:`hello world!`
+:small: side comments :small:`like this`
+:u: unarticulated annotations of, e.g, :u:`mispellings`
+:var: variables (or constants like :var:`c`)
+
+.. [#attribute-optional] Would gain from support for attributes/arguments
+ to inline roles (see TODO_).
+
+.. _TODO: https://docutils.sourceforge.io/docs/dev/todo.html
+ #acronym-and-abbreviation
+.. _"html5" writer: ../../user/html.html#html5
+
+
S5/HTML Definitions
-===================
+-------------------
The "s5defs.txt_" standard definition file contains interpreted text
roles (classes) and other definitions for documents destined to become
Added: trunk/docutils/docutils/parsers/rst/include/html-roles.txt
===================================================================
--- trunk/docutils/docutils/parsers/rst/include/html-roles.txt (rev 0)
+++ trunk/docutils/docutils/parsers/rst/include/html-roles.txt 2025-04-27 20:43:12 UTC (rev 10112)
@@ -0,0 +1,45 @@
+.. Standard definition file for additonal 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>`__
+
+.. role:: b
+.. role:: bdi
+.. role:: del
+.. role:: dfn
+.. role:: i
+.. role:: ins
+.. role:: kbd(literal)
+.. role:: mark
+.. role:: q
+.. role:: samp(literal)
+.. role:: small
+.. 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}}}}%
+ }
Property changes on: trunk/docutils/docutils/parsers/rst/include/html-roles.txt
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: svn:keywords
## -0,0 +1 ##
+Author Date Id Revision
\ No newline at end of property
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
