mirror of https://github.com/svaarala/duktape.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
149 lines
2.6 KiB
149 lines
2.6 KiB
============================
|
|
reStructuredText conventions
|
|
============================
|
|
|
|
File extension
|
|
==============
|
|
|
|
Although ``.txt`` extension is probably technically correct for RST files,
|
|
use ``.rst`` for internal documentation for better compatibility with editors,
|
|
GitHub, etc.
|
|
|
|
Section markers
|
|
===============
|
|
|
|
Book level:
|
|
|
|
#. Over- and underlined hash marks (``#``) for book title
|
|
|
|
#. Over- and underlines stars (``*``) for book sub-title
|
|
|
|
File level:
|
|
|
|
#. Over- and underlined equals signs (``=``) once at top of file (file topic)
|
|
|
|
#. Underlined equals signs (``=``)
|
|
|
|
#. Underlined minus signs (``-``)
|
|
|
|
#. Underlined colons (``:``)
|
|
|
|
#. Underlined periods (``.``)
|
|
|
|
The book level notation is reserved for future use. It allows the
|
|
internal documentation to be easily built into a single HTML/PDF
|
|
file for ease of browsing.
|
|
|
|
Page breaks
|
|
===========
|
|
|
|
See http://comments.gmane.org/gmane.text.docutils.user/6473.
|
|
|
|
You can use::
|
|
|
|
.. raw:: LaTeX
|
|
|
|
\newpage
|
|
|
|
Lists
|
|
=====
|
|
|
|
Numbering
|
|
---------
|
|
|
|
List numbering styles can be mixed, e.g.::
|
|
|
|
1. Foo
|
|
|
|
a. Bar
|
|
|
|
1. Quux
|
|
|
|
However, e.g. GitHub will renumber the bullets and may also change the
|
|
numbering style. This will make references to list elements confusing;
|
|
e.g. if you refer to Quux as element 1.a.1 above, the reference is quite
|
|
confusing if Quux was renumbered to 1.1.1 or 1.a.iii. Even so, such
|
|
references are sometimes necessary so they can be used.
|
|
Start at zero indent
|
|
|
|
Bullets
|
|
-------
|
|
|
|
Recommended bullet styles by level::
|
|
|
|
* Foo
|
|
|
|
+ Bar
|
|
|
|
- Quux
|
|
|
|
Start at zero indent
|
|
--------------------
|
|
|
|
Start lists at zero indent, e.g.::
|
|
|
|
* Foo
|
|
|
|
* Bar
|
|
|
|
If you don't, GitHub will render the list as a quoted block.
|
|
|
|
Empty lines
|
|
-----------
|
|
|
|
Use empty lines between elements and sub-elements for readability and to
|
|
minimize formatting issues::
|
|
|
|
1. Foo
|
|
|
|
a. sub-foo
|
|
|
|
+ sub-sub-foo
|
|
|
|
b. sub-bar
|
|
|
|
2. Bar
|
|
|
|
3. Quux
|
|
|
|
Nested lists and GitHub
|
|
-----------------------
|
|
|
|
While ``rst2pdf`` and friends are somewhat lenient with respect to nested
|
|
lists, GitHub RST formatter is a bit more picky. To work with the GitHub
|
|
formatter, make sure that a nested list's bullet mark is intended to the
|
|
level of the previous level's body, e.g.::
|
|
|
|
1. Foo
|
|
|
|
a. sub-foo
|
|
|
|
b. sub-bar
|
|
|
|
2. Bar
|
|
|
|
The following is **incorrect** and GitHub will render the nested list as
|
|
a quoted block::
|
|
|
|
1. Foo
|
|
|
|
a. sub-foo
|
|
|
|
b. sub-bar
|
|
|
|
2. Bar
|
|
|
|
Note that the required level depends on the length of the parent bullet.
|
|
This matters for numbered lists::
|
|
|
|
9. Foo
|
|
|
|
a. sub-foo
|
|
|
|
b. sub-bar
|
|
|
|
10. Bar
|
|
|
|
a. sub-foo (with one more indent than above)
|
|
|
|
b. sub-bar
|
|
|