[Libreoffice] Embedded parts and wikihelp/HC2

[Sophie Gautier]

Hi Kendy, all,
On 16/12/2010 16:44, Jan Holesovsky wrote:
> 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! :-)

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

For me it is, and I think that every body will the happy with your 
proposal. Thanks a lot :-)
>
> 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 ;)
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 :)

Kind regards
Sophie