Can I help?

Hi Peter,

Thanks Sophie. I've looked at the links you sent (some I'd already be given
by other people). It seems rather complicated in that the commands to set up
access to the git system all seem to refer to Unix and I run Windows. I've
never used git before so I hope I don't have to learn a completely new
language just to edit one file. Also I don't have an OpenID account anywhere
as far as I know - all rather discouraging!

No, no, no :slight_smile: what you can do instead is writing your text using the
help extension and then leave it on the issue, other will push it to
git. And then later we can explain you how to go further, no need to
learn everything at once.
Does it seems complicated for you to install the help extension? Lets
begin by this :slight_smile:
Cheers
Sophie

Ah - I see. I've installed the help authoring extension, and there's a new
menu item. But now the Documentation/Help wiki article tells me that I have
to set up a document root, which is in my clone of the help git repository -
which of course I don't have. And as I don't know git I can't get much
further!

I'm closing down now for the night - so I won't be able to answer until
tomorrow.

Hi Peter,

ptoye schrieb:

Ah - I see. I've installed the help authoring extension, and there's a new
menu item. But now the Documentation/Help wiki article tells me that I have
to set up a document root, which is in my clone of the help git repository -
which of course I don't have. And as I don't know git I can't get much
further!

I'm closing down now for the night - so I won't be able to answer until
tomorrow.

You can download the current (master, upcoming version LO 5.1) help files from http://dev-builds.libreoffice.org/pre-releases/src/

7-Zip can unpack it. It first makes a tar folder and therein a tar file, which you then have to unpack. You will get a folder "helpcontent2".

When you do not have prepared the Cygwin-environment and do not clone via git, then you need to make a backup of the file you want to work on prior to your work.

If you do not know how to make a unified diff file yourself, then you attach both the original and the changed file to the issue in Bugzilla. That way a committer can generate a diff-file and upload it to Gerrit for review.

For starting this a suitable way, but in the long term you need to make a Cygwin-environment. Find a description on https://wiki.documentfoundation.org/Development/BuildingOnWindows
[I have used that way, not the "lode" approach, mentioned there.]

Kind regards
Regina

Thanks Regina, but this is exactly the sort of issue that I mentioned in my
last post. If I have to download ( and learn how to use) Cygwin and Git
before I can even get started, it's an instant turn-off!

But the link you sent me seems to be for people who want to work on LO
itself - I just want to edit a section in a help page, which is a bit
different. Although I used to be a pretty good programmer, I don't have the
time or inclination to get stuck into modifying LO, much as I'd like to.

Hi Peter,

Thanks Regina, but this is exactly the sort of issue that I mentioned in my
last post. If I have to download ( and learn how to use) Cygwin and Git
before I can even get started, it's an instant turn-off!

But the link you sent me seems to be for people who want to work on LO
itself - I just want to edit a section in a help page, which is a bit
different. Although I used to be a pretty good programmer, I don't have the
time or inclination to get stuck into modifying LO, much as I'd like to.

You don't need to build LO now.
If you want to submit fix in a one page, you can send in any form it even in a
file .odt.
Copy the text in Writer from a page you want to edit;
Turn record changes (Edit -> Track Changes -> Record changes);
Make your changes;
Save the document and send.

Do not forget about the license.
https://wiki.documentfoundation.org/Development/Developers

But documentation authors must check how it will be shown in the local Help.
Even if we chenge a letter in a text, without touching format, there is
probable that we can break accidentally the format. This can occur for various
reasons: tiredness, inattention or a bug in HelpAuthoring. In addition, we are
the first line of defense against from bug in the work of the Help. Therefore
we make the LO build.

Best regards,
Lera

Hi Peter,

ptoye schrieb:

Thanks Regina, but this is exactly the sort of issue that I mentioned in my
last post. If I have to download ( and learn how to use) Cygwin and Git
before I can even get started, it's an instant turn-off!

To use the extension you only need the original help files. Download
http://dev-builds.libreoffice.org/pre-releases/src/libreoffice-help-5.1.0.0.alpha1.tar.xz
unpack it and you can start working on the help.

I give you the link to the "pre-release", because that is more up to date than the help files from the common download page.

But the link you sent me seems to be for people who want to work on LO
itself - I just want to edit a section in a help page, which is a bit
different. Although I used to be a pretty good programmer, I don't have the
time or inclination to get stuck into modifying LO, much as I'd like to.

I thought it was clear which of those files are the help files, obviously not. I have now added the direct link above. You need neither the other source packages nor Cygwin to work on a help file.

If all that is not comfortable for you, than open the help page you want to edit, set the cursor top-left, use Ctrl-A to mark the whole content, use Ctrl-C to copy it to clipboard, open a new Writer document and paste it. Save the document. Then proceed with change tracking as Lera has described.

Kind regards
Regina

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.

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.