Contributing to the LibreOffice Developer's Guide
The LibreOffice 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.
LibreOffice documentation is organized as separate pages for each chapter or appendix.
The Developer's Guide is located at Documentation/DevGuide, and each chapter is an additional subpage in Documentation/:
- The chapter titled First Steps is in Documentation/DevGuide/First_Steps
- The chapter titled Professional UNO is in Documentation/DevGuide/Professional_UNO
- 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 chapters
Each chapter of the DevGuide is presented as a single page. The Table of Contents (TOC) is generated automatically by the MediaWiki, and it is put on the right side of the Wiki page.
Add a new chapter to the Developer's Guide
You should think twice before adding a chapter to the DevGuide, because it already contains many chapters devoted to the different topics! But, if you are sure please read these instructions:
To add a new chapter to the Developer's guide:
- Add at least several paragraphs of contents to the Wiki as the required contents of the new chapter
- Add the required headers and footers, just like the other chapters
- Add the new chapter Category to the Developer's Guide master category
- Add the new chapter TOC to the main Developer's Guide TOC at Documentation/DevGuide
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 LibreOffice.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 MediaWiki 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.
IDL extension for linking to the correct place in the Doxygen documents is not yet ready in LibreOffice Wiki. The reason is technical problems with the Doxygen generated links. For more information, see ESC meeting minutes from 2022-02-24, section "Dev Guide was imported into our wiki" and a pending Doxygen pull request. The reason is technical problems with the Doxygen generated links] Please do not remove the IDL links, and keep them as they are until the problem is resolved.
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
 |
Note:
|
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.
|
Note:
|
- 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).
|