UP | Help `index`_ see also RSTCheatSheet_

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.

.. sidebar:: Each directive has three parts:

 .. line-block::

   1. the directive name
   2. a two-colon separator
   3. the directive block of content

To indicate you're using a directive, start the line with two periods and a space, and then the directive a la:: 

 .. directive_name

.. contents:: here's a list of directives covered on this page:

contents
--------

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.

sidebar
-------

A side bar is very useful to pull out information from the body of the text and into its own right-hand justified box. An example of a sidebar is shown above with the "Each directive has three parts" box. Here's how to make it work::

 .. sidebar:: Title for sidebar box (required)

    Text that will appear in the side bar box. **Note this text
    is indented.** To signify the end of the sidebar box content,
    simply don't indent the next paragraph of content.

 This content will not appear in the sidebar box above.


line-block
----------

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:

 .. line-block::

    Here's my address
    123 Main St
    Los 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?

image
------

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.

on-include
------

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 o-map_.::

 .. on-include ::  /community-general/o-map

This code will look like this:

.. on-include ::  /community-general/o-map

admonition
------

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:

.. admonition :: 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.

RAW
------

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:

.. RAW :: HTML

 <TABLE>
 <TR><TD>Col 1</TD><TD>Col 2</TD></TR>
 <TR><TD>Name 1</TD><TD>Phone 1</TD></TR>
 </TABLE>



----

**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__

__ http://docutils.sourceforge.net/rst.html

.. _edit: /group/help/ws/MoreFormatting/edit
.. _o-map : /group/community-general/ws/o_map/