TYPO3.org - manual for developers¶

Share the documents on typo3.org¶

It's exceedingly easy. Manuals for “real” extensions (like a message board you made) are simply put in the location “doc/manual.sxw” inside the extension and then uploaded as usual. The existence of the Open Office document is automatically recognized and displayed on typo3.org.

For all stand-alone documentation (that is it has no programming code with it) you still just make an extension (typically the extension key should be prefixed “doc_” - like this document for instance!). Of course it makes no sense for people to download your extension then (you can disable the appearance of the extension in the EM so it does not get downloaded), but the point is to use the existing machinery of the Extension Repository as a vessel for bringing your document online!

Get the template¶

On typo3.org there is an extension “EXT: My Extension” (doc_template) . Go and get the source file as a template for your own extension:

You can also download the file from the “Details” view of the extension:

Store the SXW-file in the extension directory of your extension. Use the path “doc/manual.sxw”.

Edit the meta information¶

When you open the template file you'll see something like this:

First, change the extension key which is just ordinary bold bodytext:

Then open the dialog “File > Properties...” and edit the meta information which is shown in the gray fields:

Enter your name, your email address and in the “Description” tab enter the document title. After that your document header looks like this:

Using styles¶

Since we have rules about the layout of the documentation you must use certain paragraph styles only. By default OpenOffice shows the style collection “Automatic Styles”. It would be better if you change to the view “Applied Styles” which will show all allowed styles since each of the styles is used at least once in the template document (until you delete the dummy content).

From this palette your are allowed to use the non-gray styles you see here:

• Heading 1: Used for the document header. Use this if your document is very large and needs division into major sections (see documents like Inside Typo3 or TSref as examples). Typically you don't use this.On typo3.org the headlines are numbered and “Heading 1” has the first position in the numbering: X .x.x

• Heading 2: For regular sections in your documentation. The template document (doc_template) recommends a certain set of sections. These thematic sections are described so we can unify the approaches in the documentation and tag the content so it makes it easier to find for people. The sections are described as follows:

  • Introduction 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. Screen shots 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 relevant information.
  • User 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. Target group: Users (green), Administrators or Developers in that priority. Depends on the extension.
  • 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 (blue)
  • 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 (orange)
  • Tutorial A full point-a-to-b-to-c walk-through of an application of the extension. Include screen dumps. 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
  • 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.
  • Change log Use this section to document all the changes through the versions.

  These categories of content are designed especially for extension manuals. For other kinds of documents they may not really apply. Apart from the “Introduction” section (which you should always make in order to describe the purpose of the extension/document) the others can be left out as you like. No worries.On typo3.org “Heading 2” has the second position in the numbering: x. X .x

• Heading 3: For subsections in your documentation.On typo3.org “Heading 3” has the third position in the numbering: x.x.X

• Heading 4: Headlines inside a section

• Heading 5: Headlines inside a section, typically used for the header “Example”.

• Preformatted Text: For code listings.

• Text body: For all bodytext. NOTICE that the style “Default” easily sneaks in instead of “Text body” but you must use “Text body” for your document.

• Table Heading/Table Contents: Styles automatically used for tables: Headers and content

• Table Contents/PRE: This is a custom style which must be used for code listings inside of tables. The code listings will be shown with a slightly smaller font than “Preformatted Text”. Generally be careful not to make too long non-breaked lines in code listings inside of tables; On the web pages on typo3.org those listings will expand the table horizontally and make it hard to print.

The other styles are automatically used for the footer and index table in the document top. Don't use them. Don't worry about them.

Testing the correct use of styles¶

Most likely you will not manage to make your document right in the first attempt. In particular it can be hard to spot where you have used various styles. But typo3.org helps you to “validate” the use of styles. When your document is uploaded you can test it like this:

Click the document title as it is available from “typo3temp/manual....sxw” (which is the temporary position of the document on the server. Then you'll see something like this:

All paragraphs are shown with dotted lines so you can easily see them. Headlines are shown in a special color scheme for “Heading 1-5”, tables as well. But most importantly if you have used an invalid style it has a red background! So in this case you go back to OpenOffice, place the cursor in that line and then you'll find that...

... the style “Default” was used for that paragraph! Simply double- click “Text body”, save the document, upload the extension and the problem is gone.

Tables for TS properties¶

The extension “TSConfig / TypoScript Object Reference” contains a static table with the structure of TypoScript objects for three cases: TypoScript template building, Page TSconfig and User TSconfig. The access to this local reference is normally found as a little “TS” icon like this:

Clicking the icon will bring forth this view:

The information for this tree is directly extracted from the total number of documents on typo3.org. That includes any manuals you make!

If you look into a document like TSref or TSconfig you'll see that the four-column property tables all have a little code encapsulated in square brackets in the first paragraph after the table:

In this case the code

[tsref:(cObject).CTABLE]

will add the content of the property table to the structure:

Syntax:

This is the syntax for the code line:

[type-ref] : [object-path] / [object-path] / ...  ;  [type-ref] : [object....

• [type-ref] can be “tsref”, “page” or “beuser”
• [object-path] is the path to the position in the tree in the browser. You can specify many object-paths separated by “/”
• Use the semicolon “;” to separate references to different types of references (that is if some properties apply to both “page” and “beuser” config. See example).

[page:mod.web_modules; beuser:mod.web_modules]

[page:TCEMAIN.default/TCEMAIN.table.(tablename)/->TCEMAIN_tables]

[tsref:plugin.tx_t3references_pi1]

When describing new features...¶

When writing your documentation, please consider to:

• Note at which version a feature was introduced

  It has been requested that manuals like TSref put in a note which tells from which version of the extension a certain property is available. This is now recommended as a good practice.

• Highlight keywords

  Also there has been requests for highlighing object names and properties of TypoScript you enter.

  myObject = HTML
  myObject.value = <tagstart>something</tagend>
  

  (Above the object and property names have been highlighted in red)

Linking¶

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

Use absolute URLs only (for now). When linking to other pages on typo3.org just browse to the page and copy the link into this box. Make sure you are browsing the pages at “http://typo3.org/” (not “http://www.typo3.org”). We want “internal links” to be recognized by the main domain “typo3.org”.

Finalizing¶

When you are finished with your document you should update the index in the top of the document. It doesn't automatically reflect the structure, so simply 1) place the cursor in the index table and then 2) right-click and select “Update Index/Table”:

Other notes about “doc/manual.sxw”¶

One thing you should be aware of is that the file “doc/manual.sxw” is not downloaded with extensions by default! Simply because most people don't need the manual locally. If you wish to download the full extension with doc/manual.sxw, simply tick the checkbox for that option when you download extensions:

Number of pages and filesizes¶

It is important that you try to make your manual.sxw file as small as possible. If the file exceeds about a megabyte you (and others) will have problems having the file included in the extension directory. The EM will simply make some errors. So keep it small. In particular that has to do with the way you handle images. So make images well compressed. Please read the section about images for details.

However it is not always possible to keep the filesize down below 1MB. If that is not possible, simply 1) upload your extension with a blank document in “doc/manual.sxw” and then 2) go to typo3.org, manage your extension so that the “doc/manual.sxw” has been recognized, then upload the real manual.sxw file in the “Doc-review” menu and press the “Merge?” button just as if the document had been submitted for review.

Documents uploaded by the “Doc-review” menu can be as large as 3MB but still , better spend some time making the document small for the general sake of the typo3.org site, OK!

The amount of content is not so critical regarding filesize since the contents of a Open Office Writer document is compressed. For instance the TSref is a 260K+ text characters large document and that only takes up 200 KB. But when that document is expanded from the zip- archive the content.xml file inside is very large and large amounts of content takes long time for the server to process for comparisons or simple rendering.

Inserting images¶

When you insert images you can either:

• 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). So CTRL+V does NOT WORK! The image will show fine, but internally it's stored as some kind of meta- file which cannot be shown on the web!

  

  

• Alternatively you can use the traditional way “Insert > Graphics > From file” and insert an image from your hard drive. 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 screen dumps with large areas of similar color (good png-compression), and use insertion of JPG-files for photographic images. Go for small images, 72 dpi, medium quality.

Insert images without text wrapping around them. So; No text to the left/right of images. Let them have their own paragraph (like you see everywhere in this document).

You can right-click images and select “Caption” in order to add a caption (text below image). That is allowed.

Images from Open Office manuals are displayed online without physical scaling ! So when images are wider than 600 pixels they are scaled down by simply changing the<img>-tag settings. Scaled images on the other hand get linked to a window with the full size image. So people can always click the scaled-down images and see a full, crisp version in a new window. Don't scale/resample screenshots in image processing applications. We want small, crisp screen dumps (see why in the next section below).

Images with dimensions above 50 pixels in both width and height will have a black border applied. Images with one dimension below 50 pixels is considered a “bullet” (a number, icon or something like that) and will not have a black border.

The reason for not scaling the images physically are these; First of all most images are screen dumps. They would probably download faster in their original form than a scaled, antialiased form which takes up more space. Secondly images scaled in HTML still print nicely! (At least with MSIE)

Scaling images¶

Since the documentation for TYPO3 heavily consists of screendumps it's worth to mention here. First of all visual content like images is highly encouraged! And it's very easy with OpenOffice since you can use plain copy/paste (see above). But it is worth to teach you a couple of things regarding the typical nature of screendumps.

Images displayed on typo3.org will be scaled down if wider than 600 pixels. So the question is: Should you also “resample” the image to 600 pixels width in Photoshop? The answer is NO! The reason is that a screendump consists of large parts of the same color. If you begin to scale an image you will get anti-aliased transitions between those areas of similar color. And consequently that 1) makes the image harder to compress = larger files and 2) the quality gets worse. So larger and uglier files if you scale the image to new pixel dimensions! Contrary you get crisp and small images if you just keep the screendump as-is! And the print-out will be awesome as well!

You can see the difference visually here:

The image at the top has been scaled from 516 pixels to 400 pixels. It is clear that the scaling has introduced a lot of gray tones. These graytones makes the image harder to compress as gif or png. And the image gets more blurry. So what is the point? The point probably was to keep the images as small as possible, but it happened to do the opposite in the end!

Here are the files in full size. So what prints best? What looks best? And notice the file sizes!

13,76 Kbytes, 64 colors, Gif

5,48 Kbytes, 64 colors, Gif

How to “debug” large images in Open Office documents¶

That is in fact very easy. Just renamed the manual.sxw file to “manual.sxw.zip” and open it! This is how you can do in Windows XP:

Go to the Pictures folder and sort by size:

From here you can open the largest images in a Photoshop and see if it can be compressed more. Often you'll find that only a few images are taking up far too much space and the overall size of your document can be reduced drastically by a few optimizations.

Either you can save the image back into the archive and rename the archive file back to “.sxw” or you can of course have a copy of the sxw-document open into which you simply paste the modified images.

Managing the online Table of Contents (TOC)¶

When you want to share your document on typo3.org simply upload the extension. Then go to typo3.org, find your extension and click “Edit”:

Notice how the field “doc/manual.sxw” will display this message the first time a manual is found for the extension. “Writing new TOC ...” means that the TOC (Table of Contents) is written to the database. The TOC is simply all the “Heading 1-3” paragraphs found in the document and since they reflect the structure of the document they are written to the database in single records.

Click “Edit” again and you'll see that now the document has been recognized and the TOC is written and displayed:

Now tick the “Edit TOC meta data” checkbox and set the meta-data:

You can tag each of the “Heading 2” levels with a category. If you have adhered to these categories in the making of your document please use this feature. This will be reflected at various places where the extension is shown: Extension Info: Here you will have links directly to the relevant sections if available. Further below the information table you'll have the full content of the “Introduction” section printed.

Extension listing: In the listing of extensions you'll see links directly to the individual sections as well:

The documentation matrix: Here you'll have a little flag for each of the sections available in your document. Also notice the flag indicating language.

“L3” means “Level 3” and if you set this flag for a level 2 section it means that the document is NOT divided into single pages for each “Heading 3” found in that section. Rather the full “Heading 2” section will be shown as one single page and the links from the TOC to the level 3 pages will be anchor-point links.This feature is useful if there is only little content for each “Heading 3” section so that a display of the full “Heading 2” section looks better.

You can specify content types (Faq / Examples / Reference) for the Level 3 sections if you like. This is not used yet, but later I imagine that we can have a collection of direct links to examples, faq's and references somewhere.

Target Audience is a kind of rating you can apply. The green/blue/orange color codes represents content directed to Users/Administrators/Developers. Please use this to rate the parts in the document. Thus it will be easily seen by each target group if the content they are reading is also written with them in mind.Setting Target Audience for a higher level (eg. “Heading 2”) will reflect on lower levels unless a flag is specifically set there.

Finally you can select a “Document Category” which defines where the document is listed in the “Documentation Matrix”. Likewise “Language” should be used to set the language of the document. Thus people can easily spot information in the local languages. (See image above with English flag)

Updating the TOC¶

When you edit your document it's most likely - if not the everyday situation - that sections are moved around, renamed or added. In that case you have to synchronize the new structure of your document with the TOC in the database on typo3.org. This screendump shows how that looks:

Here you see two very common things; First the header “Managing the manuals on typo3.org” has changed to “Managing manuals on typo3.org”. However in this case that header is automatically recognized. The second and more visible example is the new section “Proofreading workflow”. You need to tell the database that this section is either new or a substitute for an old one (which you can select with the selectorbox).

If you need to make changes in general you can tick of the “Show all selectorboxes on next update”, and you'll have a selector box for each item in the TOC.

Finally when you have set the TOC as it should be, you'll have to submit the changes. Only when this step is completed the new document is inserted instead of the old!

And you are done.

Why keep a redundant TOC in the database?¶

Some of you might wonder why we have to maintain a TOC in the database as well. Why not just write a new TOC each time the document is updated? The answer is simple. Since Open Office offers no unique id per header section inside the document we'll have to invent and synchronize that ourselves. There are two very good reasons for that.

First of all, links to a section in the online documentation are tied to the TOC element uid in the database. So if we deleted the old TOC and inserted a new one each time we update documents all links from external sources to that page on typo3.org would be invalid.

Secondly the only way of attaching meta-data as well as annotations to the documentation is if we have a unique identification of the section.

So as you see we need a unique id for each section. Since Open Office doesn't offer that we'll have to keep track of it ourselves.

This tool for managing the TOC could still be improved. In particular it would be nice if we could later delete and move references to old TOC elements by time. That is not possible yet (Dec. 2002).

Verifying the Open Office Document¶

As said, simply upload the extension and all that. Then go the extension page, click “Doc-review” and click the title of the document. You'll immediately have the full content of the document shown in “debug-mode” and you can see if there are invalid paragraphs or missing images.

Managing members¶

Members of an extension are able to see and download the extension if it's still “Members-only”. Further membership may have other consequences in the future (moderator, closed development forums, wiki's...). And finally a member having the upload password for the extension will be able to upload the extension to the repository.

If you disable “Members only” (which is set by default) you cannot set it again. Then the extension is public and that's it. Setting the flag again can be done only by a backend admin (such as Kasper).

You can lookup users for membership very easily by just entering some search word in the “Lookup” field and the users matching will be listed. Then tick of those you want to include.

Cleaning up old versions:¶

Please be a kind dude and remove old, irrelevant versions from the repository when you can. It keeps the database tidy.

Simply click “DELETE” and update - then the selected versions are thrown out.

You can also tick off the “Create a new dev-version based on current.” This will as it says create a new version totally equal to the more recent. This can be an advantage if you made any changes on TER to the repository version such as setting the title/description/state from the key table record.

Important notes to the owner!¶

When merging translations into the repository please make sure that the repository has been just updated with your latest version of the extension! Then make the merge and afterward download the new version as your original! Otherwise you'll just overwrite the new translations next time you upload the extension!

(When a translation is merged into the repository the “translation storage” is cleared, but not deleted. This means that translations accidentially removed by an owner who overwrites the TER extension can ultimately be restored on the low database level. But don't depend on it!)

The extension “context_help”¶

There is an extension, “context_help”, which is the extension triggering the usage of context sensitive help in TYPO3 but also contains some amounts of locallang files with CSH content.

Further you will find CSH content in the system extensions “cms” and “lang”.

More information¶

If you wish to read about the CSH framework, visit the Inside TYPO3 document .