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

[ben van 't ende]

Heyla,

Thanks for the human readable explanation. It is totally clear and  would love
to see this stuff in production. Now even I can join in writing documantation.

gRTz ben



On 23/08/12 00:05, Martin Bless wrote:
> 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
> 

-- 
TYPO3 Community Manager