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

[ben van 't ende]

Heyla Martin,

It looks like you put quite some energy into this again. My major question would
if we will get rid of the wide tables that mess up the layout of the manual and
the html pages? There was a suggestion at one point to convert tables into
definition lists, which sounded very attractive to me.

Can you say something about that?

gRTz ben




On 21/08/12 10:00, Martin Bless wrote:
> 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
>
> 
-- 
TYPO3 Community Manager