[TYPO3-doc] Restoring the official manual example

[Martin Bless]

François,

>Fine with me. I improved the wording ;-)

Great. I like it. See result of patchset #3:
http://preview.docs.typo3.org/TYPO3/OfficialManualExample/Chapter1/Index.html


>BTW I saw you moved some recurring info to a general include file, 
>that's good.

Yes, I think so. FLOW3 docs had _Includes.txt for this I think. But
please let's have Includes.txt.


>But what's the content actually?

.. role::   underline

This one is needed. You can then write :underline:`This is an example
of underlined text.` In HTML this is achieved by adding a
class="underline" and having .underline: {text-decoration:underline}
in CSS. The role 'underline' is needed as there is no ReST markup for
underlining. So I translated any underlining I found in the OpenOffice
documents to :underline:`...` textroles. I propose to have that
definition in every document we have. Maybe you want to invent a
usecase in the OfficialManual that makes sense?


Once I knew how to create textroles on the fly I wanted to demonstrate
that possibility and thought of 'typoscript' in first place. And
because its a long word we can define textrole 'ts' inheriting from
'typoscript'. And because of the :class: option in the ".. role::"
directive that defines the 'ts' textrole it works like this:

You can write: """To link to your homepage with id write
:ts:`10.typolink.parameter = 1`.

.. role::   typoscript(code)

.. role::   ts(typoscript)
   :class:  typoscript

This marks the text as being TypoScript and adds class="typoscript" to
HTML.


And while I was going I thought it might be a good idea to do the same
for PHP.

.. role::   php(code)


Once I had proposed these definitions I never touched them again to
avoid premature discussions. Alright, now the time has come for
discussions.

The only textrole of the above that has really been used is
'underline'. We should keep that as an "official" one. We could remove
the others. Although on the other hand I think it would be good to
express that 'typoscript' and 'ts' are reserved "official" textroles.

The rest in Includes.txt is comment. Note:

.. Two dots in the beginning start a comment
   that may continue in the next
   lines.

Two dots plus space '.. ' in the beginning plus "name" plus no space
plus two colons '::' are a directive:

.. directive:: argument
   :option1: value
   :option2: value

   Now the directive body...

PITFALL - I'll tell you bit it will bite you anyway: Options und
directive body have to start in the same column.

Good:

.. directive:: argument
 :option1: value
 :option2: value

 Now the directive body...


Bad:

Good:

.. directive:: argument
   :option1: value
   :option2: value

 Now the directive body...


>A further question about images. What about captions?

Yes, that's cool. Up to now I had never gotten to the point where I
had to think about this. Indeed, for our illustrations that belong to
the documentation we should be using .. figure:: instead of ..
image::. You can still decide if you make some images like the TYPO3
logo, if it occurs, just an .. image::.

You should only have to replace 'image::' by 'figure::' in our
Images.txt file(s). And that's it.

One more cool thing about figures is that they create crossreference
targets right away and show up with the caption as default link text.

>And how does that fit with our included files? Does the caption have to 
>go into the included file, along with the "image" or "figure" construct?

Well, the caption belongs to the .. figure:: directive. And if we have
it in the included file the caption has to go there. You don't have to
use the replacement technique with "|img-1|" of course. The you would
just place the whole directive into your manuscript where it belongs:


- list item 1

- list item 2: Watch this situation:

  .. figure:: ../Images/screenshot-1.png
     :alt: ALT-text

     This is the caption of the figure (a simple paragraph).

     The legend consists of all elements after the caption.  In this
     case, the legend consists of this paragraph and the following
     table:

     +-----------------------+-----------------------+
     | Symbol                | Meaning               |
     +=======================+=======================+
     | .. image:: tent.png   | Campground            |
     +-----------------------+-----------------------+
     | .. image:: waves.png  | Lake                  |
     +-----------------------+-----------------------+
     | .. image:: peak.png   | Mountain              |
     +-----------------------+-----------------------+

- list item 3


Have a nice week! Cool that we can really start working on the
manuscripts!

Martin

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de