[TYPO3-doc] [reST migration] Getting rid of tables for displaying references

[François Suter]

Hi all,

While brainstorming about the migration to reST, one particular point 
came up.

Until now we have been using tables to present lists of properties, with 
their name, type, description, etc., each in one column. This makes for 
a very compact layout, but not very readable since each column is rather 
narrow (and adding columns would make each even narrower). Long 
descriptions and code samples often end up as long strips of text.

It would seem like a good idea to replace such tables with text 
sections, just like chapters. To have an idea how this could be 
structured, look at the "solr" extension documentation, which does it 
this way: http://forge.typo3.org/projects/extension-solr/wiki/Tx_solr

This would have other advantages, beyond improved readability:

- it would enable us to add information like "Since" and "Removed", 
which we didn't really know where to put until now (adding columns would 
have made them narrower)
- code examples could be longer
- it's actually easier to migrate to reST with such a structure, as we 
wouldn't need the "field-list-table" directive which Martin implemented 
for this project, but which is probably isn't going to make into the 
docutils core soon.

Personally I think this would really be an improvement, even if it means 
having a less compact documentation.

What's your opinion?

Cheers

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch