added "default-role" directive

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3427 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

21 files changed, 170 insertions, 0 deletions

diff --git a/HISTORY.txt b/HISTORY.txt
index 1fe8b1092..f862d4896 100644
--- a/HISTORY.txt
+++ b/HISTORY.txt
@@ -24,6 +24,10 @@ Changes Since 0.3.9
   - Added validator to tab_width setting, with test.  Closes SF bug
     #1212515, report from Wu Wei.
 
+* docutils/parsers/rst/directives/misc.py:
+
+  - Added the "default-role" directive.
+
 
 Release 0.3.9 (2005-05-26)
 ==========================
diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 603b89b98..d336a48dd 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -1542,6 +1542,49 @@ details.
 .. _reStructuredText Interpreted Text Roles: roles.html
 
 
+.. _default-role:
+
+Setting the Default Interpreted Text Role
+=========================================
+
+:Directive Type: "default-role"
+:Doctree Element: None; affects subsequent parsing.
+:Directive Arguments: One, optional (new default role name).
+:Directive Options: None.
+:Directive Content: None.
+
+(New in Docutils 0.3.8)
+
+The "default-role" directive sets the default interpreted text role,
+the role that is used for interpreted text without an explicit role.
+For example, after setting the default role like this::
+
+    .. default-role:: subscript
+
+any subsequent use of implicit-role interpreted text in the document
+will use the "subscript" role::
+
+    An example of a `default` role.
+
+This will be parsed into the following document tree fragment::
+
+    <paragraph>
+        An example of a
+        <subscript>
+            default
+         role.
+
+Custom roles may be used (see the "role_" directive above), but it
+must have been declared in a document before it can be set as the
+default role.  See the `reStructuredText Interpreted Text Roles`_
+document for details of built-in roles.
+
+The directive may be used without an argument to restore the initial
+default interpreted text role, which is application-dependent.  The
+initial default interpreted text role of the standard reStructuredText
+parser is "title-reference".
+
+
 Restructuredtext-Test-Directive
 ===============================
 
diff --git a/docutils/parsers/rst/directives/__init__.py b/docutils/parsers/rst/directives/__init__.py
index 8e9f42284..1db0c76e0 100644
--- a/docutils/parsers/rst/directives/__init__.py
+++ b/docutils/parsers/rst/directives/__init__.py
@@ -131,6 +131,7 @@ _directive_registry = {
       'unicode': ('misc', 'unicode_directive'),
       'class': ('misc', 'class_directive'),
       'role': ('misc', 'role'),
+      'default-role': ('misc', 'default_role'),
       'restructuredtext-test-directive': ('misc', 'directive_test_function'),}
 """Mapping of directive name to (module name, function name).  The directive
 name is canonical & must be lowercase.  Language-dependent names are defined
diff --git a/docutils/parsers/rst/directives/misc.py b/docutils/parsers/rst/directives/misc.py
index 7bae832d2..7007546df 100644
--- a/docutils/parsers/rst/directives/misc.py
+++ b/docutils/parsers/rst/directives/misc.py
@@ -329,6 +329,28 @@ def role(name, arguments, options, content, lineno,
 
 role.content = 1
 
+def default_role(name, arguments, options, content, lineno,
+                 content_offset, block_text, state, state_machine):
+    """Set the default interpreted text role."""
+    if not arguments:
+        if roles._roles.has_key(''):
+            # restore the "default" default role
+            del roles._roles['']
+        return []
+    role_name = arguments[0]
+    role, messages = roles.role(
+        role_name, state_machine.language, lineno, state.reporter)
+    if role is None:
+        error = state.reporter.error(
+            'Unknown interpreted text role "%s".' % role_name,
+            nodes.literal_block(block_text, block_text), line=lineno)
+        return messages + [error]
+    roles._roles[''] = role
+    # @@@ should this be local to the document, not the parser?
+    return messages
+
+default_role.arguments = (0, 1, 0)
+
 def directive_test_function(name, arguments, options, content, lineno,
                             content_offset, block_text, state, state_machine):
     """This directive is useful only for testing purposes."""
diff --git a/docutils/parsers/rst/languages/af.py b/docutils/parsers/rst/languages/af.py
index 9dddae716..7304f153b 100644
--- a/docutils/parsers/rst/languages/af.py
+++ b/docutils/parsers/rst/languages/af.py
@@ -53,6 +53,7 @@ directives = {
       'unicode': 'unicode', # should this be translated? unikode
       'klas': 'class',
       'role (translation required)': 'role',
+      'default-role (translation required)': 'default-role',
       'inhoud': 'contents',
       'sectnum': 'sectnum',
       'section-numbering': 'sectnum',
diff --git a/docutils/parsers/rst/languages/ca.py b/docutils/parsers/rst/languages/ca.py
index 9fdce400d..691887325 100644
--- a/docutils/parsers/rst/languages/ca.py
+++ b/docutils/parsers/rst/languages/ca.py
@@ -58,6 +58,7 @@ directives = {
       u'unicode': 'unicode',
       u'classe': 'class',
       u'rol': 'role',
+      u'default-role (translation required)': 'default-role',
       u'contingut': 'contents',
       u'numsec': 'sectnum',
       u'numeraci\u00F3-de-seccions': 'sectnum',
diff --git a/docutils/parsers/rst/languages/cs.py b/docutils/parsers/rst/languages/cs.py
index 7163cbf8f..24087badf 100644
--- a/docutils/parsers/rst/languages/cs.py
+++ b/docutils/parsers/rst/languages/cs.py
@@ -54,6 +54,7 @@ directives = {
       u'unicode (translation required)': 'unicode',
       u't\u0159\u00EDda': 'class',
       u'role (translation required)': 'role',
+      u'default-role (translation required)': 'default-role',
       u'obsah': 'contents',
       u'sectnum (translation required)': 'sectnum',
       u'section-numbering (translation required)': 'sectnum',
diff --git a/docutils/parsers/rst/languages/de.py b/docutils/parsers/rst/languages/de.py
index 9431f0e9d..56cca5c5b 100644
--- a/docutils/parsers/rst/languages/de.py
+++ b/docutils/parsers/rst/languages/de.py
@@ -56,6 +56,7 @@ directives = {
       'unicode': 'unicode',
       'klasse': 'class',
       'rolle': 'role',
+      u'default-role (translation required)': 'default-role',
       'inhalt': 'contents',
       'kapitel-nummerierung': 'sectnum',
       'abschnitts-nummerierung': 'sectnum',
diff --git a/docutils/parsers/rst/languages/en.py b/docutils/parsers/rst/languages/en.py
index 63ddcb1b9..46822b891 100644
--- a/docutils/parsers/rst/languages/en.py
+++ b/docutils/parsers/rst/languages/en.py
@@ -54,6 +54,7 @@ directives = {
       'unicode': 'unicode',
       'class': 'class',
       'role': 'role',
+      'default-role': 'default-role',
       'contents': 'contents',
       'sectnum': 'sectnum',
       'section-numbering': 'sectnum',
diff --git a/docutils/parsers/rst/languages/eo.py b/docutils/parsers/rst/languages/eo.py
index 069fea45e..99b6d6970 100644
--- a/docutils/parsers/rst/languages/eo.py
+++ b/docutils/parsers/rst/languages/eo.py
@@ -60,6 +60,7 @@ directives = {
       u'unicode': 'unicode',
       u'klaso': 'class',
       u'rolo': 'role',
+      u'default-role (translation required)': 'default-role',
       u'enhavo': 'contents',
       u'seknum': 'sectnum',
       u'sekcia-numerado': 'sectnum',
diff --git a/docutils/parsers/rst/languages/es.py b/docutils/parsers/rst/languages/es.py
index 5f0a094da..726d97e88 100644
--- a/docutils/parsers/rst/languages/es.py
+++ b/docutils/parsers/rst/languages/es.py
@@ -62,6 +62,7 @@ directives = {
       u'unicode': 'unicode',
       u'clase': 'class',
       u'rol': 'role',
+      u'default-role (translation required)': 'default-role',
       u'contenido': 'contents',
       u'numseccion': 'sectnum',
       u'numsecci\u00f3n': 'sectnum',
diff --git a/docutils/parsers/rst/languages/fi.py b/docutils/parsers/rst/languages/fi.py
index c60444e3f..ba159cc70 100644
--- a/docutils/parsers/rst/languages/fi.py
+++ b/docutils/parsers/rst/languages/fi.py
@@ -52,6 +52,7 @@ directives = {
       u'unicode': u'unicode',
       u'luokka': u'class',
       u'rooli': u'role',
+      u'default-role (translation required)': 'default-role',
       u'sis\u00e4llys': u'contents',
       u'kappale': u'sectnum',
       u'header (translation required)': 'header',
diff --git a/docutils/parsers/rst/languages/fr.py b/docutils/parsers/rst/languages/fr.py
index 8b9cb04de..acb8d35e6 100644
--- a/docutils/parsers/rst/languages/fr.py
+++ b/docutils/parsers/rst/languages/fr.py
@@ -56,6 +56,7 @@ directives = {
       u'unicode': 'unicode',
       u'classe': 'class',
       u'role (translation required)': 'role',
+      u'default-role (translation required)': 'default-role',
       u'sommaire': 'contents',
       u'table-des-mati\u00E8res': 'contents',
       u'sectnum': 'sectnum',
diff --git a/docutils/parsers/rst/languages/it.py b/docutils/parsers/rst/languages/it.py
index ee31b42ae..f3afd2d35 100644
--- a/docutils/parsers/rst/languages/it.py
+++ b/docutils/parsers/rst/languages/it.py
@@ -53,6 +53,7 @@ directives = {
       'unicode': 'unicode',
       'classe': 'class',
       'ruolo': 'role',
+      u'default-role (translation required)': 'default-role',
       'indice': 'contents',
       'contenuti': 'contents',
       'seznum': 'sectnum',
diff --git a/docutils/parsers/rst/languages/nl.py b/docutils/parsers/rst/languages/nl.py
index 35942ca05..273828062 100644
--- a/docutils/parsers/rst/languages/nl.py
+++ b/docutils/parsers/rst/languages/nl.py
@@ -55,6 +55,7 @@ directives = {
       'unicode': 'unicode',
       'klasse': 'class',
       'rol': 'role',
+      u'default-role (translation required)': 'default-role',
       'inhoud': 'contents',
       'sectnum': 'sectnum',
       'sectie-nummering': 'sectnum',
diff --git a/docutils/parsers/rst/languages/pt_br.py b/docutils/parsers/rst/languages/pt_br.py
index 6f5d4cc6b..8a2534923 100644
--- a/docutils/parsers/rst/languages/pt_br.py
+++ b/docutils/parsers/rst/languages/pt_br.py
@@ -54,6 +54,7 @@ directives = {
       'unicode': 'unicode',
       'classe': 'class',
       'role (translation required)': 'role',
+      u'default-role (translation required)': 'default-role',
       u'\u00EDndice': 'contents',
       'numsec': 'sectnum',
       u'numera\u00E7\u00E3o-de-se\u00E7\u00F5es': 'sectnum',
diff --git a/docutils/parsers/rst/languages/ru.py b/docutils/parsers/rst/languages/ru.py
index 4ccca658c..23a842399 100644
--- a/docutils/parsers/rst/languages/ru.py
+++ b/docutils/parsers/rst/languages/ru.py
@@ -45,6 +45,7 @@ directives = {
  u'image',
  u'\u043a\u043b\u0430\u0441\u0441': u'class',
  u'role (translation required)': 'role',
+ u'default-role (translation required)': 'default-role',
  u'\u043d\u043e\u043c\u0435\u0440-\u0440\u0430\u0437\u0434\u0435\u043b\u0430':
  u'sectnum',
  u'\u043d\u0443\u043c\u0435\u0440\u0430\u0446\u0438\u044f-\u0440\u0430\u0437'
diff --git a/docutils/parsers/rst/languages/sk.py b/docutils/parsers/rst/languages/sk.py
index 2ba849700..e58296280 100644
--- a/docutils/parsers/rst/languages/sk.py
+++ b/docutils/parsers/rst/languages/sk.py
@@ -53,6 +53,7 @@ directives = {
       u'unicode': 'unicode',
       u'class (translation required)': 'class',
       u'role (translation required)': 'role',
+      u'default-role (translation required)': 'default-role',
       u'obsah': 'contents',
       u'\xe8as\x9d': 'sectnum',
       u'\xe8as\x9d-\xe8\xedslovanie': 'sectnum',
diff --git a/docutils/parsers/rst/languages/sv.py b/docutils/parsers/rst/languages/sv.py
index d6f6fba46..59d13f699 100644
--- a/docutils/parsers/rst/languages/sv.py
+++ b/docutils/parsers/rst/languages/sv.py
@@ -53,6 +53,7 @@ directives = {
       u'unicode': 'unicode',
       u'class (translation required)': 'class',
       u'role (translation required)': 'role',
+      u'default-role (translation required)': 'default-role',
       u'inneh\u00e5ll': 'contents',
       u'sektionsnumrering': 'sectnum',
       u'target-notes (translation required)': 'target-notes',
diff --git a/docutils/parsers/rst/languages/zh_tw.py b/docutils/parsers/rst/languages/zh_tw.py
index 15f253114..3eaea044a 100644
--- a/docutils/parsers/rst/languages/zh_tw.py
+++ b/docutils/parsers/rst/languages/zh_tw.py
@@ -54,6 +54,7 @@ directives = {
       'unicode (translation required)': 'unicode',
       'class (translation required)': 'class',
       'role (translation required)': 'role',
+      u'default-role (translation required)': 'default-role',
       'contents (translation required)': 'contents',
       'sectnum (translation required)': 'sectnum',
       'section-numbering (translation required)': 'sectnum',
diff --git a/test/test_parsers/test_rst/test_directives/test_default_role.py b/test/test_parsers/test_rst/test_directives/test_default_role.py
new file mode 100755
index 000000000..fc9343247
--- /dev/null
+++ b/test/test_parsers/test_rst/test_directives/test_default_role.py
@@ -0,0 +1,84 @@
+#! /usr/bin/env python
+
+# Author: David Goodger
+# Contact: goodger@python.org
+# Revision: $Revision$
+# Date: $Date$
+# Copyright: This module has been placed in the public domain.
+
+"""
+Tests for misc.py "default-role" directive.
+"""
+
+from __init__ import DocutilsTestSupport
+
+
+def suite():
+    s = DocutilsTestSupport.ParserTestSuite()
+    s.generateTests(totest)
+    return s
+
+totest = {}
+
+totest['default-role'] = [
+["""\
+.. default-role:: subscript
+
+This is a `subscript`.
+""",
+"""\
+<document source="test data">
+    <paragraph>
+        This is a \n\
+        <subscript>
+            subscript
+        .
+"""],
+["""\
+Must define a custom role before using it.
+
+.. default-role:: custom
+""",
+"""\
+<document source="test data">
+    <paragraph>
+        Must define a custom role before using it.
+    <system_message level="1" line="3" source="test data" type="INFO">
+        <paragraph>
+            No role entry for "custom" in module "docutils.parsers.rst.languages.en".
+            Trying "custom" as canonical role name.
+    <system_message level="3" line="3" source="test data" type="ERROR">
+        <paragraph>
+            Unknown interpreted text role "custom".
+        <literal_block xml:space="preserve">
+            .. default-role:: custom
+"""],
+["""\
+.. role:: custom
+.. default-role:: custom
+
+This text uses the `default role`.
+
+.. default-role::
+
+Returned the `default role` to its standard default.
+""",
+"""\
+<document source="test data">
+    <paragraph>
+        This text uses the \n\
+        <inline classes="custom">
+            default role
+        .
+    <paragraph>
+        Returned the \n\
+        <title_reference>
+            default role
+         to its standard default.
+"""],
+]
+
+
+if __name__ == '__main__':
+    import unittest
+    unittest.main(defaultTest='suite')