Can I help?

Hi Peter,

ptoye schrieb:

Sorry, Regina, I was referring to the link about Building on Windows. I found
the help files, but rather oddly the Base help files don't seem to be there,
and it's one of those that I need to edit! There's a folder for almost every
other LO application except Base. I'm looking in the
libreoffice-5.1.0.0.alpha1\helpcontent2\source\text folder, which I assume
is correct.

That is correct, but most of the file names are build of numbers and it is hard to identify the relevant file. You can use a portion of the help page text and use a tool to search in files. Or you use the file I have attached. It will help you to identify which file is currently shown in the help viewer.

How to use it:
Close LibreOffice and go to the installation folder of your LibreOffice. There should be a folder "help". Open it. You should see a file 'main_transform.xsl'. Rename this file for example to 'main_tranform.xsl.orig', so that you can easily revert the change. Then put the attached file there. When you now start LibreOffice and open the help, you should see a header with the file name, for example:

FOR DEBUGGING ONLY
File name: /text/shared/main0108.xhp

Of cause, for you it will not be 'shared/main0108.xhp' but it will be the file name, which belongs to the page, you are currently viewing in the help.

That way it should be easy for you, to identify the path to the file, which holds the text content of the help page you are currently looking at.

[The change I have made belongs to a couple of changes, which was used some years ago in OpenOffice to ease the work of translators. https://issues.apache.org/ooo/show_bug.cgi?id=56321]

Kind regards
Regina

Hi Peter,

I notice just, that the attachment was stripped. May I sent you the file directly?

Kind regards
Regina

Regina,

Thanks. I don't have a Dropbox account, but could probably set one up fairly quickly. Or can you send it directly from your own email account - I promise not to put it in my address book. Send it to lo@ptoye.com.

Best regards,

Peter
mailto:lo@ptoye.com
www.ptoye.com

Thanks Regina - I got it and installed it. I've now amended the relevant help
page. Do I upload the whole page here, or just the bits I changed? Or send
it somewhere else?

Hi Peter,

ptoye schrieb:

Thanks Regina - I got it and installed it. I've now amended the relevant help
page. Do I upload the whole page here, or just the bits I changed? Or send
it somewhere else?

This list strips attachments, therefore you cannot attach it here.

LibreOffice uses its Bugzilla to track bugs, enhancements and feature requests. For how to use Bugzilla see https://wiki.documentfoundation.org/QA/BugReport#Submitting_a_bug

If you do not have a Bugzilla account yet, you need to create one.
https://bugs.documentfoundation.org/createaccount.cgi

With using Bugzilla and an account there, your changes get the correct license automatically.

"Product" is of cause LibreOffice.
For changes in the help pages use the component "Documentation".

I think it is better to attach the whole file. That way others can generate a diff file, which is needed in the further work flow.

Look, whether a bug exists, that already describe the problem. If yes, then attach the changed file there.

If no bug exists, create a new report. When creating a new report the form will have a button "Add an attachment". Use that to attach the changed file. Do not forget to describe, why the current version of the help page is wrong.

Kind regards
Regina

Regina,

Thanks Regina. I've already noted this as a bug so I'll attach it there. Thanks ever so much for your help and patience with a (LO documentation) beginner.

Best regards,

Peter
mailto:lo@ptoye.com
www.ptoye.com

I've uploaded it to the bugzilla site. Thanks for your help.

Here it is - I think.

02010100.xhp
<http://nabble.documentfoundation.org/file/n4167017/02010100.xhp>

Hi Peter,

Your changes look very good. It really begins to look more professional and
easier to read and translate. Thank you a lot for your contribution. I can
prepare the patch in the nearest future.

I have only a few proposals.
We can not use a reference to an application of a competitive office suite like
MS Access. In the official Help this looks very strange. If we assume that a
human can have difficulties in learning LibreOffice from habits to work with
another popular office application, we need to tell about differences, but
without using reference to this application. LibreOffice is not a fork of MSO.
There are many other office suites as GoogleDrive, GNOME Office, Calligra Suite
etc. And we should not make a comparative table out of the Help.
I think that the sentence “For designers familiar with Access, the prompt is
more restricted as it cannot contain spaces or reserved characters.” needs
changing.

A mention of a user does not let the Help to look professional. In my opinion,
this can be done for a Guide or FAQ, but we need to avoid it, and to focus on
a functional description.

The last, for me “designers of a database” looks strange. I am used to see
“developers of a database”. I am not an English native speaker, and I can not
be sure, but when I get the order on a database, usually I am called
“developer”. I really don't know what we need to use in this case, just to
draw your attention.

What do you think about these?

Best regards,
Lera

Hi Regina, all,

Regina Henschel píše v St 18. 11. 2015 v 21:32 +0100:

most of the file names are build of numbers and it
is hard to identify the relevant file.

That's indeed true :slight_smile:

I wonder - would a large scale rename to something more readable (like
eg. filename constructed from the <title> tag) be more appreciated by
people editing help?

L10n people - any blockers from the tooling point of view that hinder
that, please? Would it mean that the .po files have to be renamed too,
and if yes, it is possible to do that somehow automatically?

All the best,
Kendy

.po files are named after directories, not after files. In .po files
file names are there in #: comments and in msgctx fields. It is
possible to automatically replace file names in git and in Pootle, but
this can cause disruption for translators who work offline, and
translation memories have to be regenerated.

Regards,
Andras

Hi Lera,

Thanks for your comments. As a first-time producer of LO documentation I wasn't sure about the MS Office reference. I put it in as many years ago I used Office, and found that the LO syntax rules for parameter names/prompts a bit confusing when I tried to put some spaces in. But I'm 100% happy for you to remove that paragraph. I realise that LO is nothing whatsoever to do with Office!

"Designer/developer". No problem with changing it. Your wording is better. I should have thought of it.

"User". We need some way to distinguish the person who is using the database from the person developing it. After all, the concept of the parameter query was designed to allow the person using the database to input parameter values. Do you have a better word? Maybe recast the sentences using it to say something like "at run-time" (which is in the first sentence. If you prefer that I'll send a revised version in, but I think it will be difficult not to mention the fact that it's a human being that inputs the parameter value. I notice that the original version had "you" - whoever that might be - which strikes me as even less professional.

There's also the problem of the paragraph which I didn't understand. I think that what the original author was trying to say was that parameter queries are commonly used in subforms to restrict the records to be displayed. Is that your impression? If so, I can rewrite it. It also should be moved to the section on Parameter queries - it's nothing to do with input.

Your English is better than my Russian!

Best regards,

Peter
mailto:lo@ptoye.com
www.ptoye.com

Please, once more, do not do any "l'art pour l'art"-istic changes that
might cause any kind of trouble to localizers.

There are many more things to invest time and will in first - to write
missing help content, to edit the help content, to make
wiki-served-help fully localizable, to have manuals (getting started
guides) up-to-date etc.

Most localizers localize from Pootle and I am sure that po files there
could be given additional description what part of UI or help they
cover, if really someone feels lost.

Lp, m.

Hi Martin,

Martin Srebotnjak píše v Út 24. 11. 2015 v 15:54 +0100:

Please, once more, do not do any "l'art pour l'art"-istic changes that
might cause any kind of trouble to localizers.

There are many more things to invest time and will in first - to write
missing help content, to edit the help content, to make
wiki-served-help fully localizable, to have manuals (getting started
guides) up-to-date etc.

Exactly! And to be able to do so, we need to lower the entry barrier,
so that more people can write the help content, update the manuals, etc.

We have just seen a guy interested in editing help, and this was one of
his struggles there - that he just couldn't find the help file he needs
to edit. Asking him to grep all the main0123.xhp files (and alike) is
just as nice as telling him "go away, we don't want you" :frowning:

That's why I am interested to learn what are the technical & workflow
difficulties to make the barrier lower, and what is the impact on the
localizers.

We need to do changes to be more open for documentation contributions,
that's something we just cannot avoid, otherwise our help will be
completely outdated soon. So I'm asking if (and what) we can do in a
way that causes no or only minimal trouble.

Most localizers localize from Pootle and I am sure that po files there
could be given additional description what part of UI or help they
cover, if really someone feels lost.

"Most localizers localize from Pootle" together with:

> It is
> possible to automatically replace file names in git and in Pootle, but
> this can cause disruption for translators who work offline, and
> translation memories have to be regenerated.

actually makes me think that only a small fraction of translators would
be actually disrupted, because for those using Pootle, it would be
transparent. So did I misunderstand?

Thank you for your help!

All the best,
Kendy

Probably Slovenian would be actually disrupted, and other "offline"
localization teams, I do not have a list.

Lp, m.

Þann þri 24.nóv 2015 15:35, skrifaði Martin Srebotnjak:

actually makes me think that only a small fraction of translators would
be actually disrupted, because for those using Pootle, it would be
transparent. So did I misunderstand?

Probably Slovenian would be actually disrupted, and other "offline"
localization teams, I do not have a list.

Lp, m.

Martin, I prefer translating offline, and honestly I fail to see too much of a problem if the helpfiles were renamed from 01.po, 02.po to something more meaningful. And if comments and msgctx fields are to be changed - why not...

(I do regenerate my translation memories regularly)

Sveinn í Felli

Hi Jan,

I think that you are writing about me. But I should point out that Sophi and Regina here were extremely helpful and showed me the main_transform file which puts the file name and path at the head of the text. Then I found the file I wanted immediately.

I agree that meaningful file names might help - but in which language? Even US and UK English may differ. And I've no idea what the Czech for "query" is!

An even higher barrier is that my system is based on Windows, and most of the tools used here are Unix-based - you mention grep. There are almost certainly Windows equivalents, but they take a bit of finding and don't always work too well.

I appreciate your views, and your support for me, but I have to agree with Martin.

Best regards,

Peter
mailto:lo@ptoye.com
www.ptoye.com

Sveinn,

I am not sure we are talking about the same thing or that I understand
this correctly.

They change the names of the help files (i.e. calc/01.po is now
calcsfirsthelpfilewithhelpaboutfunctions.po). For the migration
process they become new po files.

The pomigrate2 script takes the translation memory, but it was
generated from the old files (like the old calc/01.po file) with
different msgctx and comment fields etc. So even if all strings in the
renamed file are actually the same as in 01.po , they will become
fuzzy strings, right?

So for calc/01.po that is like 8000 strings, fuzzy strings. And since
we translators will not know if there is at least one changed or
updated string in there, we will have to go manually through all those
8000 strings, reading and checking and ultimately 8000 times clicking
it is not a fuzzy but an ok translation.

Well, if that is done in all help files, it means 26000 reviewed
strings with 26000 clicks that these strings are just fine.

Am I wrong?

100 localization teams doing those 26000 clicks would mean like
2.600.000 reviewed strings ...

I hope I am wrong.

Lp, m.

Hi Jan,

Jan Holesovsky schrieb:

Hi Regina, all,

Regina Henschel píše v St 18. 11. 2015 v 21:32 +0100:

most of the file names are build of numbers and it
is hard to identify the relevant file.

That's indeed true :slight_smile:

I wonder - would a large scale rename to something more readable (like
eg. filename constructed from the <title> tag) be more appreciated by
people editing help?

If you need the file name of the help page you are currently viewing, then a little change in the main_transform.xsl is needed to show the actually path.

If you need the help page but only know UI strings or the uno command, then a search is needed anyway, because of embedding.

You need no "grep", if you work on Windows, but OpenGrok will be sufficient for searching now and then. And for a local copy of the help files, modern editors have a tool for searching in files.

I think, renaming is not needed and the effort is far too big.

We can consider to document in the Wiki, how to change the main_transform.xsl file to show the file path.

Kind regards
Regina

Hi Peter,

"User". We need some way to distinguish the person who is using the database
from the person developing it. After all, the concept of the parameter
query was designed to allow the person using the database to input
parameter values. Do you have a better word? Maybe recast the sentences
using it to say something like "at run-time" (which is in the first
sentence. If you prefer that I'll send a revised version in, but I think it
will be difficult not to mention the fact that it's a human being that
inputs the parameter value. I notice that the original version had "you" -
whoever that might be - which strikes me as even less professional.

I agree with you. Combination of words such as "you must" and "you can" must
not be used in the Help.
I have read again, and I think that I interpreted a paragraph "The user can
use the SQL wild-card characters..." wrong. You are right. This paragraph
needs it.

There's also the problem of the paragraph which I didn't understand. I think
that what the original author was trying to say was that parameter queries
are commonly used in subforms to restrict the records to be displayed. Is
that your impression? If so, I can rewrite it. It also should be moved to
the section on Parameter queries - it's nothing to do with input.

Do you say about this "Parameter queries are also used for subforms, since
they work exclusively with queries for which the values to be invoked are read
internally from a variable."?
I think that it needs to be moved in the Parametr query section.

Best regards,
Lera