[Typo3-doc] ref Table formating discussion

[Jean-Marie Schweizer]

Sylvain Viart wrote:

> Hi,
> 
> Thanks for your answers, but it seems I didn't well explain what I mean. 
> :-)
> 
> I speak about how the data are ordered and presented. And it's time 
> consuming for the reader. I don't see it in the writer way for the 
> moment. I'm speaking about what could be the final document result. We 
> will try to find how it could be produced later. ;-)
> 
> Here is my example taken from RealURL manual:
> http://typo3.org/documentation/document-library/realurl/Configuration-87/#oodoc_part_6590 
> 
> 
> I've identified a peace of config code which hold language URL mapping:
>  1:     'preVars' => array(
>  2:         array(
>  3:             'GETvar' => 'no_cache',
>  4:             'valueMap' => array(
>  5:                 'no_cache' => 1,
>  6:             ),
>  7:             'noMatch' => 'bypass',
>  8:         ),
>  9:         array(                             <<-
> 10:             'GETvar' => 'L',               <<-
> 11:             'valueMap' => array(           <<-
> 12:                 'dk' => '1',               <<-
> 13:                 'danish' => '1',           <<-
> 14:                 'uk' => '2',               <<-
> 15:                 'english' => '2',          <<-
> 16:             ),                             <<-
> 17:             'valueDefault' => 'uk',        <<-
> 18:         ),
> 19:     ),
> 
> 
> Now I'm looking for how it works in the reference manual.
> 
> Here we have a 3 columns table.
> - First we have the properties name (key)
> - its type (which may link to subtype)
> - a description
> 
> I've found a properties which seems control the behavior I'm looking 
> for. :-)
> 
> preVars.GETvar ... and friends
> 
> So I look in the table...
> 
> How it is described in this table formatting ?
> 
> First table «$TYPO3_CONF_VARS['EXTCONF']['realurl']», it's a 
> «->siteCfg», I follow the arrow...
> 
> Second table «->siteCfg», it's a «preVars [0..x]» of type «->partDef», 
> follow the guide...
> 
> Fourth table «->partDef», it's start speaking about how this behavior is 
> mapped.
> 
> And I'm reading a printed version ! (20 pages)
> Which doesn't have the nice CTRL+F «Find in text» feature...
> 
> TSref uses the same kind of reference table linking...
> Example:
> http://typo3.org/documentation/document-library/doc_core_tsref/TMENUITEM/
> Property «before» of type «HTML +stdWrap»...
> 
> How to use it ?
> - Should be a kind of HTML cObject (look for what is an HTML cObject)
> - Which also have stdWrap behavior (look for it)
> 
> In this particular case, it's really bad and time consuming for the 
> reader...
> 
> Is it more clear ?

To me it's less clear now. But I just guess your question relates more 
to programmers than writers or designers, hence all that programming 
jargon.

Since I didn't understand what your problem is, I will answer it the way 
I see the problem from the structure point of view.

Biggest problem with those tables is that the description coloumn  has a 
lot of content now enough width to present that content in a easy to 
read way.

A way to solve that problem:

key | type
<empty> | description

instead of

key | typ3 | descrption

That way you visually keep the key accessible and give the description 
more space (fitting to its conent) and you have more room for subtypes.

Classifying subtypes wouldhelp too by using general terms and typing 
them in bold.

As I said, I might not have gotten your point but it was worth a try.

Jean-Marie