[TYPO3-doc] DocBook: sample reference file

[Philipp Gampe]

Hi Christian, Francois and all others trying to get a good new concept,

Christian Kartnig wrote:

> I think it would really be a good idea to explicitly write down
> usecases, where the tsref is needed, so that we can pin down all the
> requirements. Maybe we can have a little brainstorming in this list?

I can only speak for myself. If I open TSref I what to know one of the 
following (in that order, more often on top):
1. the exact spelling of an element
2. all "children" of an element
3. the meaning of an element (what exactly does it do and what values does 
it have, required children, etc.)
4. search an element I could use for a given problem

To me Typescript is a tree of elements used to define rendering of the 
website and to configure the output of plugins. (I know this is not 
completely correct, but that is what I usually have in mind.)

For 1: After working for more than two years with TYPO3, I now know most TS 
elements. But sometimes I am unsure how they were spelled exactly. For 
example I late tried to write page.pageType instead of page.typeNum ;) What 
I need to have is an overview over all elements liked to a detail page. The 
page should categorize the elements to make finding easier.
Something like this is for HTML, CSS and more (sorry german link but content 
should be self-explanatory)
http://de.selfhtml.org/navigation/syntax.htm

For 2: Sometimes I have an element and I need to know what subelement it 
has. For Example HMENU has TMENU and TMENU has NO, CUR and ACT. All three 
have expAll, aTagTitle, noblur, etc. I do not care much whether NO, CUR and 
ACT are TMENUITEMs or not. I just need to know that I can use NO "within" 
and TMENU. 
Therefore the reference should give me an overview of what child I can use. 
Of course that could be an link to stdWrap and TMENUITEM stating "all you 
find in those". I know this is a bit tricky, because an element might have 
special attributes (=subelements) and some generic subelements like stdWrap 
Support.
I would solve this by using stdWrap and TMENUITEM as pseudo datatype like it 
is done now for stdWrap (in current TSref).

For 3: I need to know all about a property: datatype(s), children, what it 
does, when was it introduced, when was it deprecated, etc. And once again, I 
do not care about technical details, I just want to know everything I need 
to use that element. And an example would be really helpful.
What I need is the detail view with (almost*) all data available.
* some technical or implementational things might be added to the reference 
too. However I do not see a need to render them for normal users. Developers 
can look into the docbook source and study the remarks and/or the structure 
there.

For 4: If I have a problem I what to solve, but do not know how to do it (or 
how to do it best), I need either a good categorization which pins it down 
to a few elements I can study in deep or I need a guide. I think a guide can 
not be part of the reference and should be an own book (e.g. TS in 45min or 
MTB based on IP).

Drawn from my use-cases we would need the following structure (pseudo-XML):
<element id="xyz"> //I like the id structure you proposed
  <title>TMENU</title>
  <description>
    TMENU is used for creating text menus.
  <description>

  <introduced>4.4.0</introduced>
  <deprecated>4.7.0</deprecated>

  <datatype>integer<datatype> //I know ... just for demonstration
  <datatype>TMENUITEM</datatype>
  <datatype>stdWrap<datatype>

  <data>
    <value>keyword 1</value>
    <desc>use keyword 1 to make it behave like a duck</desc>
  </data>
  <data>
    <value>keyword 2</value>
    <desc>use keyword 2 to turn it into a nice blue bird</desc>
  </data>
  <data>
    <value>1</value> //boolean true
    <desc>Set this to 1 to hide the menu completely.</desc>
  </data>
  <seeother>
    <link />
    <link />
  </seeother>

  <example>
    10 = HMENU
    10.1 = TMENU
    10.1 {
      wrap = <ul>|<ul>
        # this is pointless too
      NO = 1
    }
  </example>

  <remark>
    this will not be rendered... there could also be <api>...</api>
  </remark>
</element>

So looking at the current proposed structure, we almost have all.

We still need to deal with datatype and data ... looking into docbook 
reference, I think we could use the itemized list. If we can use more then 
on list, we could define the first one to contain links to datatype and the 
second to contain a list of values/keywords.

<refentry xml:id="typoscript.datatype.type.int">

  <refnamediv>
    <refname>int</refname>
    <refpurpose>A simple integer number</refpurpose>
  </refnamediv>

  <refsection>

    <itemizedlist> //first datatypes
      <listitem><link to=stdWrap /></listitem>
      <listitem><link to=TMENUITEM /></listitem>
    </itemizedlist>

    <itemizedlist> //second are keywords
      <listitem>
        <formalpara>
          <title>keyword 1</title>
          <para>here comes the text</para>
        </formalpara>
      </listitem>
    </itemizedlist>

    <title>Examples</title>
    <programlisting>
      some code
    </programlisting>

    <remark>this is an API note</remark>
  </refsection>

</refentry>

I do not know whether this makes sense. Also I did not know how the t3editor 
files are structured. I would like of course have only on single reference 
and derive everything from it.

By the way, I would not mind writing a custom XML-DTD if it turns out that 
we can not add everything needed into docbook. Creating a docbook file via 
XSLT should not be a problem if the XML is wellformed and "explicit".


This text turned out to be much longer that I intended ;) 
I hope it tells my ideas and what is needed from my point of view.

Best regards
-- 
Philipp Gampe