Changes between Version 2 and Version 3 of WikiRestructuredText


Ignore:
Timestamp:
2011-04-02T22:36:15Z (15 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WikiRestructuredText

    v2 v3  
    55From the reStucturedText webpage:
    66 "''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. ''"
     7
     8If you want a file from your Subversion repository be displayed as reStructuredText in Trac's source browser, set `text/x-rst` as value for the Subversion property `svn:mime-type`. See [trac:source:/trunk/INSTALL this example].
    79
    810=== Requirements ===
    … …  
    1012If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website].
    1113
     14Install docutils using `easy_install docutils`. Do not use the package manager of your OS (e.g. `apt-get install python-docutils`), because Trac will not find docutils then.
     15
    1216=== More information on RST ===
    1317
    … …  
    2226=== TracLinks in reStructuredText ===
    2327
    24  * Trac provides a custom RST reference-directive 'trac' to allow TracLinks from within RST text.
    25 
    26  Example:
    27  {{{
    28  {{{
    29  #!rst
    30  This is a reference to |a ticket|
    31 
    32  .. |a ticket| trac:: #42
    33  }}}
    34  }}}
    35 
    36  For a complete example of all uses of the ''trac''-directive, please see WikiRestructuredTextLinks.
    37 
    38 
    39  * Trac allows an even easier way of creating TracLinks in RST, using the custom '':trac:'' link naming scheme.
    40 
    41  Example:
    42  {{{
    43  {{{
    44  #!rst
    45  This is a reference to ticket `#12`:trac:
    46 
    47  To learn how to use Trac, see `TracGuide`:trac:
    48  }}}
    49  }}}
     28 * Trac provides a custom RST directive `trac::` to allow TracLinks from within RST text.
     29   ||= Wiki Markup ||= Display ||
     30   {{{#!td
     31     {{{
     32     {{{
     33     #!rst
     34     This is a reference to |a ticket|
     35
     36     .. |a ticket| trac:: #42
     37     }}}
     38     }}}
     39   }}}
     40   {{{#!td
     41     {{{
     42     #!rst
     43     This is a reference to |a ticket|
     44
     45     .. |a ticket| trac:: #42
     46     }}}
     47   }}}
     48
     49 * Trac allows an even easier way of creating TracLinks in RST, using the custom `:trac:` role.
     50   ||= Wiki Markup ||= Display ||
     51   {{{#!td
     52     {{{
     53     {{{
     54     #!rst
     55     This is a reference to ticket `#12`:trac:
     56
     57     To learn how to use Trac, see `TracGuide`:trac:
     58     }}}
     59     }}}
     60   }}}
     61   {{{#!td
     62     {{{
     63     #!rst
     64     This is a reference to ticket `#12`:trac:
     65
     66     To learn how to use Trac, see `TracGuide`:trac:
     67     }}}
     68   }}}
     69
     70 For a complete example of all uses of the `:trac:` role, please see WikiRestructuredTextLinks.
     71
    5072
    5173=== Syntax highlighting in reStructuredText ===
    5274
    53 There is a directive for doing TracSyntaxColoring in ReST as well. The directive is called
     75There is a directive for doing TracSyntaxColoring in RST as well. The directive is called
    5476code-block
    5577
    56 Example
    57 
    58 {{{
    59 {{{
    60 #!rst
    61 
    62 .. code-block:: python
    63 
    64  class Test:
    65 
    66     def TestFunction(self):
    67         pass
    68 
    69 }}}
    70 }}}
    71 
    72 Will result in the below.
    73 
    74 {{{
    75 #!rst
    76 
    77 .. code-block:: python
    78 
    79  class Test:
    80 
    81     def TestFunction(self):
    82         pass
    83 
    84 }}}
     78||= Wiki Markup ||= Display ||
     79{{{#!td
     80  {{{
     81  {{{
     82  #!rst
     83
     84  .. code-block:: python
     85
     86     class Test:
     87
     88         def TestFunction(self):
     89             pass
     90 
     91  }}}
     92  }}}
     93}}}
     94{{{#!td
     95  {{{
     96  #!rst
     97
     98  .. code-block:: python
     99
     100     class Test:
     101
     102         def TestFunction(self):
     103             pass
     104
     105  }}}
     106}}}
     107Note the need to indent the code at least one character after the `.. code-block` directive.
    85108
    86109=== Wiki Macros in reStructuredText ===
    87110
    88 For doing [WikiMacros Wiki Macros] in ReST you use the same directive as for syntax highlighting i.e
    89 code-block. To work you must use a version of trac that has #801 applied.
    90 
    91 === Wiki Macro Example ===
    92 
    93 {{{
    94 {{{
    95 #!rst
    96 
    97 .. code-block:: RecentChanges
    98 
    99    Trac,3
    100 
    101 }}}
    102 }}}
    103 
    104 Will result in the below:
    105 
    106      [[RecentChanges(Trac,3)]]
    107 
    108 Or a more concise Wiki Macro like syntax is also available:
    109 
    110 {{{
    111 {{{
    112 #!rst
    113 
    114 :code-block:`RecentChanges:Trac,3`
    115 }}}
    116 }}}
    117 
    118 === Bigger ReST Example ===
     111For doing [WikiMacros Wiki Macros] in RST you use the same directive as for syntax highlighting i.e code-block.
     112
     113||= Wiki Markup ||= Display ||
     114{{{#!td
     115  {{{
     116  {{{
     117  #!rst
     118
     119  .. code-block:: RecentChanges
     120
     121     Trac,3
     122
     123  }}}
     124  }}}
     125}}}
     126{{{#!td
     127  {{{
     128  #!rst
     129
     130  .. code-block:: RecentChanges
     131
     132     Trac,3
     133
     134  }}}
     135}}}
     136
     137Or a more concise Wiki Macro like syntax is also available, using the `:code-block:` role:
     138
     139||= Wiki Markup ||= Display ||
     140{{{#!td
     141  {{{
     142  {{{
     143  #!rst
     144
     145  :code-block:`RecentChanges:Trac,3`
     146  }}}
     147  }}}
     148}}}
     149{{{#!td
     150  {{{
     151  #!rst
     152
     153  :code-block:`RecentChanges:Trac,3`
     154  }}}
     155}}}
     156
     157=== Bigger RST Example ===
    119158The example below should be mostly self-explanatory:
     159
     160||= Wiki Markup ||= Display ||
     161{{{#!td
    120162{{{
    121163#!html
    … …  
    147189}}}</pre>
    148190}}}
    149 
    150 
    151 Results in:
     191}}}
     192{{{#!td
    152193{{{
    153194#!rst
    … …  
    176217.. _webpage: http://docutils.sourceforge.net/rst.html
    177218}}}
    178 
     219}}}
    179220
    180221----