Edgewall Software

Changes between Version 31 and Version 32 of WikiRestructuredText


Ignore:
Timestamp:
Sep 13, 2016, 12:29:17 AM (3 years ago)
Author:
Ryan J Ollos
Comment:

Add note on why examples may not be rendered. Remove incorrect installation requirement. Move #!rst directives inline with the opening braces of the WikiProcessor block.

Legend:

Unmodified
Added
Removed
Modified
  • WikiRestructuredText

    v31 v32  
    1010 "reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. reStructuredText is designed for extensibility for specific application domains."
    1111
    12 If you want a file from your Subversion repository to be displayed as reStructuredText in the Trac source browser, set `text/x-rst` as the value for the Subversion property `svn:mime-type`. See [trac:source:/trunk/INSTALL this example].
     12If you want a file from your Subversion repository to be displayed as reStructuredText in the Trac source browser, set `text/x-rst` as the value for the Subversion property `svn:mime-type`, or add the extension `rst` to the filename. See [trac:source:/trunk/INSTALL.rst this example].
     13
     14The examples will only be rendered as reStructuredText if docutils is installed. If Pygments is installed but docutils is not installed, the examples will be syntax-highlighted rather than rendered as reStructuredText.
    1315
    1416=== Requirements
    1517
    16 To activate RST support in Trac, install the python docutils package: `easy_install docutils`. If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website].
    17 
    18 Do not use the package manager of your OS, eg `apt-get install python-docutils`, because Trac will not find docutils then.
     18To activate RST support in Trac, install the python docutils package with the command `easy_install docutils`, or through your operating system package manager. If not already available on your operating system, you can download it from [https://pypi.python.org/pypi/docutils PyPI].
    1919
    2020=== More information on RST
    2121
    22  * reStructuredText Website -- http://docutils.sourceforge.net/rst.html
    23  * RST Quick Reference -- http://docutils.sourceforge.net/docs/rst/quickref.html
     22 * [http://docutils.sourceforge.net/rst.html reStructuredText Website]
     23 * [http://docutils.sourceforge.net/docs/rst/quickref.html RST Quick Reference]
    2424
    2525== Using RST in Trac
     
    3333   {{{#!td
    3434     {{{
     35     {{{#!rst
     36     This is a reference to |a ticket|
     37
     38     .. |a ticket| trac:: #42
     39     }}}
     40     }}}
     41   }}}
     42   {{{#!td
     43     {{{#!rst
     44     This is a reference to |a ticket|
     45
     46     .. |a ticket| trac:: #42
     47     }}}
     48   }}}
     49
     50 * You can also use the custom `:trac:` role to create TracLinks in RST.
     51   ||= Wiki Markup ||= Display ||
     52   {{{#!td
    3553     {{{
    36      #!rst
    37      This is a reference to |a ticket|
    38 
    39      .. |a ticket| trac:: #42
    40      }}}
    41      }}}
    42    }}}
    43    {{{#!td
    44      {{{
    45      #!rst
    46      This is a reference to |a ticket|
    47 
    48      .. |a ticket| trac:: #42
    49      }}}
    50    }}}
    51 
    52  * Trac allows an even easier way of creating TracLinks in RST, using the custom `:trac:` role.
    53    ||= Wiki Markup ||= Display ||
    54    {{{#!td
    55      {{{
    56      {{{
    57      #!rst
     54     {{{#!rst
    5855     This is a reference to ticket `#12`:trac:
    5956
     
    6360   }}}
    6461   {{{#!td
    65      {{{
    66      #!rst
     62     {{{#!rst
    6763     This is a reference to ticket `#12`:trac:
    6864
     
    7167   }}}
    7268
    73  For a complete example of all uses of the `:trac:` role, please see WikiRestructuredTextLinks.
     69 For a complete example of all uses of the `:trac:` role, see WikiRestructuredTextLinks.
    7470
    7571=== Syntax highlighting in reStructuredText
     
    8076{{{#!td
    8177  {{{
    82   {{{
    83   #!rst
     78  {{{#!rst
    8479
    8580  .. code-block:: python
     
    9489}}}
    9590{{{#!td
    96   {{{
    97   #!rst
     91  {{{#!rst
    9892
    9993  .. code-block:: python
     
    110104=== Wiki Macros in reStructuredText
    111105
    112 To enable [WikiMacros Wiki Macros] in RST, you use the same directive as for syntax highlighting, ie code-block:
     106To enable [WikiMacros Wiki Macros] in RST, you use the same `code-block` directive as for syntax highlighting:
     107
     108||= Wiki Markup ||= Display ||
     109{{{#!td
     110  {{{
     111  {{{#!rst
     112
     113  .. code-block:: RecentChanges
     114
     115     Trac,3
     116
     117  }}}
     118  }}}
     119}}}
     120{{{#!td
     121  {{{#!rst
     122
     123  .. code-block:: RecentChanges
     124
     125     Trac,3
     126
     127  }}}
     128}}}
     129
     130Or use the `:code-block:` role for a more concise Wiki Macro-like syntax:
    113131
    114132||= Wiki Markup ||= Display ||
     
    118136  #!rst
    119137
    120   .. code-block:: RecentChanges
    121 
    122      Trac,3
    123 
    124   }}}
    125   }}}
    126 }}}
    127 {{{#!td
    128   {{{
    129   #!rst
    130 
    131   .. code-block:: RecentChanges
    132 
    133      Trac,3
    134 
    135   }}}
    136 }}}
    137 
    138 Or a more concise Wiki Macro-like syntax is also available, using the `:code-block:` role:
    139 
    140 ||= Wiki Markup ||= Display ||
    141 {{{#!td
    142   {{{
    143   {{{
    144   #!rst
    145 
    146138  :code-block:`RecentChanges:Trac,3`
    147139  }}}
     
    149141}}}
    150142{{{#!td
    151   {{{
    152   #!rst
     143  {{{#!rst
    153144
    154145  :code-block:`RecentChanges:Trac,3`
     
    162153||= Wiki Markup ||= Display ||
    163154{{{#!td
    164 {{{
    165 #!html
    166 <pre class="wiki">{{{
    167 #!rst
     155{{{#!html
     156<pre class="wiki">{{{#!rst
    168157FooBar Header
    169158=============
     
    193182}}}
    194183{{{#!td
    195 {{{
    196 #!rst
     184{{{#!rst
    197185FooBar Header
    198186=============