- 1 META: HELPAUTHORING
- 2 Issue: HelpPrefix by LO file dialog
- 3 ToDo: Remove l10n and oldref
- 4 Issue: The extension has defects with Windows filepicker
- 5 Future: Extended Tips
- 6 Future: Extended Tips | Extract from current code
- 7 Future: TOC and Index
- 8 Issue: Attribute localize not preserved
- 9 Issue: Special section id="howtoget" is treated wrong
- 10 ToDo: Glossary and Style guide
- 11 Issue: Using emph-element in connection with switchinline-element
- 12 Future: Preview for help authores
- 13 OpenOffice.org Resources
- 14 Issues with images/icons in help files
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
- Set LO to use LibreOffice file dialogs for Save/Open.
- Use item `Set Document Root` in menu `HelpAuthoring`.
- Select the correct directory.
- Look at the property `HelpPrefix` in the file `\user\config\helpauthoring.cfg`. It should have got a dash at the end.
- For a possible fix see https://bugs.documentfoundation.org/show_bug.cgi?id=93580#c4
- Fixed in helpauthoring.oxt version 3.1.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
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
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
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.
- 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
<emph><switchinline"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.
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.
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/Documentation/Extensible_Help (including diagram)
- https://wiki.openoffice.org/wiki/Help_Agent [was removed from LibreOffice, still exists in Apache OpenOffice]
[all visited 2015-09-01]
Further content for OpenOffice.org
- http://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.
[all visited 2015-09-01]
- 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
- a modified main_transform.xsl
- a modified default.css
The files need an update for LibreOffice.
Issues with images/icons in help files
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
unparsed-text. Because of that it is not possible to import the file
- 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.
tdf#51389 LOCALHELP: Pictures in start page missing (edit)
tdf#70276 No graphics nor links in the integrated help
tdf#75636 LOCALHELP: Localised (L10n) images not used from the icon-theme
tdf#75637 LOCALHELP: Images not displayed with newer icon themes → central issue for the problem
tdf#75948 [DE] Missing symbols in OLH for "File - New" help text
tdf#78576 Offline-help (DE): Placeholder "vnd.sun.star." displayed instead of icons
tdf#82149 [closed duplicate] Help viewer shows missing icons as "vnd.sun.*" placeholders rather than taking icons from parent icon themes and links.txt
tdf#88086 Images not displayed in local help (a missing/broken image link icon appears instead)
tdf#90830 The folder res/helpimg is missing in the Tango and Oxygen icon set
tdf#91992 LO50b3: Images are not shown in local Help
tdf#94439 Help: Pictures missing
tdf#94889 Icon problem in Help
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.
tdf#87083 (fixed) 4.4.0.beta2 inline help images horizontally stretched
tdf#89017 (fixed) Help content landing page icons scaled out of proportion in local help installers
tdf#94020 LOCALHELP/WIKIHELP: Large icons should be used
tdf#94871 [HELP] note and warning paragraphs are aligned incorrectly
Interfere with security options
tdf#81091 Images in help not visible if security option is selected (comment 18)
Missing icons in applications
tdf#91565 REPORT BUILDER: Missing insert field icon in Add Field dialog
tdf#93866 ICONS: Parent icon theme links.txt duplicate records not inherited in child themes