Documentation/DevGuide/Contributing to the Developers Guide

The Developer's Guide in the Wiki uses many standard markup features of MediaWiki. This Contribution guide assumes that you already have some knowledge of MediaWiki markup.

OpenOffice.org documentation is organized using the subpages feature of MediaWiki. The subpages group the document contents together, give structure to the documents, and keep similarly named pages apart.

The Developer's Guide is located at Documentation/DevGuide, and each chapter is an additional subpage:

• The chapter titled First Steps is in Documentation/DevGuide/FirstSteps
• The chapter titled Professional Uno is in Documentation/DevGuide/ProUNO/
• etc.

A page in the Developer's Guide has several elements that are mandatory.

• The link to the Table of Contents (TOC) for the chapter
• The DISPLAYTITLE
• The page content
• The PDL
• The Category

To contribute to existing pages, all you need to do is simply edit the Wiki pages just as you would any other Wiki page.

The TOC

The TOC template is used to insert a navigation tree or Table of Contents (TOC) on the right side of the Wiki page. The TOC template is documented in the MasterTOC template page.

The TOC template has 2 parts:

• A MasterTOC page that is used in all TOCs. You do not need to edit this template.
• A chapter specific TOC that defines all the individual sections or pages in the chapter, and the order they are presented in.

Add a new chapter to the Developer's Guide

To add a new chapter to the Developer's guide:

1. Add at least one page to the Wiki
2. Create a chapter specific TOC template with the name <chaptername>TOC
3. Add the new chapter TOC to the main Developer's Guide TOC at Template:Documentation/DevGuide/DevGuideTOC
4. Add the new pages to the chapter TOC
5. Add the new chapter Category to the Developer's Guide master category

Add a page to the Developer's Guide

To add a new page to an existing chapter in the Developer's Guide:

1. Add the page to the Wiki. Make sure that the page is in the correct subpage.
2. Add the TOC link
3. Add the PDL template
4. Add the correct Category
5. Edit the chapter TOC template, and add the link to the new page

Move a page in the Developer's Guide

To move a page in the Developer's Guide:

1. Move the page to the right subpage
2. Delete the link to the page from the old chapter TOC location
3. Add a link to the page in the new chapter TOC location

Remove a page from the Developer's Guide

To remove a page from the Developer's Guide:

1. Delete the page from the Wiki
2. Delete the link to the page from the chapter TOC

The DISPLAYTITLE

MediaWiki displays the full Wiki page title including the subpages. This can make the title very difficult to read. DISPLAYTITLE is used to rewrite the Wiki page title. To use the DISPLAYTITLE to rewrite the page title, add this markup at or near the top of your document:

 {{DISPLAYTITLE:Wiki page title that should be shown}}

The PDL template

Documentation on the OpenOffice.org Wiki must have a license. The Developer's Guide has been released under the PDL, so all pages added to the Developer's Guide should have this license statement at the bottom of each page. The Wiki markup to add the PDL license to a Wiki page is:

{{PDL1}}

The Category

The MediaWiki Category feature is used to group the Developer's Guide by book and by chapter.

Each page in a chapter belongs to a Category named the same as the chapter title, and each chapter Category belongs to the master Developer's Guide Category.

IDL extension and links

The IDL extension provides an easy and convenient way to add links to the IDL reference documentation. Use the IDL tags for all IDL cross references wherever you talk in detail about a specific interface or concept. The used tags will result in links from the generated IDL reference back into the guide and will provide a useful resource to find more detailed information about the IDL types. Choose the right tag or the combination of tags, as defined in the extension, to provide the most useful cross reference.

Optional elements

__NOTOC__ can be used to turn off the automatic TOC that MediaWiki will insert if you have more than 4 headings on a single page. This has been done throughout the Developer's Guide where there are enough headings in a page to trigger the MediaWiki autotoc.

Translations to other languages

Translating the Developer's Guide into other languages is important, but there are some important points that you must consider if you are going to translate this document.

The Developer's Guide must follow certain layout conventions regardless of what language it is presented in so that the external maintenance scripts and WikiBots can correctly process things like the IDL links.

Please do not start translations until this section is complete.

Specific guidelines for translations TBD.

• Follow the same structure as the English guide.
• Use the same article names - do not translate the Wiki article names. Use the {{DISPLAYTITLE:Article title}} to localize the article name.
• Use a subpage naming structure that clearly indicates the language of the guide. For example, the Chinese version of the Developers Guide uses this subpage structure Zh/Documentation/DevGuide. The Swedish version could use SV/Documentation/DevGuide/, and so on.

• Link the various languages to each other using the Interwiki links syntax [[ISO_Lang_code:Page_Title]]. (This may be more practical to do with Wiki Templates as more languages are added)
• Use a similar Category structure to what the English guide uses.

A clean category structure is very important. We can run the WikiBot on the categories to do maintenance and other tasks such as collecting articles to build books (ODT and PDF). If the articles in the categories are mixed in with other languages or with other articles that are not part of the book, then we must manually process each wiki article. A clean category means it is easy to pick out articles belonging to a specific chapter in a specific language. For example, the Wiki articles in the English First Steps chapter belong to the Category Documentation/Developer's Guide/First Steps. The Chinese translation of that same article could belong to the Category Zh/Documentation/Developer's Guide/First Steps.

Content on this page is licensed under the Public Documentation License (PDL).