Embedded parts and wikihelp/HC2

Hi Kendy,

I've two questions concerning the wikihelp/HC2, there is no emergency for the answer, I know you're busy, but I don't want to forget to ask :wink:

Currently in the HC2 files, pages are composed by a mix of embedded chunks and local strings. We use two files to get the KID of the string, to display the embedded chunks, the .xhp tree and the OS dependent parts in order to do l10n QA on the files.

I've added a screen shot of the result to my page on the wiki [1].

How somebody contributing to the wikihelp will see these embedded parts or OS specific parts. How will he knows that it should not make it to much particular to a certain page because it will appear elsewhere on other pages in the HC2?

Some pages are mostly composed by embedded chunks, if those embedded part are removed, would that mean we will have to duplicate the localization?

Kind regards
Sophie

[1] http://wiki.documentfoundation.org/User_talk:Sophi

Hi Sophie,

I've two questions concerning the wikihelp/HC2, there is no emergency
for the answer, I know you're busy, but I don't want to forget to ask :wink:

We are all busy, I am sure; thank you for the explicit CC:, it is then
much easier to give this the priority it deserves! :slight_smile:

First of all - thank you all for the input on the wikihelp. This is
software, so any [or at least many ;-)] changes are of course possible.
So far, it seems to me that what Martin proposed fits all the [in
alphabetical order] developers, documentation team, and l10n; I mean:

----- 8< -----
I propose you develop a system to have English help editable on wiki but
fully transportable back to the po/xliff system (interchangeable).
All the translations would start from the English po/xliff help files
and decide whether to
a) strictly translate English help (like we Slovenians decided) and keep
working with po/xliff files; the online help would be updated from these
files at least with every minor and major release;
or
b) develop their own help in the wiki and never go back again;
----- 8< -----

To summarize that, the best seems to be that:

- only the English pages will be editable
  - like eg. http://help.libreoffice.org/Common/Save_As
  - but the lang versions, like
    http://help.libreoffice.org/Common/Save_As/cs
    will be _not_ editable

- strings from the English pages will be uploaded to pootle
  - so that you can work the way you are used to

- existing translations will be converted
  - so that the work is not lost, ie. everything that has been
    translated so far has to be translated in the wikihelp version too

- the pootle tranlations will be applied over the English version
  - but if a language team decides that they want to translate directly
    in the wikihelp, their language version will be open for editing
    directly in the wikihelp

How does that sound? If this plan is acceptable for all, I can go
ahead, and start working on this :slight_smile:

Only one problem I can think of is the time; I am not sure if I can get
that 100% before the final release, so - it might happen that the
wikihelp will be English only at the time of 3.3 final, but filed with
the translated versions as soon as the above works (but it is an online
thing, so the deployment can be independent of the release date, there
is still room for improvements). We will have the translated helppacks,
so hopefully it is not an issue.

Currently in the HC2 files, pages are composed by a mix of embedded
chunks and local strings. We use two files to get the KID of the string,
to display the embedded chunks, the .xhp tree and the OS dependent parts
in order to do l10n QA on the files.

I've added a screen shot of the result to my page on the wiki [1].

How somebody contributing to the wikihelp will see these embedded parts
or OS specific parts. How will he knows that it should not make it to
much particular to a certain page because it will appear elsewhere on
other pages in the HC2?

This is a very good question. In the current implementation, I do not
treat embedding in a special way, and just copy the text there directly.

The following is the page you have shown on the screenshot:

http://help.libreoffice.org/Writer/Shortcut_Keys_for_Writer

Ie. the 'Some shortcut ...' text is directly there, not an embedded
string.

If we want to address this, it is of course solvable too; the only
problem might be that for everything that is supposed to be embedded, it
has to have a special page, like Embed:Some_id, an in the text, it would
be used like {{Embed:Some_id}}.

For example, a text like:

file swriter/file1.xhp:
  <paragraph ...><variable ..."something">Something to
embed</variable></paragraph

file swriter/file2.xhp:
  <embed href="...file.xhp#something>

would in the wiki look like:

Page Embed:file1_something
  Something to embed

Page Writer/file1
  {{Embed:file1_something}}

Page Writer/file2
  {{Embed:file1_something}}

Documentation team - is that acceptable for you?

OS specific parts are already solved differently, there is a template
{{System}}, used like {{System|mac=Mac string|win=Windows string|
default=something default}}.

The template page itself does not work yet (ie. always the default
choice is shown), but I'll fix that ASAP.

Some pages are mostly composed by embedded chunks, if those embedded
part are removed, would that mean we will have to duplicate the
localization?

Yes, they would have to be duplicated, if the {{Embed:...}} solution
outlined above is not acceptable (though I hope it is).

Regards,
Kendy

To me this part is very important. Direct translation from English does
not always sound right in some languages. So, I appreciate having this
possibility in the new wikihelp.

Kohei

Hi Kendy, all,

Hi Sophie,

I've two questions concerning the wikihelp/HC2, there is no emergency
for the answer, I know you're busy, but I don't want to forget to ask :wink:

We are all busy, I am sure; thank you for the explicit CC:, it is then
much easier to give this the priority it deserves! :slight_smile:

Thank you :slight_smile:

First of all - thank you all for the input on the wikihelp.

you're welcome, it's an important work for all of us.
  This is

software, so any [or at least many ;-)] changes are of course possible.
So far, it seems to me that what Martin proposed fits all the [in
alphabetical order] developers, documentation team, and l10n; I mean:

----- 8< -----
I propose you develop a system to have English help editable on wiki but
fully transportable back to the po/xliff system (interchangeable).
All the translations would start from the English po/xliff help files
and decide whether to
a) strictly translate English help (like we Slovenians decided) and keep
working with po/xliff files; the online help would be updated from these
files at least with every minor and major release;
or
b) develop their own help in the wiki and never go back again;
----- 8< -----

To summarize that, the best seems to be that:

- only the English pages will be editable
   - like eg. http://help.libreoffice.org/Common/Save_As
   - but the lang versions, like
     http://help.libreoffice.org/Common/Save_As/cs
     will be _not_ editable

ok

- strings from the English pages will be uploaded to pootle
   - so that you can work the way you are used to

ok

- existing translations will be converted
   - so that the work is not lost, ie. everything that has been
     translated so far has to be translated in the wikihelp version too

ok

- the pootle tranlations will be applied over the English version
   - but if a language team decides that they want to translate directly
     in the wikihelp, their language version will be open for editing
     directly in the wikihelp

ok, and I agree with Kohei, this second step is also very important.

How does that sound? If this plan is acceptable for all, I can go
ahead, and start working on this :slight_smile:

For me it is, and I think that every body will the happy with your proposal. Thanks a lot :slight_smile:

Only one problem I can think of is the time; I am not sure if I can get
that 100% before the final release, so - it might happen that the
wikihelp will be English only at the time of 3.3 final, but filed with
the translated versions as soon as the above works (but it is an online
thing, so the deployment can be independent of the release date, there
is still room for improvements). We will have the translated helppacks,
so hopefully it is not an issue.

Yes, it's not an issue, we can take time to test with the l10n team and improve every thing when it's needed. And you don't have to spend your nights on this too :wink:
Also, I think our marketing guys will be happy to make some buzz around this important feature when it will be ready and it may be even better if it's not at the same time of 3.3, what do you think?

Currently in the HC2 files, pages are composed by a mix of embedded
chunks and local strings. We use two files to get the KID of the string,
to display the embedded chunks, the .xhp tree and the OS dependent parts
in order to do l10n QA on the files.

I've added a screen shot of the result to my page on the wiki [1].

How somebody contributing to the wikihelp will see these embedded parts
or OS specific parts. How will he knows that it should not make it to
much particular to a certain page because it will appear elsewhere on
other pages in the HC2?

This is a very good question. In the current implementation, I do not
treat embedding in a special way, and just copy the text there directly.

The following is the page you have shown on the screenshot:

http://help.libreoffice.org/Writer/Shortcut_Keys_for_Writer

Ie. the 'Some shortcut ...' text is directly there, not an embedded
string.

Yes, that's what I've seen.

If we want to address this, it is of course solvable too; the only
problem might be that for everything that is supposed to be embedded, it
has to have a special page, like Embed:Some_id, an in the text, it would
be used like {{Embed:Some_id}}.

For example, a text like:

file swriter/file1.xhp:
   <paragraph ...><variable ..."something">Something to
embed</variable></paragraph

file swriter/file2.xhp:
   <embed href="...file.xhp#something>

would in the wiki look like:

Page Embed:file1_something
   Something to embed

Page Writer/file1
   {{Embed:file1_something}}

Page Writer/file2
   {{Embed:file1_something}}

ok, I understand.

Documentation team - is that acceptable for you?

OS specific parts are already solved differently, there is a template
{{System}}, used like {{System|mac=Mac string|win=Windows string|
default=something default}}.

The template page itself does not work yet (ie. always the default
choice is shown), but I'll fix that ASAP.

Ok, I understand that also.

Some pages are mostly composed by embedded chunks, if those embedded
part are removed, would that mean we will have to duplicate the
localization?

Yes, they would have to be duplicated, if the {{Embed:...}} solution
outlined above is not acceptable (though I hope it is).

Ok, so let see what the doc team will say.
Thanks :slight_smile:

Kind regards
Sophie

Hi Martin,

Jan,

2010/12/16 Jan Holesovsky <kendy@suse.cz <mailto:kendy@suse.cz>>

    Only one problem I can think of is the time; I am not sure if I can get
    that 100% before the final release, so - it might happen that the
    wikihelp will be English only at the time of 3.3 final, but filed with
    the translated versions as soon as the above works (but it is an online
    thing, so the deployment can be independent of the release date, there
    is still room for improvements). We will have the translated helppacks,
    so hopefully it is not an issue.

I think online help must be available in all languages - it is a
stopper, if it isn't. Otherwise the lang teams will not ok the release
thus only the English version will be an official and tested release,
and all the rest will be untested. Think what that means for adoption of
LO in enterprises and government sector. Not good at all. For all other
languages 3.3 seems to be a preview what a LO will look like in 3.4, and
not a full featured version, a kind of LO beta.

This is the wikihelp that will be available only in en_US, HC2 will be available in all language has helppacks. What we call online help is a bit confusing as it was the help files available with the OOo/LO version. Lets speak about HC2 for the local files and wikihelp for the files on the wiki.

    This is a very good question. In the current implementation, I do not
    treat embedding in a special way, and just copy the text there directly.

    The following is the page you have shown on the screenshot:

    http://help.libreoffice.org/Writer/Shortcut_Keys_for_Writer

    Ie. the 'Some shortcut ...' text is directly there, not an embedded
    string.

    If we want to address this, it is of course solvable too; the only
    problem might be that for everything that is supposed to be embedded, it
    has to have a special page, like Embed:Some_id, an in the text, it would
    be used like {{Embed:Some_id}}.

    For example, a text like:

    file swriter/file1.xhp:
    <paragraph ...><variable ..."something">Something to
    embed</variable></paragraph

    file swriter/file2.xhp:
    <embed href="...file.xhp#something>

    would in the wiki look like:

    Page Embed:file1_something
      Something to embed

    Page Writer/file1
      {{Embed:file1_something}}

    Page Writer/file2
      {{Embed:file1_something}}

    Documentation team - is that acceptable for you?

The transport of (English) help from wiki back to xliff/po must get all
the keywords references, links etc. How is that handled? Will the index
in LO offline help work after such a backport from wiki? This is of
major importance. Offline help without index and table of contents etc.
is not usable.

Kendy, why do you have to rush at this online solution for 3.3? I
propose to leave things as with OOo for 3.3, with help packs as separate
downloads if they are too big to be included in the international
package. In the meantime you can get the conversion procedures working
so that no metadata from help gets lost and on the road to 3.4 all the
teams and LO projects decide about the future of LO help system.
What you are driving at is having a non-fully-working solution for 3.3
with already some decision in place at very short notice (and such
decisions mostly lead to headache) and then decide for future. What I
propose is a fully working solution for 3.3 with enough time later to
decide and make a new system working fully for the 3.4 release.

From what I've understand, we will have normal HC2 files aside with 3.3. Only the wikihelp will be in en_US. Then, the wikihelp will be implemented in all languages, but it has not to follow the release cycle. Only the HC2 and the porting from wikihelp to HC2 will have.

Hope this helps.

Kind regards
Sophie

Jan,

Only one problem I can think of is the time; I am not sure if I can get
that 100% before the final release, so - it might happen that the
wikihelp will be English only at the time of 3.3 final, but filed with
the translated versions as soon as the above works (but it is an online
thing, so the deployment can be independent of the release date, there
is still room for improvements). We will have the translated helppacks,
so hopefully it is not an issue.

I think online help must be available in all languages - it is a stopper, if
it isn't. Otherwise the lang teams will not ok the release thus only the
English version will be an official and tested release, and all the rest
will be untested. Think what that means for adoption of LO in enterprises
and government sector. Not good at all. For all other languages 3.3 seems to
be a preview what a LO will look like in 3.4, and not a full featured
version, a kind of LO beta.

This is a very good question. In the current implementation, I do not

treat embedding in a special way, and just copy the text there directly.

The following is the page you have shown on the screenshot:

http://help.libreoffice.org/Writer/Shortcut_Keys_for_Writer

Ie. the 'Some shortcut ...' text is directly there, not an embedded
string.

If we want to address this, it is of course solvable too; the only
problem might be that for everything that is supposed to be embedded, it
has to have a special page, like Embed:Some_id, an in the text, it would
be used like {{Embed:Some_id}}.

For example, a text like:

file swriter/file1.xhp:
<paragraph ...><variable ..."something">Something to
embed</variable></paragraph

file swriter/file2.xhp:
<embed href="...file.xhp#something>

would in the wiki look like:

Page Embed:file1_something
Something to embed

Page Writer/file1
{{Embed:file1_something}}

Page Writer/file2
{{Embed:file1_something}}

Documentation team - is that acceptable for you?

The transport of (English) help from wiki back to xliff/po must get all the
keywords references, links etc. How is that handled? Will the index in LO
offline help work after such a backport from wiki? This is of major
importance. Offline help without index and table of contents etc. is not
usable.

Kendy, why do you have to rush at this online solution for 3.3? I propose to
leave things as with OOo for 3.3, with help packs as separate downloads if
they are too big to be included in the international package. In the
meantime you can get the conversion procedures working so that no metadata
from help gets lost and on the road to 3.4 all the teams and LO projects
decide about the future of LO help system.
What you are driving at is having a non-fully-working solution for 3.3 with
already some decision in place at very short notice (and such decisions
mostly lead to headache) and then decide for future. What I propose is a
fully working solution for 3.3 with enough time later to decide and make a
new system working fully for the 3.4 release.

Lp, m.

Sophie, I understand that. But out of the box, installing the international
package, not being aware that localized help is not included, and setting
interface language to lets say French will render GUI in French. And then
that user will press F1 on an GUI item and get - English wiki help. Is that
OK? How will you tell all French potential users of LO that they MUST
install the HC2 localized help separately, otherwise they will use a
non-approved French version?

Lp, m.

Hi Martin,

> This is the wikihelp that will be available only in en_US, HC2 will be
> available in all language has helppacks. What we call online help is a bit
> confusing as it was the help files available with the OOo/LO version. Lets
> speak about HC2 for the local files and wikihelp for the files on the wiki.
>
Sophie, I understand that. But out of the box, installing the international
package, not being aware that localized help is not included, and setting
interface language to lets say French will render GUI in French. And then
that user will press F1 on an GUI item and get - English wiki help. Is that
OK? How will you tell all French potential users of LO that they MUST
install the HC2 localized help separately, otherwise they will use a
non-approved French version?

We can easily show a suggestion to download a localized version of the
help on each and every page, if the language is not en_US. With your
help (the l10n team), this can be even shown in the native language of
the user, with a direct link to the download location. How does that
sound?

Regards,
Kendy

Hi, Jan,

We can easily show a suggestion to download a localized version of the
help on each and every page, if the language is not en_US. With your
help (the l10n team), this can be even shown in the native language of
the user, with a direct link to the download location. How does that
sound?

While that would also be nice to have, I think it is mandatory to explain
that during installation. And at the end of installation it would be nice to
have a link to download the language pack. At least for Windows and OSX,
that have a GUI installer.

Also installing LO on multiple systems should provide option to install also
the langpacks (I believe that is possible now, but maybe some more
automation should be provided, given that it is two packages that need to be
installed, not just one, the fully localized build, as with OOo).

Your solution is not usable for users in a working environment without
internet access or with limited internet access (some companies/government
agencies limit Internet access for security, procastrination etc. reasons).

Lp, m.

Jan,
another thing, that I already mentioned sometime ago in one of my many many
posts here :), it would be great if these multilang installers would offer
the installer language option - e.g. when starting the installer first the
selection of installation language would pop-up. The installer would then
run in that language and automatically offer GUI and dictionaries of that
language as presets, and offer the appropriate help package download.

I prefer language selection based on user selection and not on the OS
language, because some users have English GUI in OS, but want a localized
LO.

Example: if I am Slovenian, I would select Slovenian language, the installer
GUI would be Slovenian, the defaults for installation would be Slovenian GUI
and Slovenian and English dictionaries. If I would want to manually change
the things to install I would still be able to select and deselect other
languages etc. And at the end of installation I would be warned that help is
only online and that for offline help I must follow the given link to the
Slovenian helppack.

Lp, m.

Hi Martin,

I think online help must be available in all languages - it is a
stopper, if it isn't.

  I agree. On the other hand - if there are bugs in the web help we can
improve the conversion continually to fix them without having to
re-build master and delay the release endlessly, IMHO.

  I imagine Kendy is working hard at this and other problems, and hey -
if anyone else wants to jump into working on the tools with him it
should be do-able. I imagine it is quite possible to setup your own wiki
to play with the translation as of now if people want to help out.

  HTH,

    Michael.

Definitely. I am waiting to see it and give it a good workout and appraisal.

Marc
Marketing Team Member

Hi Martin,

> We can easily show a suggestion to download a localized version of the
> help on each and every page, if the language is not en_US. With your
> help (the l10n team), this can be even shown in the native language of
> the user, with a direct link to the download location. How does that
> sound?

While that would also be nice to have, I think it is mandatory to explain
that during installation. And at the end of installation it would be nice to
have a link to download the language pack. At least for Windows and OSX,
that have a GUI installer.

I've just seen the test installation of the future LibreOffice site; I
think it very much fulfills what you are proposing. It is not at the
end of the installation, but at the time you are downloading
LibreOffice:

http://test.libreoffice.org/download/

If you choose Linux version, you can choose the language version you
need, as an additional download. I suppose the same will be implemented
with the Windows version after the RC2 that will have the langpacks.

I hope this resolves even this concern :slight_smile:

Regards,
Kendy

Hi Sophie, all,

> How does that sound? If this plan is acceptable for all, I can go
> ahead, and start working on this :slight_smile:

For me it is, and I think that every body will the happy with your
proposal. Thanks a lot :slight_smile:

I have just updated the wiki accordingly:

http://wiki.documentfoundation.org/Development/Wikihelp

Please double-check, I hope I did not forget anything :slight_smile:

Regards,
Kendy

Hi David, all,

> How somebody contributing to the wikihelp will see these embedded parts
> or OS specific parts. How will he knows that it should not make it to
> much particular to a certain page because it will appear elsewhere on
> other pages in the HC2?

This is a very good question. In the current implementation, I do not
treat embedding in a special way, and just copy the text there directly.

The following is the page you have shown on the screenshot:

http://help.libreoffice.org/Writer/Shortcut_Keys_for_Writer

Ie. the 'Some shortcut ...' text is directly there, not an embedded
string.

If we want to address this, it is of course solvable too; the only
problem might be that for everything that is supposed to be embedded, it
has to have a special page, like Embed:Some_id, an in the text, it would
be used like {{Embed:Some_id}}.

For example, a text like:

file swriter/file1.xhp:
  <paragraph ...><variable ..."something">Something to
embed</variable></paragraph

file swriter/file2.xhp:
  <embed href="...file.xhp#something>

would in the wiki look like:

Page Embed:file1_something
  Something to embed

Page Writer/file1
  {{Embed:file1_something}}

Page Writer/file2
  {{Embed:file1_something}}

Documentation team - is that acceptable for you?

I am afraid this got lost in the large mail :slight_smile: - do you think this
would work for you [I think it might work pretty well, but want to
double-check before I go ahead :-)]

Thank you,
Kendy

Hi Jan, resending for all to see plus adding a thought at the end:

I've just seen the test installation of the future LibreOffice site; I
think it very much fulfills what you are proposing. It is not at the
end of the installation, but at the time you are downloading
LibreOffice:

http://test.libreoffice.org/download/

If you choose Linux version, you can choose the language version you
need, as an additional download. I suppose the same will be implemented
with the Windows version after the RC2 that will have the langpacks.

I hope this resolves even this concern :slight_smile:

I don't think this is ok for GUI installers. I think users should be warned
there is no help included. The person that downloads the suite might not be
the same person that installs the package - so this needs to be known to the
person installing, not the one downloading (or to both of them).

Also, sometimes these office suites are distributed via CD's with other OSS
software or included in an OS, so there is no download page to see this
warning. It should be in the installation procedure somewhere. Even the
Linux installer could write it out in the console - help is not included,
for further info see this and that webpage.

My 2 cents,
m.

On the new features page at test site I think this should be changed:
- Made Help system available via the WikiHelp;
into:
Made Help system also available via the WikiHelp;

Having Help system just available via the WikiHelp is not a feature but a
stolen feature.

What's the news on the localization of LICENSE.odt - as I pointed out the
first part of the document (preamble) must be localized for all languages or
made part of a dialogue and then with a link the English license text opens,
that must not be localized.

Lp, m.

Hi Kendy:

Re: Open Questions on this particular page.

I agree that the editing rights should be open to only certain groups. As Wikihelp is destined to be an integral part of the LibreOffice suite, it should be held in protective mode from possible wrong-doers. Keeping it open would be the same as keeping any of the development code open for anyone to modify. We would not want any unwanted script to appear in code nor our help files.

I would feel better if there were some kind of workflow attached to the Wikihelp approval process whereby it would be treated just as any other document just as in the process used with the documentation team.

I think that it is fine to have it open for now but once it has been included in the final version on LibreOffice, it should be protected from outside manipulation.

Marc