Here are some punctuation tips to help you format your pages to look more readable.
To implement these formatting features, we use what is called a "directive" to indicate the system needs to handle the following text a little differently.
You may have seen a directive in action on Help pages already, specifically the "table of contents" directive.
To indicate you're using a directive, start the line with two periods and a space, and then the directive a la:
The contents directive is one of the easiest directives to use. By clicking on the plain text link for this page, you can see it's been used in the line just above this one. Here's how to make it work:
.. contents:: (optional label for TOC list) NOTE: if you do not provide a label, the label will simply read "contents"
As you build the page, each item that you underline (using the - key not the _) is automatically included in the table of contents.
The line block directive is very handy when the spacing of a list counts (like with addresses or with poetry). Here's how to make it work:
.. line-block:: Here's my address 123 Main St Los Alamos, NM 87544
Note that the text that you are line blocking must be indented. The above directive looks like this when it's published:
Here's my address123 Main StLos Alamos, NM 87544
Contrast the above with how one would normally have to do a series of lines on top of each other:
Here's my address
123 Main St
Los Alamos, NM 87544
Quite the handy directive, no?
When it comes right down to it, inserting an image in a page is just using the image directive.:
.. image :: (URL for your picture)
See Picture Display How-to for info on more advanced use.
This directive copies the contents of a worksheet to the document you are working in. This is particularly useful if you the same text to be referred to in several places. This is how it is done.:
.. on-include :: worksheet name
Please notice that you use the worksheet name (with any spaces it might have) NOT the URL. This form only works if the worksheet is in the group that you are posting in. If it is in another groups's workspace, you must include the other group in the address.
Please look at sidebar.:
.. on-include :: /community-general/sidebar
This code will look like this:
This directive allows you to put a box with information in the middle of a post. It is particularly useful to emphasize a point. If you are wandering around the help pages you will see this one a lot.:
.. admonition :: Did you know? To return to the page you were just viewing, just click the "back" button on your Web browser.
And this is what it yields:
Did you know?
To return to the page you were just viewing, just click the "back" button on your Web browser.
Again, the text that will appear in the box is indented.
This directive will allow you to enter straight HTML code so that the Colophone doesn't parse it into it's own language. I find this particularly good for doing tables as I am very comfortable doing tables in HTML.:
.. RAW :: HTML <TABLE> <TR><TD>Col 1</TD><TD>Col 2</TD></TR> <TR><TD>Name 1</TD><TD>Phone 1</TD></TR> </TABLE>
Note, yet again, that the HTML code must be indented after EVERY enter, even for a blank line. This little snippet yields:
|Col 1||Col 2|
|Name 1||Phone 1|
Techies Take Note:
We have used reStructuredText (RST) as our markup language. If you're inclined to understand technical documentation, the full listing of RST directives can be found here at reStructuredText