Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[9118] trunk/docutils
|
From: <mi...@us...> - 2022-07-29 11:57:03
|
Revision: 9118
http://sourceforge.net/p/docutils/code/9118
Author: milde
Date: 2022-07-29 11:56:58 +0000 (Fri, 29 Jul 2022)
Log Message:
-----------
Improve internationalisation documentation
Add links to documentation of translated terms.
Sort mappings to better match documentation
and keep related terms together.
Modified Paths:
--------------
trunk/docutils/docs/howto/i18n.txt
trunk/docutils/docs/ref/rst/roles.txt
trunk/docutils/docutils/parsers/rst/languages/en.py
Modified: trunk/docutils/docs/howto/i18n.txt
===================================================================
--- trunk/docutils/docs/howto/i18n.txt 2022-07-29 11:56:46 UTC (rev 9117)
+++ trunk/docutils/docs/howto/i18n.txt 2022-07-29 11:56:58 UTC (rev 9118)
@@ -88,10 +88,10 @@
``labels``
This is a mapping of node class names to language-dependent
boilerplate label text. The label text is used by Writer
- components when they encounter document tree elements whose class
- names are the mapping keys.
+ components when they encounter `document tree`_ elements whose
+ `class names`_ are the mapping keys.
- The entry values (*not* the keys) should be translated to the
+ The entry **values** (*not* the keys) should be translated to the
target language.
``bibliographic_fields``
@@ -98,12 +98,12 @@
This is a mapping of language-dependent field names (converted to
lower case) to canonical field names (keys of
``DocInfo.biblio_notes`` in ``docutils.transforms.frontmatter``).
- It is used when transforming bibliographic fields.
+ It is used when transforming `bibliographic fields`_.
- The keys should be translated to the target language.
+ The **keys** should be translated to the target language.
``author_separators``
- This is a list of strings used to parse the 'Authors'
+ This is a list of strings used to parse the 'Authors_'
bibliographic field. They separate individual authors' names, and
are tried in order (i.e., earlier items take priority, and the
first item that matches wins). The English-language module
@@ -112,7 +112,16 @@
Most languages won't have to "translate" this list.
+.. _document tree:
+ ../ref/doctree.html
+.. _class names:
+ ../ref/doctree.html#element-reference
+.. _authors:
+ .. ref/doctree.html#authors
+.. _bibliographic fields:
+ ../ref/rst/restructuredtext.html#bibliographic-fields
+
reStructuredText Language Module
================================
@@ -127,8 +136,9 @@
``directives``
This is a mapping from language-dependent directive names to
canonical directive names. The canonical directive names are
- registered in ``docutils/parsers/rst/directives/__init__.py``, in
- ``_directive_registry``.
+ registered in ``docutils/parsers/rst/directives/__init__.py``,
+ in ``_directive_registry`` and documented in
+ `reStructuredText Directives`_.
The keys should be translated to the target language. Synonyms
(multiple keys with the same values) are allowed; this is useful
@@ -136,15 +146,19 @@
``roles``
This is a mapping language-dependent role names to canonical role
- names for interpreted text. The canonical directive names are
+ names for interpreted text. The canonical role names are
registered in ``docutils/parsers/rst/states.py``, in
- ``Inliner._interpreted_roles`` (this may change).
+ ``Inliner._interpreted_roles`` (this may change) and documented
+ in `reStructuredText Interpreted Text Roles`_.
The keys should be translated to the target language. Synonyms
(multiple keys with the same values) are allowed; this is useful
for abbreviations.
+.. _reStructuredText Directives: ../ref/rst/directives.html
+.. _reStructuredText Interpreted Text Roles: ../ref/rst/roles.html
+
Testing the Language Modules
============================
Modified: trunk/docutils/docs/ref/rst/roles.txt
===================================================================
--- trunk/docutils/docs/ref/rst/roles.txt 2022-07-29 11:56:46 UTC (rev 9117)
+++ trunk/docutils/docs/ref/rst/roles.txt 2022-07-29 11:56:58 UTC (rev 9118)
@@ -9,10 +9,10 @@
:Revision: $Revision$
:Date: $Date$
:Copyright: This document has been placed in the public domain.
+:Abstract:
+ This document describes the interpreted text roles implemented in the
+ reference reStructuredText parser.
-This document describes the interpreted text roles implemented in the
-reference reStructuredText parser.
-
Interpreted text uses backquotes (`) around the text. An explicit
role marker may optionally appear before or after the text, delimited
with colons. For example::
@@ -66,51 +66,37 @@
Standard Roles
----------------
-``:emphasis:``
-==============
-:Aliases: None
-:DTD Element: emphasis
+``:abbreviation:``
+==================
+
+:Aliases: ``:ab:``
+:DTD Element: abbreviation_
:Customization:
:Options: class_.
:Content: None.
-Implements emphasis. These are equivalent::
+An abbreviation used in the document.
+An example of an abbreviation is ‘St’ being used instead of ‘Street’.
- *text*
- :emphasis:`text`
+``:acronym:``
+==================
-``:literal:``
-==============
-
-:Aliases: None
-:DTD Element: literal
+:Aliases: ``:ac:``
+:DTD Element: acronym_
:Customization:
:Options: class_.
:Content: None.
-Implements inline literal text. These are equivalent::
+An acronym.
- ``text``
- :literal:`text`
-Care must be taken with backslash-escapes though. These are *not*
-equivalent::
-
- ``text \ and \ backslashes``
- :literal:`text \ and \ backslashes`
-
-The backslashes in the first line are preserved (and do nothing),
-whereas the backslashes in the second line escape the following
-spaces.
-
-
``:code:``
==========
:Aliases: None
-:DTD Element: literal
+:DTD Element: literal_
:Customization:
:Options: class_, language
:Content: None.
@@ -143,11 +129,51 @@
.. _supported languages and markup formats: https://pygments.org/languages/
+``:emphasis:``
+==============
+
+:Aliases: None
+:DTD Element: emphasis_
+:Customization:
+ :Options: class_.
+ :Content: None.
+
+Implements emphasis. These are equivalent::
+
+ *text*
+ :emphasis:`text`
+
+
+``:literal:``
+==============
+
+:Aliases: None
+:DTD Element: literal_
+:Customization:
+ :Options: class_.
+ :Content: None.
+
+Implements inline literal text. These are equivalent::
+
+ ``text``
+ :literal:`text`
+
+Care must be taken with backslash-escapes though. These are *not*
+equivalent::
+
+ ``text \ and \ backslashes``
+ :literal:`text \ and \ backslashes`
+
+The backslashes in the first line are preserved (and do nothing),
+whereas the backslashes in the second line escape the following
+spaces.
+
+
``:math:``
==========
:Aliases: None
-:DTD Element: math
+:DTD Element: math_
:Customization:
:Options: class_
:Content: None.
@@ -172,7 +198,7 @@
===================
:Aliases: ``:PEP:``
-:DTD Element: reference
+:DTD Element: reference_
:Customization:
:Options: class_.
:Content: None.
@@ -194,7 +220,7 @@
===================
:Aliases: ``:RFC:``
-:DTD Element: reference
+:DTD Element: reference_
:Customization:
:Options: class_.
:Content: None.
@@ -227,7 +253,7 @@
============
:Aliases: None
-:DTD Element: strong
+:DTD Element: strong_
:Customization:
:Options: class_.
:Content: None.
@@ -242,7 +268,7 @@
===============
:Aliases: ``:sub:``
-:DTD Element: subscript
+:DTD Element: subscript_
:Customization:
:Options: class_.
:Content: None.
@@ -278,7 +304,7 @@
=================
:Aliases: ``:sup:``
-:DTD Element: superscript
+:DTD Element: superscript_
:Customization:
:Options: class_.
:Content: None.
@@ -290,7 +316,7 @@
=====================
:Aliases: ``:title:``, ``:t:``.
-:DTD Element: title_reference
+:DTD Element: title_reference_
:Customization:
:Options: class_.
:Content: None.
@@ -339,7 +365,7 @@
=======
:Aliases: None
-:DTD Element: raw
+:DTD Element: raw_
:Customization:
:Options: class_, format
:Content: None
@@ -391,3 +417,17 @@
``format`` : text
One or more space-separated output format names (Writer names).
+
+
+.. References
+
+.. _abbreviation: ../doctree.html#abbreviation
+.. _acronym: ../doctree.html#acronym
+.. _emphasis: ../doctree.html#emphasis
+.. _literal: ../doctree.html#literal
+.. _math: ../doctree.html#math
+.. _reference: ../doctree.html#reference
+.. _strong: ../doctree.html#strong
+.. _subscript: ../doctree.html#subscript
+.. _superscript: ../doctree.html#superscript
+.. _title_reference: ../doctree.html#title-reference
Modified: trunk/docutils/docutils/parsers/rst/languages/en.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/languages/en.py 2022-07-29 11:56:46 UTC (rev 9117)
+++ trunk/docutils/docutils/parsers/rst/languages/en.py 2022-07-29 11:56:58 UTC (rev 9118)
@@ -19,9 +19,6 @@
# language-dependent: fixed
'attention': 'attention',
'caution': 'caution',
- 'code': 'code',
- 'code-block': 'code',
- 'sourcecode': 'code',
'danger': 'danger',
'error': 'error',
'hint': 'hint',
@@ -34,6 +31,10 @@
'topic': 'topic',
'line-block': 'line-block',
'parsed-literal': 'parsed-literal',
+ 'code': 'code',
+ 'code-block': 'code',
+ 'sourcecode': 'code',
+ 'math': 'math',
'rubric': 'rubric',
'epigraph': 'epigraph',
'highlights': 'highlights',
@@ -40,14 +41,10 @@
'pull-quote': 'pull-quote',
'compound': 'compound',
'container': 'container',
- # 'questions': 'questions',
'table': 'table',
'csv-table': 'csv-table',
'list-table': 'list-table',
- # 'qa': 'questions',
- # 'faq': 'questions',
'meta': 'meta',
- 'math': 'math',
# 'imagemap': 'imagemap',
'image': 'image',
'figure': 'figure',
@@ -69,9 +66,12 @@
# 'citations': 'citations',
'target-notes': 'target-notes',
'restructuredtext-test-directive': 'restructuredtext-test-directive'}
-"""English name to registered (in directives/__init__.py) directive name
-mapping."""
+"""Mapping of English directive name to registered directive names
+Cf. https://docutils.sourceforge.io/docs/ref/rst/directives.html
+and `_directive_registry` in ``directives/__init__.py``.
+"""
+
roles = {
# language-dependent: fixed
'abbreviation': 'abbreviation',
@@ -79,8 +79,14 @@
'acronym': 'acronym',
'ac': 'acronym',
'code': 'code',
- 'index': 'index',
- 'i': 'index',
+ 'emphasis': 'emphasis',
+ 'literal': 'literal',
+ 'math': 'math',
+ 'pep-reference': 'pep-reference',
+ 'pep': 'pep-reference',
+ 'rfc-reference': 'rfc-reference',
+ 'rfc': 'rfc-reference',
+ 'strong': 'strong',
'subscript': 'subscript',
'sub': 'subscript',
'superscript': 'superscript',
@@ -88,24 +94,21 @@
'title-reference': 'title-reference',
'title': 'title-reference',
't': 'title-reference',
- 'pep-reference': 'pep-reference',
- 'pep': 'pep-reference',
- 'rfc-reference': 'rfc-reference',
- 'rfc': 'rfc-reference',
- 'emphasis': 'emphasis',
- 'strong': 'strong',
- 'literal': 'literal',
- 'math': 'math',
- 'named-reference': 'named-reference',
+ 'raw': 'raw',
+ # the following roles are not implemented in Docutils
+ 'index': 'index',
+ 'i': 'index',
'anonymous-reference': 'anonymous-reference',
+ 'citation-reference': 'citation-reference',
'footnote-reference': 'footnote-reference',
- 'citation-reference': 'citation-reference',
+ 'named-reference': 'named-reference',
'substitution-reference': 'substitution-reference',
- 'target': 'target',
'uri-reference': 'uri-reference',
'uri': 'uri-reference',
'url': 'uri-reference',
- 'raw': 'raw',
+ 'target': 'target',
}
"""Mapping of English role names to canonical role names for interpreted text.
+
+Cf. https://docutils.sourceforge.io/docs/ref/rst/roles.html
"""
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
