diff --git a/docs/user/rest.rst b/docs/user/rest.rst index fa3882c37..0eab8e659 100644 --- a/docs/user/rest.rst +++ b/docs/user/rest.rst @@ -3,8 +3,9 @@ reST (reStructuredText) Markup =============================== .. - This document is duplicated within Moin2 as `/docs/user/rest.rst` and - `contrib/sample/rst.data`. Please update both. + This document is duplicated within the Moin2 repository as + `docs/user/rest.rst` and `src/moin/help/help-en/rst.data`. + Please update both. Depending on your source, this document may have been created by the Moin2 reST parser (Docutils) or the Sphinx reST parser. These parsers @@ -92,17 +93,18 @@ Text formatting The following is a table of inline markup that can be used to format text in Moin. -+----------------------------------------+------------------------------------+ -|Markup |Result | -+========================================+====================================+ -|``**Bold Text**`` |**Bold text** | -+----------------------------------------+------------------------------------+ -|``*Italic*`` |*Italic* | -+----------------------------------------+------------------------------------+ -|````Inline Literals```` |``Inline Literals`` | -+----------------------------------------+------------------------------------+ -|``***nested markup is not supported***``|***nested markup is not supported***| -+----------------------------------------+------------------------------------+ +======================================== ==================================== +Markup Result +======================================== ==================================== +``**Bold Text**`` **Bold text** + +``*Italic*`` *Italic* + +````Inline Literals```` ``Inline Literals`` + +``***nested markup is not supported***`` ***nested markup is not supported*** +======================================== ==================================== + Hyperlinks ========== @@ -110,42 +112,63 @@ Hyperlinks External Links -------------- -+-----------------------------------------------------------------+-------------------------------------------------------------+ -|Markup |Result | -+=================================================================+=============================================================+ -|``https://www.python.org/`` |https://www.python.org/ | -+-----------------------------------------------------------------+-------------------------------------------------------------+ -|``External hyperlinks, like `Python `_``|External hyperlinks, like `Python `_| -+----------------------------------------------------------------+--------------------------------------------------------------+ -|``External hyperlinks, like Moin_.`` |External hyperlinks, like Moin_. | -| | | -|``.. _Moin: http://moinmo.in/`` |.. _Moin: http://moinmo.in/ | -+-----------------------------------------------------------------+-------------------------------------------------------------+ +================================================================ ===================================================== +Markup Result +================================================================ ===================================================== +``http://www.python.org/`` http://www.python.org/ + +``External hyperlinks, like `Python `_`` External hyperlinks, like + `Python `_ + +``External hyperlinks, like Moin_.`` External hyperlinks, like Moin_. + +``.. _Moin: http://moinmo.in/`` .. _Moin: http://moinmo.in/ +================================================================ ===================================================== Internal Links -------------- +The examples below use the "help-en" and "help-common" namespaces +to separate these help pages from the main wiki content. +Some target pages may be missing from the default namespace. + +Within the rst syntax: + + * a link like ``http:Home`` links to an item in the default namespace + * a link like ``http:/subitem`` links to a subitem of the current item + * a link that begins with a namespace like ``http:users/Home`` links to the Home item in the target namespace + * a link like ``http:../sibling`` links to a sibling of the current item + .. _myanchor: -+----------------------------------------------------------------+------------------------------------------------------------+ -|Markup |Result | -+================================================================+============================================================+ -|``http:Home`` link to a page in this wiki |http:Home link to a page in this wiki | -+----------------------------------------------------------------+------------------------------------------------------------+ -|```Home `_`` link to a page in this wiki |`Home `_ link to a page in this wiki | -+----------------------------------------------------------------+------------------------------------------------------------+ -|``Headings_`` link to heading anchor on this page |Headings_ link to heading anchor on this page | -+----------------------------------------------------------------+------------------------------------------------------------+ -|```Internal Links`_`` link to heading with embedded blanks |`Internal Links`_ link to heading with embedded blanks | -+----------------------------------------------------------------+------------------------------------------------------------+ -|``.. _myanchor:`` create anchor, real anchor is above this table|create anchor, real anchor is above this table | -+----------------------------------------------------------------+------------------------------------------------------------+ -|``myanchor_`` link to above anchor |myanchor_ link to above anchor | -+----------------------------------------------------------------+------------------------------------------------------------+ +============================ ============================ =========================================================== +Markup Result Comment +============================ ============================ =========================================================== + ``http:Home`` http:Home link to an item in the default namespace of this wiki + + ```Home2 `_`` `Home2 `_ fancy link to an item in the default namespace of this wiki + + ``http:/subitem`` http:/subitem link to a subitem of the current item + + ```sub `_`` `sub `_ fancy link to a subitem of the current item + + ``http:users/Home`` http:users/Home link to an item in a different namespace of this wiki + + ``http:../moin`` http:../moin link to a sibling of this item + + ``Headings_`` Headings_ link to Headings anchor on this item + + ```Internal Links`_`` `Internal Links`_ link to a heading with embedded blanks + + ``.. _myanchor:`` create anchor, real anchor is above this table + + ``myanchor_`` myanchor_ link to above anchor +============================ ============================ =========================================================== **Notes:** - If this page was created by Sphinx, none of the above internal link examples work correctly. - - The ".. _myanchor:" directive must begin in column one. + - The block level "target" ``.. _myanchor:`` sets an anchor for the following element. + Inline targets set the anchor on the text content which is also used as label. - Section titles (or headings) automatically generate hyperlink targets (the title text is used as the hyperlink name). @@ -161,11 +184,11 @@ several images declared successively without any positioning will display in a h Before text. - .. image:: png - :height: 100 + .. image:: help-common/logo.svg + :height: 200 :width: 200 - :scale: 50 - :alt: alternate text png + :scale: 100 + :alt: alternate text logo.svg :align: center After text. @@ -174,18 +197,18 @@ several images declared successively without any positioning will display in a h Before text. -.. image:: png - :height: 100 +.. image:: help-common/logo.svg + :height: 200 :width: 200 - :scale: 50 - :alt: alternate text png + :scale: 100 + :alt: alternate text logo.svg :align: center After text. **Notes:** - - The Sphinx parser does not have an image named "png" so the alternate text - will be displayed. + - The Sphinx parser does not have an image named "logo.svg" so the alternate text + will be displayed above. Figures ======= @@ -198,11 +221,11 @@ will display in a column. Before text. - .. figure:: png + .. figure:: help-common/logo.png :height: 100 :width: 200 :scale: 50 - :alt: alternate text png + :alt: alternate text logo.png Moin Logo @@ -213,13 +236,14 @@ will display in a column. **Result**: + Before text. -.. figure:: png +.. figure:: help-common/logo.png :height: 100 :width: 200 :scale: 50 - :alt: alternate text png + :alt: alternate text logo.png Moin Logo diff --git a/src/moin/help/help-en/rst.data b/src/moin/help/help-en/rst.data index cee5fd96e..0eab8e659 100644 --- a/src/moin/help/help-en/rst.data +++ b/src/moin/help/help-en/rst.data @@ -1,21 +1,22 @@ =============================== -ReST (ReStructured Text) Markup +reST (reStructuredText) Markup =============================== .. - This document is duplicated within Moin2 as `/docs/user/rest.rst` and - `contrib/sample/rst.data`. Please update both. + This document is duplicated within the Moin2 repository as + `docs/user/rest.rst` and `src/moin/help/help-en/rst.data`. + Please update both. -Depending upon your source, this document may have been created by -the Moin2 ReST parser (Docutils) or the Sphinx ReST parser. These parsers -have slight differences in the rendering of ReST markup, some of those differences +Depending on your source, this document may have been created by +the Moin2 reST parser (Docutils) or the Sphinx reST parser. These parsers +have slight differences in the rendering of reST markup. Some of those differences are noted below. -The purpose of this document is to define the features of the Moin2 ReST (Docutils) -parser. The Sphinx extensions to ReST markup that are not supported +The purpose of this document is to define the features of the Moin2 reST (Docutils) +parser. The Sphinx extensions to reST markup that are not supported by the Docutils parser are not included here. -See the the Docutils Restructured Text documentation for more information. +See the Docutils reStructuredText documentation for more information. Headings ======== @@ -92,17 +93,18 @@ Text formatting The following is a table of inline markup that can be used to format text in Moin. -+----------------------------------------+------------------------------------+ -|Markup |Result | -+========================================+====================================+ -|``**Bold Text**`` |**Bold text** | -+----------------------------------------+------------------------------------+ -|``*Italic*`` |*Italic* | -+----------------------------------------+------------------------------------+ -|````Inline Literals```` |``Inline Literals`` | -+----------------------------------------+------------------------------------+ -|``***nested markup is not supported***``|***nested markup is not supported***| -+----------------------------------------+------------------------------------+ +======================================== ==================================== +Markup Result +======================================== ==================================== +``**Bold Text**`` **Bold text** + +``*Italic*`` *Italic* + +````Inline Literals```` ``Inline Literals`` + +``***nested markup is not supported***`` ***nested markup is not supported*** +======================================== ==================================== + Hyperlinks ========== @@ -110,22 +112,25 @@ Hyperlinks External Links -------------- -+----------------------------------------------------------------+------------------------------------------------------------+ -|Markup |Result | -+================================================================+============================================================+ -|``http://www.python.org/`` |http://www.python.org/ | -+----------------------------------------------------------------+------------------------------------------------------------+ -|``External hyperlinks, like `Python `_``|External hyperlinks, like `Python `_| -+----------------------------------------------------------------+------------------------------------------------------------+ -|``External hyperlinks, like Moin_.`` |External hyperlinks, like Moin_. | -| | | -|``.. _Moin: http://moinmo.in/`` |.. _Moin: http://moinmo.in/ | -+----------------------------------------------------------------+------------------------------------------------------------+ +================================================================ ===================================================== +Markup Result +================================================================ ===================================================== +``http://www.python.org/`` http://www.python.org/ + +``External hyperlinks, like `Python `_`` External hyperlinks, like + `Python `_ + +``External hyperlinks, like Moin_.`` External hyperlinks, like Moin_. + +``.. _Moin: http://moinmo.in/`` .. _Moin: http://moinmo.in/ +================================================================ ===================================================== Internal Links -------------- -The examples below use the "help-en" and "help-common" namespaces to separate these help pages from the main wiki content. Some target pages may be missing from the default namespace. +The examples below use the "help-en" and "help-common" namespaces +to separate these help pages from the main wiki content. +Some target pages may be missing from the default namespace. Within the rst syntax: @@ -136,33 +141,34 @@ Within the rst syntax: .. _myanchor: -+-----------------------------+-------------------------------------+------------------------------------------------------------+ -|Markup |Result |Comment | -+=============================+=====================================+============================================================+ -| ``http:Home`` |http:Home |link to an item in the default namespace of this wiki | -+-----------------------------+-------------------------------------+------------------------------------------------------------+ -| ```Home2 `_`` |`Home2 `_ |fancy link to an item in the default namespace of this wiki | -+-----------------------------+-------------------------------------+------------------------------------------------------------+ -| ``http:/subitem`` |http:/subitem |link to a subitem of the current item | -+-----------------------------+-------------------------------------+------------------------------------------------------------+ -| ```sub `_`` |`sub `_ |fancy link to a subitem of the current item | -+-----------------------------+-------------------------------------+------------------------------------------------------------+ -| ``http:users/Home`` |http:users/Home |link to an item in a different namespace of this wiki | -+-----------------------------+-------------------------------------+------------------------------------------------------------+ -| ``http:../moin`` |http:../moin |link to a sibling of this item | -+-----------------------------+-------------------------------------+------------------------------------------------------------+ -| ``Headings_`` |Headings_ |link to Headings anchor on this item | -+-----------------------------+-------------------------------------+------------------------------------------------------------+ -| ```Internal Links`_`` |`Internal Links`_ |link to a heading with embedded blanks | -+-----------------------------+-------------------------------------+------------------------------------------------------------+ -| ``.. _myanchor:`` | |create anchor, real anchor is above this table | -+-----------------------------+-------------------------------------+------------------------------------------------------------+ -| ``myanchor_`` |myanchor_ |link to above anchor | -+-----------------------------+-------------------------------------+------------------------------------------------------------+ +============================ ============================ =========================================================== +Markup Result Comment +============================ ============================ =========================================================== + ``http:Home`` http:Home link to an item in the default namespace of this wiki + + ```Home2 `_`` `Home2 `_ fancy link to an item in the default namespace of this wiki + + ``http:/subitem`` http:/subitem link to a subitem of the current item + + ```sub `_`` `sub `_ fancy link to a subitem of the current item + + ``http:users/Home`` http:users/Home link to an item in a different namespace of this wiki + + ``http:../moin`` http:../moin link to a sibling of this item + + ``Headings_`` Headings_ link to Headings anchor on this item + + ```Internal Links`_`` `Internal Links`_ link to a heading with embedded blanks + + ``.. _myanchor:`` create anchor, real anchor is above this table + + ``myanchor_`` myanchor_ link to above anchor +============================ ============================ =========================================================== **Notes:** - If this page was created by Sphinx, none of the above internal link examples work correctly. - - The ".. _myanchor:" directive must begin in column one. + - The block level "target" ``.. _myanchor:`` sets an anchor for the following element. + Inline targets set the anchor on the text content which is also used as label. - Section titles (or headings) automatically generate hyperlink targets (the title text is used as the hyperlink name). @@ -357,7 +363,7 @@ Ordered Lists (for lists which do not start at "1") and formatting type (e.g. ``1.`` or ``(1)`` or ``1)``). More information on enumerated lists can be found in the `reStructuredText documentation - `_. + `_. - One or more blank lines are required before and after reStructuredText lists. - The Moin2 parser requires a blank line between items when changing indentation levels. - Formatting types (A) and i) are rendered as A. and A. by Sphinx and as A. and i. by Moin2. @@ -409,7 +415,7 @@ Field lists are part of an extension syntax for directives usually intended for Option lists ============ -Option lists are intended to document Unix or DOS command line options. +Option lists are intended to document Unix or DOS command-line options. **Markup**:: @@ -453,7 +459,7 @@ Backslash Escapes ================= Sometimes there is a need to use special characters as literal characters, -but ReST's syntax gets in the way. Use the backslash character as an escape. +but reST's syntax gets in the way. Use the backslash character as an escape. **Markup**:: @@ -476,8 +482,8 @@ but ReST's syntax gets in the way. Use the backslash character as an escape. 333\. is a float, 333 is an integer. **Notes**: - - The Moin2 ReST parser changes the 333. to a 1. and inserts an error message into the document. - - The Sphinx ReST parser begins an ordered list with 333. The visual effect is a dedented line. + - The Moin2 reST parser changes the 333. to a 1. and inserts an error message into the document. + - The Sphinx reST parser begins an ordered list with 333. The visual effect is a dedented line. Tables ====== @@ -549,8 +555,8 @@ Complex tables can have any number of rows or columns. They are made by ``|``, ` | C | +--------------------------------+ -One difference between the Sphinx and Moin ReST parsers is demonstrated below. -With the Spinx parser, grid table column widths can be expanded by adding spaces. +One difference between the Sphinx and Moin reST parsers is demonstrated below. +With the Sphinx parser, grid table column widths can be expanded by adding spaces. **Markup**:: @@ -565,9 +571,9 @@ With the Spinx parser, grid table column widths can be expanded by adding spaces +---------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ **Notes:** - - The Moin2 ReST parser does not add the + - The Moin2 reST parser does not add the HTML markup added by the Sphinx parser (the width attribute generates an HTML - validation error), nor does it use Javascript to adjust the width of tables. + validation error), nor does it use JavaScript to adjust the width of tables. - Under Moin2, tables and table cells will be of minimal width (unless there is CSS styling to set tables larger). @@ -578,7 +584,7 @@ Admonitions are used to draw the reader's attention to an important paragraph. There are nine admonition types: attention, caution, danger, error, hint, important, note, tip, and warning. -The ReST parser uses "error" admonitions to highlight some ReST syntax errors. +The reST parser uses "error" admonitions to highlight some reST syntax errors. **Markup**:: @@ -628,7 +634,7 @@ Comments link within item views. Literal Blocks ============== -Literal blocks are used to show text as-it-is. i.e no markup processing is done within a literal block. +Literal blocks are used to show text as is; i.e., no markup processing is done within a literal block. A minimum (1) indentation is required for the text block to be recognized as a literal block. **Markup**:: diff --git a/src/moin/help/help-en/rst.meta b/src/moin/help/help-en/rst.meta index b0ce9ee89..4867612d7 100644 --- a/src/moin/help/help-en/rst.meta +++ b/src/moin/help/help-en/rst.meta @@ -5,9 +5,9 @@ "contenttype": "text/x-rst;charset=utf-8", "dataid": "c7f47fd6eaaa4e518c2bd32d741073f8", "externallinks": [ - "http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#enumerated-lists", "http://moinmo.in/", - "http://www.python.org/" + "http://www.python.org/", + "https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#enumerated-lists" ], "itemid": "412d0e59c79147058ef2e947d1772d5f", "itemlinks": [ @@ -29,8 +29,8 @@ "namespace": "help-en", "rev_number": 1, "revid": "fd40283c31464441a3734ba512b7cfb0", - "sha1": "40abb7437b6bd5234f58644114cef02eaa7a7b83", - "size": 21443, + "sha1": "d71e4e1f1e978714550ab1c0f80033cc3d3e182c", + "size": 19176, "summary": "", "tags": [ "parser",