Re: [Docutils-users] restructured text and two columns?

[David G. <go...@py...>]

On 1/14/08, Robert Nagle <ro...@en...> wrote:
> Hi, I'm using restructured text to document a python-based SW tool.
>
> I would like to create a page with two columns for an index/Table of
> Contents page.

Do you require two columns in the input, or only in the output?
Doing multiple columns in output is a lot easier than in the input.

> I would think creating a table would adequately simulate the effect of
> having two columns.  However, the simple tables that RST supports seem to
> require using the hyphen (and therefore making the table lines visible).

You can use simple tables, like this:

================================  =============================
Each line here starts a new row.  But here, text may wrap
                                  across lines.

                                  And you can have multiple
                                  paragraphs (still first row).

This is a new row.                Second row.
================================  =============================

You may be able to get around the column-one limitation with a
directive (e.g. ".. contents::" in column one, row one, and nothing
else).  You don't need to use rows of hyphens.

There are also grid tables, which don't have the column-one limitation:

+-----------------------+------------------------+
| This is the content   | The second column can  |
| of the first column,  | also wrap.  Each       |
| and it can wrap as    | rectangle is an        |
| you like.             | independent block.     |
|                       |                        |
| You can have multiple | The disadvantage of    |
| paragraphs etc. in    | grid tables is that    |
| each cell.            | they're hard to edit.  |
|                       | If you're using Emacs, |
|                       | Table mode helps a     |
|                       | lot.                   |
+-----------------------+------------------------+

Another option is list-tables:

.. list-table::

   * - The content of this bullet list item is the content of row one,
       column one.

       You can have arbitrary body-level content here.

     - This is column two of row one.

       If you only want two columns, with one (perhaps long) row, this
       is all you need.

   * - This is another row.

       Each row needs the same number of columns (nested list), even
       if a cell is empty, like the next one is.

     -

Table borders and cell separator lines can be suppressed with styles
(for  to all table types).  Use the "class" directive.

> Is there a way in restructured text to achieve this effect?

The examples above may do it for you.  If not, provide more details.

If you want columns with automatic text flowing, reST won't do it for
you.  You'll have to use stylesheets with your back-end processor.

-- 
David Goodger <http://python.net/~goodger>