Bibletime2Frontend

Design

The analysis and the class design of the frontend.

• BibleTime2FrontendNavigator

We'll probably use WebKit as HTML renderer (here is an initial evaluation).

Documentation

We need a good online help system in BibleTime. It should be context-sensitive, i.e. if you press F1 / Help in a dialog information about the current dialog should be displayed which explains what the GUI elements do. To do this cross-plattform it might be necessary to write a simple online help application or evalutate Qt assistant. If we decide to write our own app this could be done as a totally seperate binary or by another main window which can be controlled by the dialogs, etc.

The best and easiest form of online help is tooltips. I think it would be a good idea to force a guideline according to which you are not allowed to check in UI code which doesn't have both tooltip and whatsthis text if they are available for the elements. Like it or not, for some reason people just don't read help documents - and why bother, if the UI is self-documenting and intuitive. --Eeli

I agree! We need to make sure the tooltips can work with normal HTML. Do you think we can do without a handbook entirely? What about screenshots? --mgruner

From Qt docs: "The "What's This?" text is used to provide a brief description of the action. The text may contain rich text." (rich text is html). OK, I tested this with Designer. It accepts html, also pictures: <img src="/work/mydocs/nuolialas.png">, and span style="font-size:20pt" etc. Maybe it just uses Qt's rich text engine? But href links don't work. You can use paragraphs and align text. Tables work also.

Rich text doesn't work with tooltips.

For visible shortcuts tooltip and whatsthis may be enough, but menus etc. may need some other documentation. (Edit: Qt has whatsthis for menu items, too.) Also some kind of workflow oriented HowTo could be nice. For example for the Navigator widget good tooltip or whatsthis can serve as a simple tutorial. If we take my Navigator proposal, it could read in book selector text area: "Write the name of the book or some initials. You can write the chapter and verse here also. Press Enter to read the book or Tab to move to Chapter selection." Then there are "Next book" and "Previous book" buttons and "List of all books" button.

Read http://accentgrave.blogspot.com/2006/04/whatsthis.html and follow the link to the pdf doc. Maybe that gives some ideas. Whatever path we take, simple tooltip is always great as long as it gives a bit more information than the picture in the button of which you wonder what it is. Good tooltips have saved my day many times. --Eeli

Translations

Bible Booknames

We'll need to find a way to enable translators to translate all books available in OSIS as well as define abbreviations for them that match their language. This should be possible by defining a simple std::vector, QHashMap (or something better) of QStrings containing

1. osisID
2. translation
3. comma-separated string of abbreviations

for each book. This "array" can be used to get the data for display and parsing, and we will make sure that tr() is called for each element when it is filled. The benefit of this is that it integrates into the normal UI translation and eliminates the need to load data from other external files.

User Interface

QT offers an own translation mechanism using the QObject::tr() function. The main drawback is that it uses its own internal file format instead of .po and .mo files. It seems that we can use ts2po and po2ts (debian package is called translate-toolkit) to convert the untranslated .ts files to .pot files, let translators work on them with KBabel, and convert the translated .po files back to .ts files (which later need to be compiled with lrelease). That way we can standardize on one format (see below). (We have to check if the conversion process between ts and po is lossless, Qt has a comment field and plural forms for the translation lookup)

Qt includes QtLinguist which is a graphical tool for translators. It's of course cross-platform and uses Qt's own format. Does it lack someting? (edit: Now I see... it doesn't handle the BT documentation.)

Documentation

Currently the documentation is in XML (docbook) and can be translated with tools from KDE. They extract all translatable strings to .po files which can be translated and be assembled to XML files afterward. This would not be possible with the QT file format. We will compile the translated XML files it into HTML pages during release preparation and install the HTML files and images on a user's system. When a user clicks on "handbook", BibleTime will call the system browser and let it open the correct HTML file. (ToDo: Check how this could be integrated with our help system or check if the help system could be replaces by a system-browser based solution)

Website

This works like documentation translation currently (docbook-based).