[Libreoffice] Embedded parts and wikihelp/HC2

[Jan Holesovsky]

Hi Sophie,

On 2010-12-16 at 07:38 +0300, Sophie Gautier wrote:

> 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 ;)

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! :-)

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 :-)

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