FrontPage 

Fuego wiki

Login or create account

Markup Mapping in split format

{{TableOfContents}}
This page describes the mapping from tbwiki markup language to reStructuredText for the conversion of documentation to Sphynx and readthedocs. (see Issue_0046)
This page describes the mapping from tbwiki markup language to reStructuredText
for the conversion of documentation to Sphynx and readthedocs.  (see [[Issue_0046]])

references [edit section]

http://bird.org/tbwiki/TBWikiDocumentation * ReStructuredText: * RST cheat-sheet: https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html * Reference: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html * Quickref: https://docutils.sourceforge.io/docs/user/rst/quickref.html
= references =
 * TBWIKI:
   * http://bird.org/tbwiki/TBWikiDocumentation
 * ReStructuredText:
   * RST cheat-sheet: https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
   * Reference: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
   * Quickref: https://docutils.sourceforge.io/docs/user/rst/quickref.html

mapping [edit section]

= mapping =
== headers ==
{{{
item | tbwiki | reStructuredText ____________________|_____________________|____________________ | | | | ########## Page Title | | Title | | ########## ____________________|_____________________|____________________ | | ========= 1st level heading | = Heading 1 = | Heading 1 | | ========= ____________________|_____________________|____________________ | | 2nd level heading | == heading 2 == | Heading 2 | | ========= ____________________|_____________________|____________________ | | 3rd level heading | === Heading 3 === | Heading 3 | | --------- ____________________|_____________________|____________________ | | 4th level heading | ==== Heading 4 ==== | Heading 4 | | ~~~~~~~~~ ____________________|_____________________|____________________ | |
 item               |   tbwiki            |  reStructuredText
____________________|_____________________|____________________
                    |                     |
                    |                     | ##########
Page Title          |                     |  Title
                    |                     | ##########
____________________|_____________________|____________________
                    |                     |  =========
1st level heading   | = Heading 1 =       |  Heading 1
                    |                     |  =========
____________________|_____________________|____________________
                    |                     |
2nd level heading   | == heading 2 ==     |  Heading 2
                    |                     |  =========
____________________|_____________________|____________________
                    |                     |
3rd level heading   | === Heading 3 ===   |  Heading 3
                    |                     |  ---------
____________________|_____________________|____________________
                    |                     |
4th level heading   | ==== Heading 4 ==== |  Heading 4
                    |                     |  ~~~~~~~~~
____________________|_____________________|____________________
                    |                     |
}}}
}}}
In rst, Heading order must be consistent, and you can't skip headings. For example, you can't do H1 followed by H3. You must be consistent with the heading underline styles. Sphinx autodetects the level associated with the headings styles, so if you skip a style or use it differently it will cause errors.
In rst, Heading order must be consistent, and you can't skip headings.
For example, you can't do H1 followed by H3.  You must be consistent
with the heading underline styles.  Sphinx autodetects the level associated
with the headings styles, so if you skip a style or use it differently
it will cause errors.

inline markup [edit section]

== inline markup ==
{{{
item | tbwiki | reStructuredText _________________|___________________|____________________ | | bold | '''bold''' | **bold** | | italic | ''italic'' | *italic* | | external link | http://foo | http://foo | | heading anchor | (automatic) | .. _name: | | (automatic with sphinx.ext.autosectionlabel configured) | | | | explicit anchor | Page Name | :doc:`page_name` | | | | | | bullet | * item | * item | (first level must | (first level must follow an empty line) | be indented) | | | dir or filename | filename | filename | | command | 'command' | command |(no markup, but | | convention was | | single quotes) | }}}
item             |   tbwiki          |  reStructuredText
_________________|___________________|____________________
                 |                   |
bold             |  '''bold'''       |   **bold**
                 |                   |
italic           |  ''italic''       |   *italic*
                 |                   |
external link    |  http://foo       |   http://foo
                 |                   |
heading anchor   | (automatic)       |  .. _name:
                 |                   | (automatic with sphinx.ext.autosectionlabel configured)
                 |                   |
                 |                   |
explicit anchor  | {{HTML(<a name="#<name></a>)}} | .._name:
                 |                   |
                 |                   |
                 |                   | 
page link        |  [[Page Name]]    |  :doc:`page_name`
                 |                   |   
                 |                   | 
                 |                   |
bullet           |   * item          | * item
                 | (first level must | (first level must follow an empty line)
                 |  be indented)     |
                 |                   |
dir or filename  | ``filename``      | ``filename``
                 |                   |
command          | 'command'         | ``command``
                 |(no markup, but    |
                 | convention was    |
                 | single quotes)    |
}}}

other items (definition lists, comments) [edit section]

== other items (definition lists, comments) ==
item             |   tbwiki           |  reStructuredText
_________________|____________________|____________________
                 |                    |
definition       | ; term: definition | term
                 |                    |   definition description
                 |                    |
                 |                    |   use same indent to continue
_________________|____________________|____________________
                 |                    |
                 |                    |
comment          | {{{# comment here  | .. comment here
                 | }}}                |
                 |                    |
                 |                    |
{{{
item             |   tbwiki           |  reStructuredText
_________________|____________________|____________________
                 |                    |
definition       | ; term: definition | term
                 |                    |   definition description
                 |                    |
                 |                    |   use same indent to continue
_________________|____________________|____________________
                 |                    |
                 |                    |
comment          | {{{# comment here  | .. comment here
                 | }}}                |
                 |                    |
                 |                    |
}}}
}}}

blocks and quoted [edit section]

== blocks and quoted ==

{{{
item | tbwiki | reStructuredText _____________|________________________________|____________________ | | block | {{{ | previous paragraph | indented | indented | content | content | }}} | previous indentation level _____________|________________________________|____________________ | | | | .. note:: content in colored | {{{#!YellowBox | note block block | content | .. tip:: content in | }}} | note block (also warning:, error: important: caution:) | | | | last part of preceding paragraph :: | | | | stuff in block _____________|________________________________|____________________ | | labeled | | offset block | (not available) | .. note:: content in note block _____________|________________________________|____________________ | | }}}
item         |   tbwiki                       |  reStructuredText
_____________|________________________________|____________________
             |                                |
block        | {{{                            | previous paragraph
             |    indented                    |    indented
             |      content                   |      content
             | }}}                            | previous indentation level
_____________|________________________________|____________________
             |                                |
             |                                | .. note:: content in 
colored      | {{{#!YellowBox                 |    note block
block        |     content                    | .. tip:: content in
             | }}}                            |    note block (also warning:, error: important: caution:)
             |                                |
             |                                |  last part of preceding paragraph ::
             |                                |
             |                                |     stuff in block
_____________|________________________________|____________________
             |                                |
labeled      |                                |
offset block |  (not available)               | .. note:: content in note block
_____________|________________________________|____________________
             |                                |
}}}

links [edit section]

== links ==
note labels and anchors are case-insensitive in rst.
By convention, explicit declarations of labels are lower case.
By convention, explicit declarations of labels are lower case.
http://example.com/Example
item         |   tbwiki                       |  reStructuredText
_____________|________________________________|____________________
             |                                |
URL          |             | http://example.com/
_____________|________________________________|____________________
             |                                |
URL with     |  | `Example http://example.com/`_
cover text   |                                | 
_____________|________________________________|____________________
             |                                |
internal     | [[#Section Name]]              | `section_name`_
_____________|________________________________|____________________
             |                                |
page         | [[Page Name]]                  | :doc:`Page Name`
             |                                |  (depends on whether first
             |                                |   section heading matches
             |                                |   page name)
             |                                |
             |                                | :ref:`Page Name <page_nm>` 
             |                                |  (when a separate anchor has
             |                                |   been created for a page,)
             |                                |
_____________|________________________________|____________________
             |                                |
page with    | [[Page Name|Cover text]]       | :doc:`Cover Text <page name>`
cover text   |                                |
_____________|________________________________|____________________
             |                                |
define       |{{HTML(<a name="new_lbl"></a>)}}| .. _new_label:
anchor       |                                |
_____________|________________________________|____________________
             |                                | 
define       | (not available)                | `Example`_
URL separate |                                |     ...
from cover   |                                |
text         |                                | .. _Example: http://example.com/
             |                                |
_____________|________________________________|____________________
             |                                | 
}}}
{{{
item         |   tbwiki                       |  reStructuredText
_____________|________________________________|____________________
             |                                |
URL          | http://example.com/            | http://example.com/
_____________|________________________________|____________________
             |                                |
URL with     | [[http://example.com|Example]] | `Example http://example.com/`_
cover text   |                                | 
_____________|________________________________|____________________
             |                                |
internal     | [[#Section Name]]              | `section_name`_
_____________|________________________________|____________________
             |                                |
page         | [[Page Name]]                  | :doc:`Page Name`
             |                                |  (depends on whether first
             |                                |   section heading matches
             |                                |   page name)
             |                                |
             |                                | :ref:`Page Name <page_nm>` 
             |                                |  (when a separate anchor has
             |                                |   been created for a page,)
             |                                |
_____________|________________________________|____________________
             |                                |
page with    | [[Page Name|Cover text]]       | :doc:`Cover Text <page name>`
cover text   |                                |
_____________|________________________________|____________________
             |                                |
define       |{{HTML(<a name="new_lbl"></a>)}}| .. _new_label:
anchor       |                                |
_____________|________________________________|____________________
             |                                | 
define       | (not available)                | `Example`_
URL separate |                                |     ...
from cover   |                                |
text         |                                | .. _Example: http://example.com/
             |                                |
_____________|________________________________|____________________
             |                                | 
}}}
See https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref for recommendations on using :ref: It's still a bit unclear to me how to force it to a specific cover text. It appears that it uses a section name following the anchor definition as the cover text, unless overridden. The purpose of this appears to be to let the :ref: handle section renames, without the user having to go to all references and fix them up.
See https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref for recommendations
on using :ref:  It's still a bit unclear to me how to force it to a specific
cover text.  It appears that it uses a section name following the anchor
definition as the cover text, unless overridden.  The purpose of this
appears to be to let the :ref: handle section renames, without the user
having to go to all references and fix them up.

Macros and directives [edit section]

= Macros and directives =
item         |   tbwiki                       |  reStructuredText
_____________|________________________________|____________________
             |                                |
include      | {{Include(page-or-ref)}}       | .. include: included-file.txt
_____________|________________________________|____________________
             |                                |
}}}
{{{
item         |   tbwiki                       |  reStructuredText
_____________|________________________________|____________________
             |                                |
include      | {{Include(page-or-ref)}}       | .. include: included-file.txt
_____________|________________________________|____________________
             |                                |
}}}
TBWiki engine 1.8.3 by Tim Bird