Lists

ICG does not add/extend any of the three principal list mechanisms provided by Docutils (bullet, enumerated, definition) but below are a few usage details peculiar to ICG docs.

ICG Usages

Bullet or Enumerated Lists

For bullet/enumerated lists, please observe these two conventions:

• do not indent list items from the preceding indentation level
• though valid, please do not use the asterisk character (*) for bullet lists

This is what it looks like when you indent the list item in markup.

1. Now there is too much indentation.

.. this is a correctly formatted bullet list, with a comment preceding

For bullet/enumerated lists, please observe these two conventions:

+ do not indent list items from the preceding indentation level
+ though valid, please do not use the asterisk character (*) for bullet lists

This is what it looks like when you indent the list item in markup.

 1. Now there is too much indentation.

Horizontal offset of bullet lists is built into the rendering style for lists, so indenting it in the markup increases the indention needlessly.

The asterisk character is used in reST for multiple purposes. Also, using it on lists will confuse syntax highlighters. It is better to just avoid its use on lists (and for section title underlining, or as a footnote marker, by the way!). Use any of these instead: + - • ‣ ⁃ (copy/paste right from here will work). If you need more than five bullet characters, something is deeply wrong.

Tip

Bullet items will follow line spacing: without an extra carriage return between items in a list, the list will be “single spaced” in output (see example above). There are no hard rules about whether to use single or double spacing on lists, however. In general, simple lists are probably better when they are more compact (single spaced list items). Lists of “big ideas” and such merit double spacing between items.