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

[Martin Bless]

Heyla heyla heyla (which song was it?) Ben,

>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?

Sure. I even tried in that paragraph 7.:

>> 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.).

But I agree that it was more lawyer's diction and hard to understand. Natural language
goes like this:

It's cool that we now CAN use tables much easier. When you write documentation use the
most natural way of writing (headlines, text, lists, definitions, indentation, codeblocks,
...). Use tables where appropriate. Real table data can best be expressed by tables:

===== ========
Name   gender
===== ========
Peter  male
Paul   male
Mary   female
===== ========

Do not create those big large tables any more like we had in for example the Tsref.

But what do we do with those big tables we still have? For example:
http://preview.docs.typo3.org/TYPO3/Extensions/powermail/1.6.9/#constants-table

which is directly taken from the OpenOffice document. Current state is: We want to get rid
of them. We can transform them automatically to that "definition list" structure. But we
don't have a nice "frontend layout" for that. The definition list structure is by far not
as understandable as the table. We chose the definition list structure (a) in the hope to
find a nice JS/CSS trick for it, which we haven't yet and (b) because the ReST can best be
edited manually. Or even easily editited back to the now possible "t3-field-list-table"
format.

I know about the big pressure we have to get a good rendering done on typo3.org. If we
don't present tables as tables there people will complain and not understand what's being
shown there.

I think it need human intelligence and an editor to rewrite stuff that had been in tables
before to create the new and modern form.

Hhm, it's late, I'm tired, do you get what I mean?

cu!

Martin

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de