From b894621d5f4fe62b2dc8e6e369061698a218b233 Mon Sep 17 00:00:00 2001
From: milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 6 Jan 2012 11:11:51 +0000
Subject: [PATCH] Link documentation on how to create inline raw roles.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@7307 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 17 +++++++++++++++--
 docs/ref/rst/roles.txt      |  2 +-
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index d1fcf37bb..0f042bd1d 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -537,7 +537,7 @@ for Unicode symbols, for example::
 
     α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)
 
-For inline math, use the `math role`_.
+For inline math, use the `"math" role`_.
 
 Support for math may be limited by the output format. If a writer does
 not support math typesetting, the content is inserted verbatim.
@@ -546,7 +546,7 @@ configuration setting (or the corresponding ``--math-output`` command
 line option).
 
 .. _Short Math Guide: ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf
-.. _math role: roles.html#math
+.. _"math" role: roles.html#math
 .. _math_output: ../../user/config.html#math-output
 
 Rubric
@@ -1515,6 +1515,9 @@ example::
     .. raw:: html
        :file: inclusion.html
 
+Inline equivalents of the "raw" directive can be defined via
+`custom interpreted text roles`_ derived from the `"raw" role`_.
+
 The following options are recognized:
 
 ``file`` : string (newlines removed)
@@ -1527,6 +1530,8 @@ The following options are recognized:
     The text encoding of the external raw data (file or URL).
     Defaults to the document's encoding (if specified).
 
+.. _"raw" role: roles.html#raw
+
 
 .. _classes:
 
@@ -1691,6 +1696,14 @@ The parsed result is as follows::
         <emphasis classes="custom">
             text
 
+A special case is the `"raw" role`_: derived roles enable
+inline `raw data pass-through`_, e.g.::
+
+   .. role:: raw-role(raw)
+      :format: html latex
+
+   :raw-role:`raw text`
+
 If no base role is explicitly specified, a generic custom role is
 automatically used.  Subsequent interpreted text will produce an
 "inline" element with a `"classes"`_ attribute, as in the first example
diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt
index f6d8b4dad..e59605a56 100644
--- a/docs/ref/rst/roles.txt
+++ b/docs/ref/rst/roles.txt
@@ -351,7 +351,7 @@ passed untouched to the Writer.  It is the inline equivalent of the
 `"raw" directive`_; see its documentation for details on the
 semantics.
 
-.. _"raw" directive: directives.html#raw
+.. _"raw" directive: directives.html#raw-directive
 
 The "raw" role cannot be used directly.  The `"role" directive`_ must
 first be used to build custom roles based on the "raw" role.  One or
-- 
2.11.4.GIT