User:Regina/HelpAuthoringDashboard

META: HELPAUTHORING
The meta-issue for tracking problems with the helpauthoring extension is https://bugs.documentfoundation.org/show_bug.cgi?id=93580

Issue: HelpPrefix by LO file dialog
- For a possible fix see https://bugs.documentfoundation.org/show_bug.cgi?id=93580#c4 - Fixed in helpauthoring.oxt version 3.1.1
 * 1) Set LO to use LibreOffice file dialogs for Save/Open.
 * 2) Use item `Set Document Root` in menu `HelpAuthoring`.
 * 3) Select the correct directory.
 * 4) Look at the property `HelpPrefix` in the file `\user\config\helpauthoring.cfg`. It should have got a dash at the end.
 * 1) Again, use item `Set Document Root` in menu `HelpAuthoring`. Notice, that the field `path` is pre-filled, but it has a dash at the end. If the user clicks `Select` the HelpPrefix will have two dashes and therefore will be invalid.

ToDo: Remove l10n and oldref
These attributes are no longer needed, because the transformation to helpcontent2 finished long time ago. It might be an "easyhack" task to cleanup the help files.

See also: https://bugs.documentfoundation.org/show_bug.cgi?id=93580#c6

Issue: The extension has defects with Windows filepicker
If LibreOffice is set to use Windows filepicker, then getDisplayDirectory of the filepicker returns an empty string and therefore file helpauthoring.cfg contains wrong paths. https://bugs.documentfoundation.org/show_bug.cgi?id=93634

Workaround: Use LibreOffice's own filepicker dialog.

The fix for faulty getDisplayDirectory in https://gerrit.libreoffice.org/#/c/18127/ is available in master since 2015-09-03, but still problems in using setDisplayDirectory and getDisplayDirectory in Basic in Windows, see https://bugs.documentfoundation.org/show_bug.cgi?id=43021

Future: Extended Tips
Extended Tips are currently inside the help files. When the help content itself is maintained in the Wiki, a new solution for Extended Tips is needed. These tips need to be available without Internet access.

Olivier Hallot has described his observation in the linked mail. Idea: Using property "tooltip_markup" of a widget in a UI dialog, edited by Glade. http://nabble.documentfoundation.org/ahelp-ahelp-Extended-tips-in-Helpcontent-VCL-Glade-tp4157991.html

Comments (for original read the thread!) in the thread by

Caolán McNamara 2015-08-25: Pro and Contras

Markus Mohrhard 2015-08-26: Technical solution exists. Current translations are preserved, but strings are duplicated and future translations are affected.

Sophie Gautier 2015-08-28: Make translation a topic during the l10n workshop at LibOCon

Future: Extended Tips | Extract from current code
Comment by Caolán McNamara 2015-08-25: Markus has an extended-tip extraction tool as ./bin/extract-tooltip.py

Comment by Markus Mohrhard 2015-08-16: We have already a working solution for the extended tooltips. There is a script to extract them from the help and maintain them independently. As far as I known Caolan is even thinking about adding support for extended tooltips to the ui files.

Future: TOC and Index
Comment by Markus Mohrhard 2015-08-16: That is what Kendy means with missing JavaScript code. The plan would be to implement a search and index through Javascript. Actually there are wikis which provide this feature similar to the way we do it in the build-in help right now. So this is one of the required steps before we could switch to wikihelp.

Issue: Attribute localize not preserved
From https://bugs.documentfoundation.org/show_bug.cgi?id=93580#c1: issue 03

Has its own issue now https://bugs.documentfoundation.org/show_bug.cgi?id=93981

Issue: Special section id="howtoget" is treated wrong
https://bugs.documentfoundation.org/show_bug.cgi?id=93580#c2: issue 04

Has its own issue now https://bugs.documentfoundation.org/show_bug.cgi?id=93982

ToDo: Glossary and Style guide
The help should use consistent wording and style. Therefore a guide is needed. For example: What term should be used for the kind of tools, which have a little black triangle to open it, and which you can grip and move to get a separate tools window?

Issue: Using emph-element in connection with switchinline-element
https://bugs.documentfoundation.org/show_bug.cgi?id=94154

Some files (e.g. /source/text/shared/01/01020000.xhp) have a nesting

But according xmlhelp.dtd switchinline-element is not allowed as child of emph-element. With LibreOffice until at least BuildID fdafa5302df26df4f147b0d2efb6064389a1330c 2015-08-22, the wrong structure is turned into the valid structure

But from BuildID eb2e1ab4651350bffc53f618961a910bd3bbcfd9 2015-09-02 (likely earlier too) it is turned into the invalid structure

The changed behavior was tested with the very same version of the helpauthoring extension.

Problems:
 * The changed behavior is likely in the way LibreOffice uses the .xsl transformations. My question, what was changed in the code in regard to .xsl transformation got no answer.
 * I have searched for  and got 208 hits in 105 files. That is far to much to correct the wrong nesting in the files directly. It would produce a lot of "changed" notifications for translators.

Future: Preview for help authores
Currently you can see the result of editing a help page only if you compile helpcontent2 and so get a changed installation. It would be nice to have a preview of the helppages without compiling. I have started some tries, find the macro in https://bugs.documentfoundation.org/show_bug.cgi?id=95064.

I have made a .jar file, which contains a copy of the document, of which you want a preview. But using the help viewer via vnd.sun.star.help: only works once. I can update the file in the .jar container, but the help viewer still uses the old version and viewing another file is impossible in the same session, the view is empty. I don't know what might be the reason.

If anyone has an idea for this or an idea for a totally different way, please tell me.

Conference
Frank Peters & Uwe Fischer: OOo Documentation - Online Help and Beyond Slideshow from talk on OpenOffice Conference seen at http://de.slideshare.net/jza/ooo-documentation-online-help-and-beyond [2015-09-01] Slide 12 contains a diagramm, similar diagramm extended with the web-help would be nice.

https://wiki.openoffice.org/wiki/Category:Documentation/OnlineHelp
Topics there [all visited 2015-09-01]
 * https://wiki.openoffice.org/wiki/Application_Help_Development_To_Do
 * https://wiki.openoffice.org/wiki/Create_and_modify_Help
 * https://wiki.openoffice.org/wiki/Documentation/Extensible_Help (including diagram)
 * https://wiki.openoffice.org/wiki/Extended_Tip_Help
 * https://wiki.openoffice.org/wiki/Fix_Help_Issues
 * https://wiki.openoffice.org/wiki/Font_Problem_with_Online_Help
 * https://wiki.openoffice.org/wiki/Help_Agent [was removed from LibreOffice, still exists in Apache OpenOffice]
 * https://wiki.openoffice.org/wiki/Help_context
 * https://wiki.openoffice.org/wiki/Help_ID
 * https://wiki.openoffice.org/wiki/Help_Standardisation_issues
 * https://wiki.openoffice.org/wiki/Help_Viewer
 * https://wiki.openoffice.org/wiki/Help_Viewer_Bookmarks_tab_page
 * https://wiki.openoffice.org/wiki/Help_Viewer_Contents_tab_page
 * https://wiki.openoffice.org/wiki/Help_Viewer_Find_tab_page
 * https://wiki.openoffice.org/wiki/Help_Viewer_Index_tab_page
 * https://wiki.openoffice.org/wiki/Helpcontent2
 * https://wiki.openoffice.org/wiki/OOo_OnlineHelp
 * https://wiki.openoffice.org/wiki/Report_bugs
 * https://wiki.openoffice.org/wiki/Sponsor_a_Help_area
 * https://wiki.openoffice.org/wiki/Submit_patches
 * https://wiki.openoffice.org/wiki/To_Do_List

Further content for OpenOffice.org
[all visited 2015-09-01]
 * https://wiki.openoffice.org/wiki/Documentation/DevGuide/Extensions/Help_Content
 * https://wiki.openoffice.org/wiki/Documentation/Dashboard/Application_Online_Help
 * https://www.openoffice.org/documentation/online_help/index.html It contains the link to the pdf-version of "Understanding and Authoring OpenOffice 2.0 Online Help" aka OOo2HelpAuthoring.
 * https://www.openoffice.org/documentation/online_help/helpauthoring/HelpAuthoring.html
 * https://www.openoffice.org/documentation/online_help/OOo2HelpAuthoring.pdf
 * http://specs.openoffice.org/appwide/help/ExtensibleHelp.odt

[visited 2015-09-11]
 * Uwe Fischer 6.Feb.2012 "Re: Conventions in help files" http://mail-archives.apache.org/mod_mbox/incubator-ooo-dev/201202.mbox/%3CCALApVL%3D9%2B1o7McyB5V_%3D42mWrU7R3tJhR1P2YSU1JcZQXbrSsw%40mail.gmail.com%3E

Modifing the view of the application help
The necessary files for modifications are attached to issue https://issues.apache.org/ooo/show_bug.cgi?id=56321
 * allfiles.tree
 * a modified main_transform.xsl
 * a modified default.css

The files need an update for LibreOffice.

Missing ability of the help viewer
Problems identified so far
 * The library libxslt supports only XSLT 1.0 and therefore does not know the function . Because of that it is not possible to import the file   while using.
 * Some themes do not contain all needed images, but the fallback to Galaxy does not work for the help.

Some tests with the transformation shows, that the way is not promissing. Instead an improvement in core should be tried. Adapt the currend protocol handler or write a new one for use in helpviewer. Try to avoid duplicating code.

LOCALHELP: Pictures in start page missing (edit)

No graphics nor links in the integrated help

LOCALHELP: Localised (L10n) images not used from the icon-theme

LOCALHELP: Images not displayed with newer icon themes → central issue for the problem

[DE] Missing symbols in OLH for "File - New" help text

Offline-help (DE): Placeholder "vnd.sun.star." displayed instead of icons

[closed duplicate] Help viewer shows missing icons as "vnd.sun.*" placeholders rather than taking icons from parent icon themes and links.txt

Images not displayed in local help (a missing/broken image link icon appears instead)

The folder res/helpimg is missing in the Tango and Oxygen icon set

LO50b3: Images are not shown in local Help

Help: Pictures missing

Icon problem in Help

Other improvements
Problems identified so far:
 * The help viewer does not use the image size from the images itself. But adds some space to the right.


 * The column width of tables cannot be set via CSS and relative setting via colgroup works neither.

(fixed) 4.4.0.beta2 inline help images horizontally stretched

(fixed) Help content landing page icons scaled out of proportion in local help installers

LOCALHELP/WIKIHELP: Large icons should be used

[HELP] note and warning paragraphs are aligned incorrectly

Interfere with security options
Images in help not visible if security option is selected (comment 18)

Missing icons in applications
REPORT BUILDER: Missing insert field icon in Add Field dialog

ICONS: Parent icon theme links.txt duplicate records not inherited in child themes