[TYPO3-doc] New: "t3-field-list-table" directive now availble for ReST markup in our Sphinx documentation projects

[Martin Bless]

Hello friends,

I'm happy to announce the the "t3-field-list-table" directive is now available for us in
the Sphinx documentation projects.

Short history
=============

Creating tables is sort of a problem in any editor. But it's important to as as there are
often very long tables in the existing documentation. That's why I spent some effort last
year to offer a better solution. And that was implementing a "field-list-table" directive
for the Docutils (= basic ReST toolset). It goes back to ideas of 2005 in the Docutils
community and was presented in [1]. To see some examples of how it is used see [2].

Unfortuneately in the meantime there was no manpower to get that into the Docutils core.
That simply meant that we could not use it because it was not commonly available without
"hacking".

In the meantime the "t3sphinx" Python package has been created and provides a way to
easily spread all TYPO3 specific amendmends and extensions to everybody. Yesterday I spent
a whole day to find - in the end - the three lines of code that give us the - new name! -
"t3-field-list-table" directive back in our Sphinx projects.

This means: We can start using it!

Installation
============

Do this:

- Read [4] and 
- follow the "Installation" chapter.
- See [3] and
- add the TYPO3 specific codeblock manually to your "conf.py"

That's it.


How does it work?
=================

In ReST markup you write a doubly nested list. An unordered list is the outer one and
constructs table rows. It's a "bullet-list" [5] in Docutil's terms:

- row1
- row2
- row3
- ...

Each row is a "field-list" [6] which means that each item is a key-value pair and creates
a cell. The key is the column name. The value is the cell content. So a complete example
may look like this:

.. t3-field-list-table::
 :header-rows: 1

 - :Property,20:    Property
   :Data type,20:   Data type
   :Description,50: Description
   :Default,10:     Default

 - :Property:    allWrap
   :Data type:   wrap / stdWrap
   :Description: Wraps the whole item

 - :Property:    wrapItemAndSub

   :Data type:   wrap / stdWrap

   :Description:
         Wraps the whole item and
         any submenu concatenated to it.

The table has three rows. The first on is a header row. And there a four named columns
with desired widths 20%, 20%, 50%, 10%. The unnumbered list markup and the field-list
markup follows the normal standard ReST syntax rules. Without our directive you would have
to use the "grid table" markup of the Docutils to produce the same result:

+----------------+---------------+---------------------------------+-------------+
| Property       | Data type     | Description                     |  Default    |
+================+===============+=================================+=============+
| allWrap        | wrap /stdWrap | Wraps the whole item            |             |
+----------------+---------------+---------------------------------+-------------+
| wrapItemAndSub | wrap /stdWrap | Wraps the whole item and        |             |
|                |               | any submenu concatenated to it. |             |
+----------------+---------------+---------------------------------+-------------+


Implications ...
================

Just a few notes, mainly for the TYPO3 documentation team:

1. We had given up the idea of keeping tables because we couldn't handle then in markup.

2. Now we can handle them! (using "t3-field-list-table")

3. We had found a "definition list markup" as workaround to write existings tables in
OpenOffice documents in ReST markup. And that's how all our official documents are now in
the Git repositories.

4. It would be much nicer to have (2.) instead of (3.) for the existing tables!

5. If we want to have (4.) - yes, we do! - this means we either have to do it manually or
generate everything once again and push it once again to Git.

6. To achieve (5.) manually is not as much work as it sounds because the ReST markup is
very similar. So that's what I would propose.

7. IN GENERAL there was an agreement when we asked in the documentation list that we in
general should not use those big tables as there are, for example, in the
TyposcriptReferenceManual. Where appropriate stuff should be rewritten using other
"normal" text constructs. But this can only be done manually. That's another argument, I'd
say, to keep the current docs as they are (see 3.) and to improve manually as in (6.).

8. And, KEEP IN MIND, the kind of voting mentioned in (7.) should not mean at all that you
should avoid tables in general. Yes, please do use tables wherever you find them
appropriate. If you have table like data you should write that as table.

I'm hoping you can follow my numbers =:-) I feel a bit like a lawyer ... But don't worry,
I'm not at all.



[1] http://lists.typo3.org/pipermail/typo3-project-documentation/2011-November/003517.html

[2]
http://mbless.de/4us/typo3-oo2rest/06-The-%5Bfield-list-table%5D-directive/1-demo.rst.html

[3] http://lists.typo3.org/pipermail/typo3-project-documentation/2012-August/004048.html

[4]
http://git.typo3.org/Documentation/RestTools.git?a=blob_plain;f=ExtendingSphinxForTYPO3/README.txt;hb=HEAD

[5] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-lists

[6] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#field-lists