From 882168c1d4c41233714bf4f7e242a82b0217d163 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=BCnter=20Milde?= Date: Mon, 2 Jun 2025 23:17:05 +0200 Subject: [PATCH 1/3] Update rST parser documentation: preparation Use a simple table for simple examples. Easier to read and edit. No change to the content and the rendered output. --- src/moin/help/help-en/rst.data | 96 ++++++++++++++++++---------------- 1 file changed, 50 insertions(+), 46 deletions(-) diff --git a/src/moin/help/help-en/rst.data b/src/moin/help/help-en/rst.data index cee5fd96e..e7a249f99 100644 --- a/src/moin/help/help-en/rst.data +++ b/src/moin/help/help-en/rst.data @@ -92,17 +92,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 +111,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,29 +140,29 @@ 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. From 7a3af3ee7ff75d3e9dce60a05af390381454b236 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=BCnter=20Milde?= Date: Mon, 2 Jun 2025 23:17:05 +0200 Subject: [PATCH 2/3] 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. --- docs/user/rest.rst | 126 +++++++++++++++++++-------------- src/moin/help/help-en/rst.data | 39 +++++----- 2 files changed, 94 insertions(+), 71 deletions(-) diff --git a/docs/user/rest.rst b/docs/user/rest.rst index fa3882c37..6929f2633 100644 --- a/docs/user/rest.rst +++ b/docs/user/rest.rst @@ -92,17 +92,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 +111,62 @@ 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 +182,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 +195,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 +219,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 +234,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 e7a249f99..841e93ae4 100644 --- a/src/moin/help/help-en/rst.data +++ b/src/moin/help/help-en/rst.data @@ -1,21 +1,21 @@ =============================== -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. -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 ======== @@ -166,7 +166,8 @@ Markup Result Comment **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). @@ -361,7 +362,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. @@ -413,7 +414,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**:: @@ -457,7 +458,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**:: @@ -480,8 +481,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 ====== @@ -553,8 +554,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**:: @@ -569,9 +570,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). @@ -582,7 +583,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**:: @@ -632,7 +633,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**:: From 5195478f2628bbf42d0b8cab60e624d41ead0d64 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=BCnter=20Milde?= Date: Tue, 21 Oct 2025 21:32:15 +0200 Subject: [PATCH 3/3] rST documentation fixup. Fix path of help file in leading comment. Remove trailing whitespace. Wrap long line. Update metadata. --- docs/user/rest.rst | 14 ++++++++------ src/moin/help/help-en/rst.data | 13 +++++++------ src/moin/help/help-en/rst.meta | 8 ++++---- 3 files changed, 19 insertions(+), 16 deletions(-) diff --git a/docs/user/rest.rst b/docs/user/rest.rst index 6929f2633..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 @@ -96,11 +97,11 @@ The following is a table of inline markup that can be used to format text in Moi Markup Result ======================================== ==================================== ``**Bold Text**`` **Bold text** - + ``*Italic*`` *Italic* - + ````Inline Literals```` ``Inline Literals`` - + ``***nested markup is not supported***`` ***nested markup is not supported*** ======================================== ==================================== @@ -127,7 +128,8 @@ Markup Result Internal Links -------------- -The examples below use the "help-en" and "help-common" namespaces to separate these help pages from the main wiki content. +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: diff --git a/src/moin/help/help-en/rst.data b/src/moin/help/help-en/rst.data index 841e93ae4..0eab8e659 100644 --- a/src/moin/help/help-en/rst.data +++ b/src/moin/help/help-en/rst.data @@ -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 @@ -96,11 +97,11 @@ The following is a table of inline markup that can be used to format text in Moi Markup Result ======================================== ==================================== ``**Bold Text**`` **Bold text** - + ``*Italic*`` *Italic* - + ````Inline Literals```` ``Inline Literals`` - + ``***nested markup is not supported***`` ***nested markup is not supported*** ======================================== ==================================== @@ -127,7 +128,7 @@ Markup Result Internal Links -------------- -The examples below use the "help-en" and "help-common" namespaces +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. 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",