Commits

Roger Haase  committed a9c1d79

copy updated ReST docs from serialize/items.moin to docs/user/rest.rst

  • Participants
  • Parent commits fb44a83

Comments (0)

Files changed (1)

File docs/user/rest.rst

 The first style encountered will be an outermost title (like HTML H1), the second style will be a subtitle, 
 the third will be a subsubtitle, and so on.
 
+The underline below the title must at least be equal to the length of the title itself.  Failure to comply results in messages on the server log. Skipping a heading (e.g. putting an H5 heading directly under an H3) results in a rendering error and an error message will be displayed instead of the expected page.
+
+If any markup appears before the first heading on a page, then the first heading will be an H2 and all subsequent headings will be demoted by 1 level.
+
 **Markup**: ::
 
+ =======
  Level 1
  =======
 
- **Intentionally not rendered as level 1 so it doesn't interfere with Sphinx's indexing**
-
  Level 2
  =======
 
+ # levels 1 and 2 are not shown below, see top of page and this section heading.
+
  Level 3
  -------
 
  Level 6
  +++++++
 
+
 **Result**:
 
-Level 1
-=======
-
-**Intentionally not rendered as level 1 so it doesn't interfere with Sphinx's indexing**
-
-Level 2
-=======
 
 Level 3
 -------
 Level 6
 +++++++
 
-**Notes** The underline below the title must at least be equal to the length of the title itself.
+
+Table of Contents
+=================
+
+**Markup**: ::
+
+    .. contents::
+
+**Result**:
+
+.. contents::
+
+The table of contents may appear above or floated to the right side due to CSS styling.
+
 
 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``                   |
-+-------------------------------------+---------------------------------------+
++----------------------------------------------+---------------------------------------+
+| Markup                                       | Result                                |
++==============================================+=======================================+
+| ``**Bold Text**``                            | **Bold text**                         |
++----------------------------------------------+---------------------------------------+
+| ``*Italic*``                                 | *Italic*                              |
++----------------------------------------------+---------------------------------------+
+| ````Inline Literals````                      | ``Inline Literals``                   |
++----------------------------------------------+---------------------------------------+
+| ````***nested markup is not supported***```` | ***nested markup is not supported***  |
++----------------------------------------------+---------------------------------------+
 
 Hyperlinks
 ==========
 
 **Markup**: ::
 
- .. image:: example.png
+ .. image:: png
    :height: 100
    :width: 200
    :scale: 50%
 
 **Result**:
 
- .. image:: example.png
+ .. image:: png
  
 Blockquotes and Indentations
 ============================
  - A block quote may end with an attribution: a text block beginning with "--", "---", 
    or a true em-dash, flush left within the block quote.
  - **RSTTODO** the attribution does not work in moin2.
+ - **RSTTODO** indented text should not be displayed the same as term-definition, needs CSS fix
+
+   - term-definition: <dl><dt>term 1</dt><dd><p>Definition 1.</p>
+   - indented text: <dl><dd><dl><dt>indented text</dt><dd><p>text indented for the 2nd level</p>
 
 Lists
 =====
 
  1. item 1
  
-    1. item 1.1
-    #. item 1.2
+    (A) item 1.1
+    (#) item 1.2
+
+        i) item 1.2.1
+        #) item 1.2.2
    
  #. item 2
 
 
  1. item 1
  
-    1. item 1.1
-    #. item 1.2
+    (A) item 1.1
+    (#) item 1.2
+
+        i) item 1.2.1
+        #) item 1.2.2
    
  #. item 2
    
    (e.g. Roman numerals, Arabic numerals, etc.), initial number (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 <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#enumerated-lists>`_.
  - One or more blank lines are required before and after reStructuredText lists.
+ - **RSTTODO**: Formatting types (1) and 1) do not render correctly in moin2.
 
 Definition Lists
 ================
 
+Definition lists are formed by an unindented one line term followed by an indented definition.
+
 **Markup**: ::
 
  term 1
 
 **Result**:
 
- term 1
-  Definition 1.
+term 1
+ Definition 1.
 
- term 2 : classifier
-  Definition 2.
+term 2 : classifier
+ Definition 2.
 
- term 3 : classifier one : classifier two
-  Definition 3.
+term 3 : classifier one : classifier two
+ Definition 3.
+
+Field Lists
+===========
+
+Field lists are part of an extension syntax for directives usually intended for further processing.
+
+**Markup**: ::
+
+    :Date: 2001-08-16
+    :Version: 1
+    :Authors: Joe Doe
+
+**Result**:
+
+:Date: 2001-08-16
+:Version: 1
+:Authors: Joe Doe
+
+**Notes**:
+ - **RSTTODO**: This could use some CSS changes to enhance the format.
+
+Option lists
+============
+
+Option lists are intended to document Unix or DOS command line options. 
+
+**Markup**: ::
+
+    -a      command definition
+    --a     another command definition
+    /S      dos command definition
+
+**Result**:
+
+-a      command definition
+--a     another command definition
+/S      dos command definition
+
+**Notes**:
+ - **RSTTODO**: The above is rendered in a <dl><dd><p> sequence, but there is a lack of CSS to format it.
+
+
+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.
+
+**Markup**: ::
+
+    *hot*
+
+    333. is a float, 333 is an integer.
+
+    \*hot\*
+
+    333\. is a float, 333 is an integer.
+
+**Result**:
+
+*hot*
+
+333. is a float, 333 is an integer.
+
+\*hot\*
+
+333\. is a float, 333 is an integer.
+
   
 Tables
 ======
 Admonitions are used as a caution/notification block.
 
 **Markup**: ::
- 
+
+ .. caution:: Caution!
+ .. danger:: Danger! 
+ .. error:: Error!
+
  .. note:: This is a paragraph
+ .. admonition:: By the way
  
 **Result**:
 
+ .. caution:: Caution!
+ .. danger:: Danger! 
+ .. error:: Error!
+
  .. note:: This is a paragraph
+ .. admonition:: By the way
+
+**Notes**:
+ - **RSTTODO**: Admonitions are not working. Generates: <div class="None"> and <p style="">
 
 Comments
 ========
 
 **Markup**: ::
 
- Paragraph with a space between succeeding two colons ::
+ Paragraph with a space between preceding two colons ::
 
   Literal block
  
 **Result**:
 
- Paragraph with a space between succeeding two colons ::
+ Paragraph with a space between preceding two colons ::
 
   Literal block
   
 **Markup**: ::
 
- Paragraph with no space between succeeding two colons::
+ Paragraph with no space between text and two colons::
 
   Literal block
  
 **Result**:
 
- Paragraph with no space between succeeding  two colons::
+ Paragraph with no space between text and two colons::
 
   Literal block