Wikihelp - The Online Help for LibreOffice

From The Document Foundation Wiki
Jump to: navigation, search

This page describes the implementation of Wikihelp (also known as Help Wiki, Wiki Help, Online Help) — http://help.libreoffice.org

Other Wikis

This wiki contains basic help/documentation for LibreOffice. For everything else related to TDF/LibreOffice/The Document Liberation Project, please see

Technical Information

  • Runs on MediaWiki
  • Most pages are translated into other languages
  • Closed registration

Generate wiki pages

In helpcontent2/ run help-to-wiki.py.

$ ./help-to-wiki.py -r

The -r switch generates the redirects (needed for context sensitive help). Help IDs change sometimes, so redirects must be generated for main versions. Not necessary for minor (translation) updates.

Postprocess wiki pages

Delete 0 length pages. MediaWiki would reject them.

$ cd wiki
$ find . -size 0c -delete

Replace <A HREF to &lt;A HREF. MediaWiki thinks it is a spam.

$ for i in Common/Hyperlink/*;do sed -i "s/<A/\&lt;A/" $i;done

If we work in a branch, not master, we need to move everything under wiki/ into wiki/something, for example wiki/5.2, and adjust links:

$ cd wiki/5.2
$ for i in `find . -type f`;do for j in Basic Calc Writer Math Chart Draw Impress Common;do sed -i "s/\[\[$j/\[\[5.2\/$j/g" $i;done;done

Upload wiki pages

In order to upload, you need the wikisetup.txt in helpcontent2/.

wikisetup.txt

wiki=http://help-api.libreoffice.org/api.php
upload=http://help-api.libreoffice.org/index.php5/Special:Upload
name=WikiSysop
password=**********
$ upload-wiki.pl -i -r

The -i switch will upload images (recommended for major releases). The -r switch will upload redirects. On error, the script will retry infinitely to upload the page. This is good, when you have temporary server errors. Otherwise the script will run forever, so issues have to be solved. It takes more than a day to upload all help pages.

Setup version redirect on server

$ ssh wsadmin@vm190.documentfoundation.org
wsadmin@vm190:~$ vi /var/www/helpwiki/core/extensions/WikihelpRedirect/WikihelpRedirect.php

add new version:

       elseif ($version == "5.2") {
               $try_versions[] = "5.2/";
       }

Available Templates

Unknown

Feedback and Bugs

  • To contact the sysadmins in charge of Wikihelp, please see the Infra/Services page.
  • Bug Reports
    • To report a technical bug about the Wikihelp Infrastructure, please
      • Use Redmine and
      • file a bug in the Infrastructure project
      • with Category set to Help Wiki.
    • To report a content bug or feature/improvement request, please

(Our old method for dealing with Content bugs/enhancements was to use Bugzilla and file a bug with Component: Documentation and Summary prefixed with: WIKIHELP:.
We might use Bugzilla again in the future.)

Why Wikihelp?

The help files as they are now (the .xhp) format is hard to edit for developers and the documentation writers. Also, it is unfortunate that to see your changes, you have to actually rebuild part of LibreOffice. Both the developers and the documentation writers need something easier, something that can be created collaboratively, and easily. But still, it has to be easy to handle for the localization teams.

Wiki is so far the best free tool for collaboration editing. It gives anyone the freedom to improve things. With help implemented as a wiki, any user of the suite can (potentially) just describe the functionality better, should he/she find out that something is described wrongly, or just partially; but of course this does not mean that we will open it for public editing from the Day 1, at the beginning the accounts will be created on request.

The Plan

  • Only the English pages will be editable
  • Strings from the English pages will be uploaded to Pootle
    • So that you can work the way you are used to
    • The Translate Toolkit has a tool to extract strings from wiki markup - txt2po. If necessary, it has to be extended to handle everything we need in the Wikihelp
  • Existing translations will be converted
    • So that the work is not lost, that is, everything that has been translated so far has to be translated in the Wikihelp version too
  • The Pootle tranlations will be applied over the English version
    • But if a language team decides that they want to translate directly in the Wikihelp, their language version will be open for editing directly in the Wikihelp

The Timeline

  • Currently, we are converting the .xhp files into wiki markup
    • It is now online as http://help.libreoffice.org
    • Needs to be polished [for example, it is yet unclear if we want to treat shared content (embedding) specially]
    • Bugreports are appreciated! File to https://bugs.documentfoundation.org, and assign to kendy@collabora.com, with wikihelp: <description of the problem> in the subject
    • LibreOffice 3.3 redirects to the on-line help, if the off-line help is not installed
  • The content of the Wikihelp has to be exported to .pot files
    • Might need changes in the txt2po filter
  • The translations from the .sdf files or .po files have to be converted to the wiki markup
    • Tested thoroughly that no information is lost
    • Tested also that when applied over the English version, all still looks fine, and no formatting is lost

Future Plans

  • Later we need tooling to convert the online help back to offline version(s)
    • To a platform-native help system
    • Windows, Linux, and Mac OS X
    • From the engineering point of view, we don't want a home-grown help system, as we have now
    • Needs more research, to see if we don't lose features, etc.
  • When done, the Wikihelp becomes the authoritative version of the help
    • But we'll still be able to incorporate changes from the .xhp files, when merging from OOo

Open questions

  • Extended tips (done)
    • Cannot be part of the Wikihelp. Most probably these have to be handled separately, that is, still part of the source code
  • Security (question by Jean-Baptiste Faure)
    • To fight spammers, see MediaWiki
    • David Nelson proposes to have editing rights dedicated to some groups only (dev, l10n, doc, ...)
  • Proposal by Jonathan Aquilina: when a page is edited, a mail is sent to a list to make the team aware and allow them to check for consistency as well as content
  • About offline editing, Kendy propose to use Wiki publisher extension and may be reviewing a modification feature in LibreOffice.
  • Currently, there is no way to use a glossary or TMX on the wiki.
  • What about help of installed extensions? Currently, extensions can provide help in the same system of off-line help than LibO.
    • (Apparently, there is a bug that prevents LibO from checking extension help.)
      • This looks like tdf#33209 - WIKIHELP LOCALHELP: does not show for extensions - ASSIGNED
  • Perhaps it should be interesting, from performance point of view, to have some sort of cache to store on-line help pages read by the user in the user profile.
    • If you use server-based Windows-user-profiles (which contain the LO user profile), then the whole Windows user profile is transfered from the server to the working place when you log-in. Therefore it would be unfavorable to have such help pages stored permanently.
  • The built-in help viewer has the feature, that you can make the window very small. You can hide the navigation. And the window has only a very tiny toolbar. Therefore the build-in help is well-suited for small devices like netbooks and tablets. For the Wikihelp a special modus is needed, similar to the special versions http://pocket.dict.cc/ or https://en.m.wikipedia.org for example, without large header and without side pane.
  • Sophie mentioned, "in some countries, you are not allowed to deliver a software without translated build-in help." see http://lists.freedesktop.org/archives/libreoffice/2015-August/069556.html. And there exist situations where you cannot use the Wikihelp because you have no physical access to the Internet, or because you are not allowed to use it, e.g. in enterprises or in schools. Therefore a built-in help is still needed. If it is intended that the Wikihelp becomes the authoritative version, a time frame for the transition is needed. If it will be done in the next half year, no one will spent time to improve the built-in help. But if it is known, that such will not happen earlier than in four years, it makes sense to fix bugs in the extension "helpauthoring.oxt" to make it usable.
  • The search in the built-in help is restricted to the current language, searching in the Wikihelp gives results from other languages too.
  • The WikiHelp has no Index.
  • Printing of a page of the built-in help prints only the content, WikiHelp prints additional header and footer stuff.