Skip to content

Commit 7a3af3e

Browse files
gmildegmilde
committed
Synchronize rST parser documentation files.
A comment in the rST Markup help page says: > This document is duplicated within Moin2 as `/docs/user/rest.rst` and > `contrib/sample/rst.data`. Please update both. Merge recent updates.
1 parent 882168c commit 7a3af3e

File tree

2 files changed

+94
-71
lines changed

2 files changed

+94
-71
lines changed

‎docs/user/rest.rst‎

Lines changed: 74 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -92,60 +92,81 @@ Text formatting
9292

9393
The following is a table of inline markup that can be used to format text in Moin.
9494

95-
+----------------------------------------+------------------------------------+
96-
|Markup |Result |
97-
+========================================+====================================+
98-
|``**Bold Text**`` |**Bold text** |
99-
+----------------------------------------+------------------------------------+
100-
|``*Italic*`` |*Italic* |
101-
+----------------------------------------+------------------------------------+
102-
|````Inline Literals```` |``Inline Literals`` |
103-
+----------------------------------------+------------------------------------+
104-
|``***nested markup is not supported***``|***nested markup is not supported***|
105-
+----------------------------------------+------------------------------------+
95+
======================================== ====================================
96+
Markup Result
97+
======================================== ====================================
98+
``**Bold Text**`` **Bold text**
99+
100+
``*Italic*`` *Italic*
101+
102+
````Inline Literals```` ``Inline Literals``
103+
104+
``***nested markup is not supported***`` ***nested markup is not supported***
105+
======================================== ====================================
106+
106107

107108
Hyperlinks
108109
==========
109110

110111
External Links
111112
--------------
112113

113-
+-----------------------------------------------------------------+-------------------------------------------------------------+
114-
|Markup |Result |
115-
+=================================================================+=============================================================+
116-
|``https://www.python.org/`` |https://www.python.org/ |
117-
+-----------------------------------------------------------------+-------------------------------------------------------------+
118-
|``External hyperlinks, like `Python <https://www.python.org/>`_``|External hyperlinks, like `Python <https://www.python.org/>`_|
119-
+----------------------------------------------------------------+--------------------------------------------------------------+
120-
|``External hyperlinks, like Moin_.`` |External hyperlinks, like Moin_. |
121-
| | |
122-
|``.. _Moin: http://moinmo.in/`` |.. _Moin: http://moinmo.in/ |
123-
+-----------------------------------------------------------------+-------------------------------------------------------------+
114+
================================================================ =====================================================
115+
Markup Result
116+
================================================================ =====================================================
117+
``http://www.python.org/`` http://www.python.org/
118+
119+
``External hyperlinks, like `Python <http://www.python.org/>`_`` External hyperlinks, like
120+
`Python <http://www.python.org/>`_
121+
122+
``External hyperlinks, like Moin_.`` External hyperlinks, like Moin_.
123+
124+
``.. _Moin: http://moinmo.in/`` .. _Moin: http://moinmo.in/
125+
================================================================ =====================================================
124126

125127
Internal Links
126128
--------------
127129

130+
The examples below use the "help-en" and "help-common" namespaces to separate these help pages from the main wiki content.
131+
Some target pages may be missing from the default namespace.
132+
133+
Within the rst syntax:
134+
135+
* a link like ``http:Home`` links to an item in the default namespace
136+
* a link like ``http:/subitem`` links to a subitem of the current item
137+
* a link that begins with a namespace like ``http:users/Home`` links to the Home item in the target namespace
138+
* a link like ``http:../sibling`` links to a sibling of the current item
139+
128140
.. _myanchor:
129141

130-
+----------------------------------------------------------------+------------------------------------------------------------+
131-
|Markup |Result |
132-
+================================================================+============================================================+
133-
|``http:Home`` link to a page in this wiki |http:Home link to a page in this wiki |
134-
+----------------------------------------------------------------+------------------------------------------------------------+
135-
|```Home <http:Home>`_`` link to a page in this wiki |`Home <http:Home>`_ link to a page in this wiki |
136-
+----------------------------------------------------------------+------------------------------------------------------------+
137-
|``Headings_`` link to heading anchor on this page |Headings_ link to heading anchor on this page |
138-
+----------------------------------------------------------------+------------------------------------------------------------+
139-
|```Internal Links`_`` link to heading with embedded blanks |`Internal Links`_ link to heading with embedded blanks |
140-
+----------------------------------------------------------------+------------------------------------------------------------+
141-
|``.. _myanchor:`` create anchor, real anchor is above this table|create anchor, real anchor is above this table |
142-
+----------------------------------------------------------------+------------------------------------------------------------+
143-
|``myanchor_`` link to above anchor |myanchor_ link to above anchor |
144-
+----------------------------------------------------------------+------------------------------------------------------------+
142+
============================ ============================ ===========================================================
143+
Markup Result Comment
144+
============================ ============================ ===========================================================
145+
``http:Home`` http:Home link to an item in the default namespace of this wiki
146+
147+
```Home2 <http:Home>`_`` `Home2 <http:Home>`_ fancy link to an item in the default namespace of this wiki
148+
149+
``http:/subitem`` http:/subitem link to a subitem of the current item
150+
151+
```sub <http:/subitem>`_`` `sub <http:/subitem>`_ fancy link to a subitem of the current item
152+
153+
``http:users/Home`` http:users/Home link to an item in a different namespace of this wiki
154+
155+
``http:../moin`` http:../moin link to a sibling of this item
156+
157+
``Headings_`` Headings_ link to Headings anchor on this item
158+
159+
```Internal Links`_`` `Internal Links`_ link to a heading with embedded blanks
160+
161+
``.. _myanchor:`` create anchor, real anchor is above this table
162+
163+
``myanchor_`` myanchor_ link to above anchor
164+
============================ ============================ ===========================================================
145165

146166
**Notes:**
147167
- If this page was created by Sphinx, none of the above internal link examples work correctly.
148-
- The ".. _myanchor:" directive must begin in column one.
168+
- The block level "target" ``.. _myanchor:`` sets an anchor for the following element.
169+
Inline targets set the anchor on the text content which is also used as label.
149170
- Section titles (or headings) automatically generate hyperlink targets (the title
150171
text is used as the hyperlink name).
151172

@@ -161,11 +182,11 @@ several images declared successively without any positioning will display in a h
161182

162183
Before text.
163184

164-
.. image:: png
165-
:height: 100
185+
.. image:: help-common/logo.svg
186+
:height: 200
166187
:width: 200
167-
:scale: 50
168-
:alt: alternate text png
188+
:scale: 100
189+
:alt: alternate text logo.svg
169190
:align: center
170191

171192
After text.
@@ -174,18 +195,18 @@ several images declared successively without any positioning will display in a h
174195

175196
Before text.
176197

177-
.. image:: png
178-
:height: 100
198+
.. image:: help-common/logo.svg
199+
:height: 200
179200
:width: 200
180-
:scale: 50
181-
:alt: alternate text png
201+
:scale: 100
202+
:alt: alternate text logo.svg
182203
:align: center
183204

184205
After text.
185206

186207
**Notes:**
187-
- The Sphinx parser does not have an image named "png" so the alternate text
188-
will be displayed.
208+
- The Sphinx parser does not have an image named "logo.svg" so the alternate text
209+
will be displayed above.
189210

190211
Figures
191212
=======
@@ -198,11 +219,11 @@ will display in a column.
198219

199220
Before text.
200221

201-
.. figure:: png
222+
.. figure:: help-common/logo.png
202223
:height: 100
203224
:width: 200
204225
:scale: 50
205-
:alt: alternate text png
226+
:alt: alternate text logo.png
206227

207228
Moin Logo
208229

@@ -213,13 +234,14 @@ will display in a column.
213234

214235
**Result**:
215236

237+
216238
Before text.
217239

218-
.. figure:: png
240+
.. figure:: help-common/logo.png
219241
:height: 100
220242
:width: 200
221243
:scale: 50
222-
:alt: alternate text png
244+
:alt: alternate text logo.png
223245

224246
Moin Logo
225247

‎src/moin/help/help-en/rst.data‎

Lines changed: 20 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,21 @@
11
===============================
2-
ReST (ReStructured Text) Markup
2+
reST (reStructuredText) Markup
33
===============================
44

55
..
66
This document is duplicated within Moin2 as `/docs/user/rest.rst` and
77
`contrib/sample/rst.data`. Please update both.
88

9-
Depending upon your source, this document may have been created by
10-
the Moin2 ReST parser (Docutils) or the Sphinx ReST parser. These parsers
11-
have slight differences in the rendering of ReST markup, some of those differences
9+
Depending on your source, this document may have been created by
10+
the Moin2 reST parser (Docutils) or the Sphinx reST parser. These parsers
11+
have slight differences in the rendering of reST markup. Some of those differences
1212
are noted below.
1313

14-
The purpose of this document is to define the features of the Moin2 ReST (Docutils)
15-
parser. The Sphinx extensions to ReST markup that are not supported
14+
The purpose of this document is to define the features of the Moin2 reST (Docutils)
15+
parser. The Sphinx extensions to reST markup that are not supported
1616
by the Docutils parser are not included here.
1717

18-
See the the Docutils Restructured Text documentation for more information.
18+
See the Docutils reStructuredText documentation for more information.
1919

2020
Headings
2121
========
@@ -166,7 +166,8 @@ Markup Result Comment
166166

167167
**Notes:**
168168
- If this page was created by Sphinx, none of the above internal link examples work correctly.
169-
- The ".. _myanchor:" directive must begin in column one.
169+
- The block level "target" ``.. _myanchor:`` sets an anchor for the following element.
170+
Inline targets set the anchor on the text content which is also used as label.
170171
- Section titles (or headings) automatically generate hyperlink targets (the title
171172
text is used as the hyperlink name).
172173

@@ -361,7 +362,7 @@ Ordered Lists
361362
(for lists which do not start at "1") and formatting type
362363
(e.g. ``1.`` or ``(1)`` or ``1)``). More information on
363364
enumerated lists can be found in the `reStructuredText documentation
364-
<http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#enumerated-lists>`_.
365+
<https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#enumerated-lists>`_.
365366
- One or more blank lines are required before and after reStructuredText lists.
366367
- The Moin2 parser requires a blank line between items when changing indentation levels.
367368
- Formatting types (A) and i) are rendered as A. and A. by Sphinx and as A. and i. by Moin2.
@@ -413,7 +414,7 @@ Field lists are part of an extension syntax for directives usually intended for
413414
Option lists
414415
============
415416

416-
Option lists are intended to document Unix or DOS command line options.
417+
Option lists are intended to document Unix or DOS command-line options.
417418

418419
**Markup**::
419420

@@ -457,7 +458,7 @@ Backslash Escapes
457458
=================
458459

459460
Sometimes there is a need to use special characters as literal characters,
460-
but ReST's syntax gets in the way. Use the backslash character as an escape.
461+
but reST's syntax gets in the way. Use the backslash character as an escape.
461462

462463
**Markup**::
463464

@@ -480,8 +481,8 @@ but ReST's syntax gets in the way. Use the backslash character as an escape.
480481
333\. is a float, 333 is an integer.
481482

482483
**Notes**:
483-
- The Moin2 ReST parser changes the 333. to a 1. and inserts an error message into the document.
484-
- The Sphinx ReST parser begins an ordered list with 333. The visual effect is a dedented line.
484+
- The Moin2 reST parser changes the 333. to a 1. and inserts an error message into the document.
485+
- The Sphinx reST parser begins an ordered list with 333. The visual effect is a dedented line.
485486

486487
Tables
487488
======
@@ -553,8 +554,8 @@ Complex tables can have any number of rows or columns. They are made by ``|``, `
553554
| C |
554555
+--------------------------------+
555556

556-
One difference between the Sphinx and Moin ReST parsers is demonstrated below.
557-
With the Spinx parser, grid table column widths can be expanded by adding spaces.
557+
One difference between the Sphinx and Moin reST parsers is demonstrated below.
558+
With the Sphinx parser, grid table column widths can be expanded by adding spaces.
558559

559560
**Markup**::
560561

@@ -569,9 +570,9 @@ With the Spinx parser, grid table column widths can be expanded by adding spaces
569570
+---------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
570571

571572
**Notes:**
572-
- The Moin2 ReST parser does not add the <colgroup><col width="9%"><col width="91%">
573+
- The Moin2 reST parser does not add the <colgroup><col width="9%"><col width="91%">
573574
HTML markup added by the Sphinx parser (the width attribute generates an HTML
574-
validation error), nor does it use Javascript to adjust the width of tables.
575+
validation error), nor does it use JavaScript to adjust the width of tables.
575576
- Under Moin2, tables and table cells will be of minimal width
576577
(unless there is CSS styling to set tables larger).
577578

@@ -582,7 +583,7 @@ Admonitions are used to draw the reader's attention to an important paragraph.
582583
There are nine admonition types: attention, caution, danger, error, hint,
583584
important, note, tip, and warning.
584585

585-
The ReST parser uses "error" admonitions to highlight some ReST syntax errors.
586+
The reST parser uses "error" admonitions to highlight some reST syntax errors.
586587

587588
**Markup**::
588589

@@ -632,7 +633,7 @@ Comments link within item views.
632633
Literal Blocks
633634
==============
634635

635-
Literal blocks are used to show text as-it-is. i.e no markup processing is done within a literal block.
636+
Literal blocks are used to show text as is; i.e., no markup processing is done within a literal block.
636637
A minimum (1) indentation is required for the text block to be recognized as a literal block.
637638

638639
**Markup**::

0 commit comments

Comments
 (0)