Ease maintenance of build-in help

[Regina Henschel]

Hi Jan,

Jan Holesovsky schrieb:
> Hi Regina,
>
> Regina Henschel píše v Ne 02. 08. 2015 v 19:06 +0200:
>
>> I have started a new thread so that the problem is not hidden inside
>> other threads or in private mails.
>>
>> First, is there consensus, that the current build-in help will be retained?
>
> Thank you for your thoughts on this topic - and sorry for my late reply.

I'm late too. That happens for persons, who can only contribute in their 
spare time.

> In the ideal world, I'd like the help be handled like this:
>
> * wikihelp is the authoritative source, with appropriate approval system
>    etc. [easy for casual contributors to fix stuff in the help, but safe
>    & easy to keep the standards]
>
> * existing translations converted so that there is no additional work
>    for the translators when converting to wikihelp (once)

A workflow is needed for new content and for new languages. When the 
built-in help is automatically generated, the translated Wikihelp needs 
to follow a strong structure.

>
> * built-in help is generated from the wikihelp + translatios, and shown
>    in the browser (JavaScript used for the indexing & search), instead of
>    the home-grown help system

The part "extended tips" is missing in this scenario.

>
> Currently we have the following pieces of the puzzle:
>
> * ability to convert .xhp's -> wiki format
> * ability to convert wiki format -> html
>
> The indexing IIRC is not retained at the moment, and also the JavaScript
> indexing is not implemented; so the switch is impossible in the current
> state.  I am unable to work on this, but would be extremely happy to
> mentor anybody who would be willing to help.

The Contents part (that what is generated from the *.tree files) is 
missing too. In addition the current Wikihelp misses reducing the UI, 
and the global search of the Wiki is no replacement for the search 
features of the built-in help.

>
> For the wikihelp itself, it might be possible to use the Mozilla's
> Kitsune (the engine behind support.mozilla.org):
>
> https://github.com/mozilla/kitsune
>
> but that needs checking - whether it is better for our purposes than the
> 'normal' mediawiki or not.
>

I don't know about it; no comment.

>> If not, then the following ideas are useless and starting would be waste
>> of time. In such case, please stop me immediately.
>
> As you can see - the "ideal world" vision is long-term :-)  So let's not
> allow perfect be enemy of the good, and improve the current workflow in
> the meantime.

OK, let's start. I've put this as topic on 
https://wiki.documentfoundation.org/Hackfest/Hamburg2015 already. Will 
anyone be there and like to work on the problem with me?

>
>> I collect here some ideas from some threads and mails:
>>
>> A
>> Authors of help texts are allowed to start in ODF to discuss and
>> finalize the content and appearance of the intended help texts. There
>> should be a place in the repository to store such files. This way
>> authors did not need deep knowledge of the technical structure of
>> helpcontent2. The person who integrates the help texts into the build-in
>> help need not be the content author.
>
> That's perfectly possible.  Let's just use Flat ODF (.fodt) as the
> fileformat, and store the file next to the appropriate .xhp in the help
> repository.
>
> It would be still good to use the helpauthoring.oxt when generating the
> odt too, to use the appropriate fields, and to use the same template as
> the start.

I have a person in mind, who know nothing about the structure of the 
help. But your are right, that using the helpauthoring template would be 
helpful, and that is possible even for a person with no knowledge about 
xhp and help structure.

>
>> B
>> Improve the extension "HelpAuthoring" and fix its bugs. The extension
>> might be principally not suitable to generate the final version of a
>> help file, but it is useful as start, because it sets a lot of the
>> needed XML-elements and attributes automatically. The result might still
>> needs additions and corrections, but that is less work, than writing all
>> from scratch. Even if someone do not know all details about the help, he
>> can start and deliver a file, which other then can improve and integrate.
>
> Definitely.  The xslt filter that is responsible for converting fodt <->
> xhp is actually trivial, I'm happy to fix bugs there when you send me
> the original .(f)odt, resulting .xhp (generated by the 'broken'
> helpauthoring.oxt), and the fixed .xhp (that is modified how it is
> supposed to look like).

Some problems are not in the transformation but in the Basic code.

I prefer to use Bugzilla and so make work visible. Shall I put you in CC 
in Bugzilla for such issues?

>
>> C
>> Provide a development section about the build-in help to the Wiki. It
>> should not only contain a tutorial about help authoring but in addition
>> a description how the current help works at all from a developer view,
>> and how it is actually structured.
>
> I attempted that here:
>
> https://wiki.documentfoundation.org/Documentation/Help
>
> I'd like this page to become a kind of "do this and that, and you'll
> have a minimal useful help for your new feature" for the developers -
> ie. assuming that the person knows git etc.  Improvements most
> appreciated!
>
>> We can start with the document "OOo2HelpAuthoring.pdf". The content has
>> to be revised and adapted and extended. For example the .mk files are
>> different than described in that document and the document describes the
>> possibilities of the help format, but not all details of the actual
>> realization.
>
> There is also a more verbose
>
> https://wiki.documentfoundation.org/HelpContent

Both pages are about the extension. I mean things beyond that, e.g. 
Describe the way from .xhp to .sdf.
How does extended tips work?
What is the format of the files in the installed LibreOffice?
What does a "help compiler" and where is it?
What does the "help viewer" and where is it?
How are the .xhp files transformed to html on user side?
What kind of placeholder exists?
What item attributes actually exist?
How is context sensitivity achieved?
How to integrate a new help file and where?
What is the reason of the kind of numbering of the help files?
...

>
> that I think could be this "stripped down OOo2HelpAuthoring.pdf".  We
> should probably move it to Documentation/HelpContent so that it is in
> the right section of the wiki (?)

There should be a more general predefined frame. Perhaps with dummy 
pages for the wished content? (Something for Hackfest too?)

>
>> Having it in the Wiki keeps such knowledge available, when a help expert
>> leaves the community. It can be adapted to future developments. Experts
>> of different areas can better work together to collect help knowledge in
>> one place, for example experts for "Help to Wiki" and experts for
>> "translating help".
>>
>> D
>> It would ease work, when there would be a tool, that shows a .xhp file
>> the same way as it it shown in the help viewer, so that it is not needed
>> to build helpcontent2 every time when you test some changes in your way
>> to the final version. And authors who use "HelpAuthoring" need not be
>> able to build LibreOffice.
>
> We have the xhp -> wiki -> html at least ;-)  So showing in the browser
> would be possible, and could help fine-tuning the long term goal of
> wikihelp; but probably it's not exactly what you had in mind...

I think of something directly in Writer, when using the extension. So 
that an author can see e.g. whether a table has the correct structure 
and work well for small window sizes, whether icons and pictures are at 
the correct place and have a suitable size, whether text markup is 
correct. Not as odt document, but just as shown in the help viewer or if 
you like in any browser, using the original "default.css".
At least there should be an easy way to hide/show the fields.

Kind regards
Regina