User:Regina/HelpAuthoringDashboard

From The Document Foundation Wiki
Jump to: navigation, search

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

  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.
    - For a possible fix see https://bugs.documentfoundation.org/show_bug.cgi?id=93580#c4
    - Fixed in helpauthoring.oxt version 3.1.1
  5. 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

<emph><switchinline ...><caseinline...>foo</caseinline><defaultinline>bar</defaultinline></sitchinline></emph>

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

<switchinline ...><caseinline...><emph>foo</emph></caseinline><defaultinline><emph>bar</emph></defaultinline></sitchinline>

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

<emph><switchinline ...></emph><emph><caseinline...></emph><emph>foo</emph><emph></caseinline></emph><emph><defaultinline></emph><emph>bar</emph><emph></defaultinline></emph><emph></sitchinline></emph>

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 <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.

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.

OpenOffice.org Resources

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]

Further content for OpenOffice.org

[all visited 2015-09-01]

[visited 2015-09-11]

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.

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 links.txt while using main_transform.xsl.
  • 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

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.

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