Discussion:
Ease maintenance of build-in help
(too old to reply)
Regina Henschel
2015-08-02 17:06:51 UTC
Permalink
Hi all,

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?

If not, then the following ideas are useless and starting would be waste
of time. In such case, please stop me immediately.

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.

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.

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

Kind regards
Regina
Sophie
2015-08-03 09:11:44 UTC
Permalink
Hi Regina,
Post by Regina Henschel
Hi all,
I have started a new thread so that the problem is not hidden inside
other threads or in private mails.
Thanks a lot for that
Post by Regina Henschel
First, is there consensus, that the current build-in help will be retained?
Yes, it's the only documentation available for the different languages
we offer to our users and in some countries, you are not allowed to
deliver a software without translated build-in help.
Post by Regina Henschel
If not, then the following ideas are useless and starting would be waste
of time. In such case, please stop me immediately.
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.
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.
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.
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.
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.
Again thanks for the details. I do not have time to participate much at
the moment, but when the 5.0 will be out and the LibOCon organization
more advanced, I would very much like to help where I can.

Kind regards
Sophie
--
Sophie Gautier ***@documentfoundation.org
GSM: +33683901545
IRC: sophi
Co-founder - Release coordinator
The Document Foundation
James E Lang
2015-08-02 18:32:25 UTC
Permalink
Hi Regina and all the rest.

First of all, I'm not (yet at least) a developer. That said I'll toss in my thoughts because I AM very concerned about the quality and accuracy of LibreOffice's built-in help.

[May I suggest that all responses to this thread should utilize the Reply All mechanism but stay on topic. Private (off list) replies are not very helpful in a discussion like this.]

Regarding concensus that the current built-in help will be retained: In my opinion something like it MUST exist. As frustrating as the current verbiage is, to toss it out entirely would be far worse. Rather, let's incrementally improve it.

A
This seems to be common sense. (+1)

B
I know nothing about this extension but if it makes it easier for "Joe Sixpack" (a run of the mill user of LibreOffice) to productively contribute to the quality of the built-in help then I'm all for it. (+1)

C
Most emphatically, yes. (+3) To improve its visibility to the user community someone should add a link to this wiki in the top level Help menu (something like "How to contribute to this Help")

D
Way to go! Those who contribute any documentation, particularly in the early stages, need not be programmers who are battle scarred from waging the battle to build the software. (+2)
--
Jim

-----Original Message-----
From: Regina Henschel <***@t-online.de>
To: LO dev fdo <***@lists.freedesktop.org>
Cc: LO documentation <***@global.libreoffice.org>
Sent: Sun, 02 Aug 2015 10:07
Subject: Ease maintenance of build-in help

Hi all,

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?

If not, then the following ideas are useless and starting would be waste
of time. In such case, please stop me immediately.

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.

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.

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

Kind regards
Regina
Thorsten Behrens
2015-08-04 15:06:18 UTC
Permalink
I have started a new thread so that the problem is not hidden inside other
threads or in private mails.
Thanks a lot!
First, is there consensus, that the current build-in help will be retained?
I think - the plan to go all-in for wiki-based help is on hold, until
someone (Kendy?) has cycles to push it further.

Would perhaps be good to extend
https://wiki.documentfoundation.org/Development/Wikihelp with some
status/plans/more details on what is missing where.
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.
Makes sense. For storing those WIP versions in the repo, I'm not sure
that gives us much. Perhaps collaboration via owncloud or wiki works
better there?
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.
Having a list of EasyHacks / Bugs somewhere would be a great
start. And a possible topic for one of the upcoming hackfests.
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.
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.
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".
Quite.
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.
Sounds like another obvious Easy/HardHack idea for a Hackfest? ;)

Cheers,

-- Thorsten
Regina Henschel
2015-08-04 23:45:03 UTC
Permalink
Hi Thorsten,
Post by Thorsten Behrens
I have started a new thread so that the problem is not hidden inside other
threads or in private mails.
Thanks a lot!
First, is there consensus, that the current build-in help will be retained?
I think - the plan to go all-in for wiki-based help is on hold, until
someone (Kendy?) has cycles to push it further.
Would perhaps be good to extend
https://wiki.documentfoundation.org/Development/Wikihelp with some
status/plans/more details on what is missing where.
Mmh. Ideally that would mean, that the ideas below are obsolete. But it
seems to me, that the help is in a bad state currently: The Wikihelp is
not yet authoritative and cannot be edited and has not all needed
features, and the built-in help is difficult to maintain and is not
adapted to get content from the Wikihelp and still needs to provide
those features, that the Wikihelp lacks, especially the extended tips.

I have added some comments to the linked page.
Post by Thorsten Behrens
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.
Makes sense. For storing those WIP versions in the repo, I'm not sure
that gives us much. Perhaps collaboration via owncloud or wiki works
better there?
Yes, it would have to be discussed, where such documents to store. The
central point is, to allow a format, that is well known; so that authors
need not learn any other authoring tool.
Post by Thorsten Behrens
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.
Having a list of EasyHacks / Bugs somewhere would be a great
start. And a possible topic for one of the upcoming hackfests.
[..}
Post by Thorsten Behrens
Sounds like another obvious Easy/HardHack idea for a Hackfest? ;)
Yes I agree, "Help Authoring" is a good topic for a Hackfest.

Kind regards
Regina
t***@aim.com
2015-08-04 17:53:40 UTC
Permalink
Hi guyz,

Why don't you use wiki as authoring tool, convert that to XML, then you have a source that can be converted to anything. You put the wiki into version control (git/subversion), power authors can edit the text files with ease in an editor of their choice (wiki syntax is easy to learn), others can use their browser.

‎Everybody can contribute to the doc in an easy way, wikipedia-style documentation.

Regards,

HP

Sent from my BlackBerry 10 smartphone.
  Original Message  
From: Thorsten Behrens
Sent: Tuesday, 4 August 2015 17:11
To: Regina Henschel
Cc: LO dev fdo; LO documentation; Jan Holesovsky
Subject: [libreoffice-documentation] Re: Ease maintenance of build-in help
I have started a new thread so that the problem is not hidden inside other
threads or in private mails.
Thanks a lot!
First, is there consensus, that the current build-in help will be retained?
I think - the plan to go all-in for wiki-based help is on hold, until
someone (Kendy?) has cycles to push it further.

Would perhaps be good to extend
https://wiki.documentfoundation.org/Development/Wikihelp with some
status/plans/more details on what is missing where.
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.
Makes sense. For storing those WIP versions in the repo, I'm not sure
that gives us much. Perhaps collaboration via owncloud or wiki works
better there?
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.
Having a list of EasyHacks / Bugs somewhere would be a great
start. And a possible topic for one of the upcoming hackfests.
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.
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.
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".
Quite.
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.
Sounds like another obvious Easy/HardHack idea for a Hackfest? ;)

Cheers,

-- Thorsten
--
To unsubscribe e-mail to: documentation+***@global.libreoffice.org
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette
List archive: http://listarchives.libreoffice.org/global/documentation/
All messages sent to this list will be publicly archived and cannot be deleted
Jan Holesovsky
2015-08-12 05:50:53 UTC
Permalink
Hi Thorsten,
Post by Thorsten Behrens
Post by Regina Henschel
First, is there consensus, that the current build-in help will be retained?
I think - the plan to go all-in for wiki-based help is on hold, until
someone (Kendy?) has cycles to push it further.
Added some details in the other mail :-)
Post by Thorsten Behrens
Post by Regina Henschel
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.
Makes sense. For storing those WIP versions in the repo, I'm not sure
that gives us much. Perhaps collaboration via owncloud or wiki works
better there?
I'm not much a friend of having stuff on many places, so I'd prefer just
a .fodt next to the appropriate .xhp, and be done with that. But of
course - what fits the documentation authors best...

All the best,
Kendy
Jan Holesovsky
2015-08-12 05:44:01 UTC
Permalink
Hi Regina,
Post by Regina Henschel
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.
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)

* 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

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.

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.
Post by Regina Henschel
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.
Post by Regina Henschel
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.
Post by Regina Henschel
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).
Post by Regina Henschel
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!
Post by Regina Henschel
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

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 (?)
Post by Regina Henschel
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...

All the best,
Kendy
Jan Holesovsky
2015-08-13 15:52:40 UTC
Permalink
Hi Regina,
Post by Jan Holesovsky
Post by Regina Henschel
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.
I forgot to mention - it is easily possible to convert such .fodt's
to .xhp offline, without using LibreOffice. You need only xsltproc and
the filter from dev-tools:

[git clone git://anongit.freedesktop.org/libreoffice/contrib/dev-tools]

cd dev-tools
xsltproc helpauthoring/filter/soffice2xmlhelp.xsl helpfile.fodt > helpfile.xhp

All the best,
Kendy
Regina Henschel
2015-08-15 20:30:50 UTC
Permalink
Hi Jan,
Post by Sophie
Hi Regina,
Post by Regina Henschel
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.
Post by Sophie
* 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.
Post by Sophie
* 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.
Post by Sophie
* 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.
Post by Sophie
For the wikihelp itself, it might be possible to use the Mozilla's
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.
Post by Sophie
Post by Regina Henschel
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?
Post by Sophie
Post by Regina Henschel
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.
Post by Sophie
Post by Regina Henschel
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?
Post by Sophie
Post by Regina Henschel
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.
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!
Post by Regina Henschel
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?
...
Post by Sophie
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?)
Post by Sophie
Post by Regina Henschel
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
Markus Mohrhard
2015-08-15 22:11:26 UTC
Permalink
Hey,

I'll take the freedom to just answer some of the wikihelp related points.
Post by Regina Henschel
Hi Jan,
Post by Sophie
Hi Regina,
I have started a new thread so that the problem is not hidden inside
Post by Regina Henschel
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.
Post by Sophie
* 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.
Post by Sophie
* 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.
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.
Post by Regina Henschel
Post by Sophie
* 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.
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.
Post by Regina Henschel
Post by Sophie
For the wikihelp itself, it might be possible to use the Mozilla's
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.
Markus

Regina Henschel
2015-08-15 18:26:18 UTC
Permalink
Hi Oliver,
Hi Regina, all
Post by Regina Henschel
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.
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.
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".
Do we have a tool to convert such pdf to mediawiki? I found a good one
to convert to html5 but all my attemps to get mediawiki turns out to be
very manual... If we can get the original odf/swx, that will be nice to
try with our internal mediawiki export.
Also, are we allowed to upload this document and edit it in a wiki? It
is under Public document License and by section 2 of PDL, it looks like
we can... but IANAL.
http://www.openoffice.org/licenses/PDL.html
I think too, that providing the original document for download is
allowed and we should do it as reference. But I think, we should not try
to use it directly in the Wiki, because the license has a strict rule,
how to handle information about authors which can easily be broken when
free Wiki editing is possible. In addition this rules make it difficult
to arrange the content on different pages.

I think, we need to newly write the content.

Kind regards
Regina
Continue reading on narkive:
Loading...