DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

EXT: Readable name of your extension

Created:2010-02-18T17:33:18
Changed:2010-03-03T20:03:02
Classification:extensionkey
Description:The keywords help with categorizing and tagging of the manuals. You can combine two or more keywords and add additional keywords yourself. Please use at least one keyword from both lists. If your manual is NOT in english, see next tab "language" ---- forEditors (use this for editors / german "Redakteure") forAdmins (use this for Administrators) forDevelopers (use this for Developers) forBeginners (manuals covering TYPO3 basics) forIntermediates (manuals going into more depth) forAdvanced (covering the most advanced TYPO3 topics) see more: http://wiki.typo3.org/doc_template#tags ----
Keywords:keywords comma-separated
Author:Author Name
Email:your@email.com
Info 4:
Language:en

img-1 img-2 EXT: Readable name of your extension - extensionkey

EXT: Readable name of your extension

Extension Key: extensionkey

Language: en

Keywords: keywords comma-separated

Copyright 2000-2010, Author Name, <your@email.com>

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

- a GNU/GPL CMS/Framework available from www.typo3.org

Table of Contents

EXT: Readable name of your extension 1

`Introduction 3 <#1.1.Introduction|outline>`_

What does it do? 3

Screenshots 3

`Users manual 4 <#1.2.Users%20manual|outline>`_

FAQ 4

`Administration 5 <#1.3.Administration|outline>`_

FAQ 5

`Configuration 6 <#1.4.Configuration|outline>`_

FAQ 6

Reference 6

`Tutorial 7 <#1.5.Tutorial|outline>`_

`Known problems 8 <#1.6.Known%20problems|outline>`_

`To-Do list 9 <#1.7.To-Do%20list|outline>`_

`ChangeLog 10 <#1.8.ChangeLog|outline>`_

Important guidelines 11

`Issues with Open Office documentation for TYPO3 12 <#2.1.Issues%20w ith%20Open%20Office%20documentation%20for%20TYPO3|outline>`_

Inserting images 12

Paragraph styles 12

Linking 13

Meta data and updates 13

HowTo: Update a manual to the new layout 13

HowTo: (alternative) Import the styles from another document 14

`HowTo: Fix the Table Of Contents when it is empty 14 <#2.1.8.HowTo:%2 0Fix%20the%20Table%20Of%20Contents%20when%20it%20is%20empty%20|outline >`_

HowTo: Fix the Table Of Contents when a chapter is missing 14

Help by documentation.openoffice.org 14

Introduction

What does it do?

Overview; What does it do? What problem is solved? Who is interested in this? Brief technical insight. Basically everything people need to know if they should go on with this extension.

Tips for manual-editors
New style: “List”
  • Hit the F11 key to show the styles
  • If you use the current “doc_template” (version 1.2.7 and higher) you already see “List” in “ Applied styles ”/ (german: “Verwendete Vorlagen”)
  • For all who just upgrade d from an older version: See “ List styles ” and double click at “List” to use it, and switch back to “Used styles”
  • Use it: select some lines and double klick the List-style
HowTo: Update the styles in your manual

Use the HowTo at page 13 “HowTo: Update a manual to the new layout”

Checklist: Before you upload an extension
  • No empty line between a header and a paragraph
  • No changes of the headers (font select box “Clear formatting”/ “Formatierung loeschen”)
  • Change special paragraph-styles to standard (with “Clear formatting”)
  • Update the Table of Contents with a right click (when you hover over the TOC-items you see the numbering)

Screenshots

  • img-3 Screenshots are very much welcome for a visual impression.
  • This section will have a link in the EM, so therefore it's very important that it conveys this message.
  • Target group: Mostly Developers and administrators, but should be a non-technical and visual presentation.
  • This section is required and in some cases it basically tells it all.

Users manual

  • Documentation of how to use the extension, how it works, how to apply it if it's a website plugin. A user manual.
  • Language should be non-technical, explaining, using small examples.
  • Examples: For the "News" plugin this would be a manual showing how to create the news-items, explaining the options etc.
  • Target group: Users, Administrators or Developers in that priority. Depends on the extension.

FAQ

Possible subsections: FAQ

Administration

  • Describes how to manage the extension from a superuser point of view. That relates to Page/User TSconfig, permissions, configuration etc. which administrator level users have access to.
  • language should be non/semi-technical, explaining, using small examples.
  • Target group: Administrators

FAQ

Possible subsections: FAQ

Configuration

  • Technical information; Installation, Reference of TypoScript, configuration options on system level, how to extend it, the technical details, how to debug it.
  • language should be technical, assuming developer knowledge of TYPO3. Small examples/visuals are always encouraged.
  • Target group: Developers

FAQ

Possible subsections: FAQ

Subheadlines

You can produce subheadlines in a section using “Heading 4” or “Heading 5” (normally used for “Examples”)

Reference

Possible subsections: Reference (TypoScript)

allWrap /+stdWrap

Property

allWrap /+stdWrap

Data type

wrap

Description

Wraps the whole item

Default

wrapItemAndSub

Property

wrapItemAndSub

Data type

wrap

Description

Wraps the whole item and any submenu concatenated to it.

Default

subst_elementUid

Property

subst_elementUid

Data type

boolean

Description

If set, all appearances of the string '{elementUid}' in the total element html-code (after wrapped in .allWrap} is substituted with the uid number of the menu item.

This is useful if you want to insert an identification code in the HTML in order to manipulate properties with JavaScript.

Default

RO_chBgColor

Property

RO_chBgColor

Data type

string

Description

If property RO is set (see below) then you can set this property to a certain set of parameters which will allow you to change the background color of eg. the tablecell when the mouse rolls over you text-link.

Syntax:

[over-color] | [out-color] | [id-prefix]

Example:

page = PAGE
page.typeNum = 0
page.10 = HMENU
page.10.wrap = <table border=1>|</table>
page.10.1 = TMENU
page.10.1.NO {
  allWrap = <tr><td valign=top id="1tmenu{elementUid}" style="background:#eeeeee;">|</td></tr>
  subst_elementUid = 1
  RO_chBgColor = #cccccc | #eeeeee | 1tmenu
  RO = 1
}

This example will start out with the table cells in #eeeeee and change them to #cccccc (and back) when rolled over. The “1tmenu” string is a unique id for the menu items. You may not need it (unless the same menu items are more than once on a page), but the important thing is that the id of the table cell has the exact same label before the {elementUid} (red marks). The other important thing is that you DO set a default background color for the cell with the style-attribute (blue marking). If you do not, Mozilla browsers will behave a little strange by not capturing the mouseout event the first time it's triggered.

Default

[tsref:(cObject).TEST]

((generated))
Example

Here you would show an example of the stuff from the reference or so:

page = PAGE
page.typeNum = 0
page.10 = TEXT
page.10.value = HELLO WORLD

Tutorial

  • A full point-a-to-b-to-c walk-through of an application of the extension. Include screendumps.
  • Language: As tutorials are...
  • Target group: Whatever fits.

Known problems

  • Use this section for important warnings about bugs, problems or performance issues. This is where you should explain shortcomings of the extension, so people are properly warned. Be honest.
  • Target group: Mostly Developers
  • TYPO3 Forge link to your project
  • Alternativley if you like: User contributions to YOUR manual : (don't use the forge-wiki-page because nobody would find it, the central wiki is wiki.typo3.org)

To-Do list

  • A wish list of things you want to add or fix. This includes smaller problems/bugs which are best described as a todo item.
  • Visions for what the extension could become with more development.
  • TYPO3 Forge link to your project

ChangeLog

0.1.0

Version

0.1.0

Changes

Added / Changed/ Caught error

Important guidelines

Issues with Open Office documentation for TYPO3

There are a few important points to make about writing documentation for TYPO3 in Open Office. Please makes sure to follow these.

Inserting images

When you insert images you can either:

  • img-4 Make a copy/paste from eg. Photoshop, but it's REALLY IMPORTANT that you insert the image into Open Office by the menu “Edit > Paste Special” and then select “Bitmap”. If you don't do it in this way the image cannot be shown (since it will not be stored as a PNG internally in the SXW file)
  • Alternatively you can use the traditional way “ Insert > Graphics > From file ” and insert an image from your harddrive. In particular use this if the image is photographic (JPG) since the internal storage as PNG is not good for photographs.

Generally please use copy/paste only for screendumps with large areas of similar color (good png-compression) and JPG-files for photographic images. Go for small images, 72 dpi, medium quality.

Paragraph styles

  • Use the paragraph style “Text body” for bodytext
  • Use “Heading 1” to “Heading 5” for headers. “Heading 1-3” will be recognized as “sections” on typo3.org. “Heading 4-5” is subheaders, where “Heading 5” is preferrably for “Examples”.
  • For code listings, use the style “Preformatted Text” (found under “HTML Styles”). For codelistings in tables there is a custom style called “Table Contents/PRE”.

This screenshot shows the only paragraph styles allowed in the documents. The ones grayed out are paragraph styles that are used by default for such as the index table or the footer. The others are the ones you are allowed to use.

img-5

Linking

You can make hyperlinks in the documents as absolute URLs. Use menu “Insert > Hyperlink”

Meta data and updates

There are three fields of meta-data you have to fill in. First of all go to “File > Properties...”.

img-6

  • In the “Description” screen you enter the title of the document. Extension manuals are prefixed “EXT: [extension title]”
  • In the “User defined” screen you enter your email address as the first field (named “Email” / ”Info 1”)
  • In the “User defined” screen you enter your full name as the second field (named “Author” / ”Info 2”)

Finally you should also insert the correct extension key in the text below the document title, but this is not a meta-data field, just regular text.

HowTo: Update a manual to the new layout

With these steps you get it very fast

  • Update the extension doc_template (maybe a new one is out)
  • Hit the F11 key to show the styles
  • >> Copy everything from your old manual except the title page and the table of contents <<
  • Delete contents from new manual but leave the title page and the table of contents there
  • Paste your content and check that formatting is correct and images are in place
  • Hint: When the header-styles are still in the old layout then clear and re-assign the new style
  • Update the page properties with your extension key, e-mail-address, name, language, tagging.In the moment the language- and tagging- properties are not in use by the TER, but findable by search.
  • Reload the table of content (right click update index table)
  • Insert your extension key below the document title

Ready.

HowTo: (alternative) Import the styles from another document

  • img-7 (!) In some old OpenOffice versions (e.g. 2.4) there's a bug: after the import you need the HowTo “Fix the TOC”
  • Load your manual, then hit the F11 key to show the styles
  • Klick on the small arrow top-right
  • A select box appears , you klick at “Load Styles” and then “From File”
  • (!) Check all the boxes
  • Navigate to the “doc_template”/doc” folder and switch the file-type to .sxw “OpenOffice.org 1.0 Textdocument”
  • Open the manual.sxw, now you can use the new style!

HowTo: Fix the Table Of Contents when it is empty

Maybe the outline numbering is broken (german: “Kapitelnummerierung”).

  • Go to menu "Tools” > “Outline Numbering" and apply the missing "Heading" styles to the empty levels.
  • Update the TOC, ready.

HowTo: Fix the Table Of Contents when a chapter is missing

You have changed the styling of a header. Clear the formatting of the header and re-assign the header-style

Help by documentation.openoffice.org

See the international portal for help: http://documentation.openoffice.org

img-2 14