Use of "allow to" in documentation

I've noticed that the phrase "allow to" or "allows to" appears a lot in the
API documentation, and also in some of the help files. AS a native UK
English speaker, I feel that I should point out that this is incorrect
grammar (I think it's also incorrect in US English). "Allow" must take an
object (except in the phrase "allow for"). There's a good discussion of this
in
http://english.stackexchange.com/questions/85069/is-the-construction-it-allows-to-proper-english
which implies that it's a translation problem (maybe a German speaker here
would like to comment).

For example "If the current entry in the Settings listbox allows to edit a
value, you can click the Edit button." needs editing to something like "If
the current entry in the Settings listbox is set to allow editing of a
value, you can click the Edit button."

There is also the question of whether "allows" is the correct word in many
cases. "<This parameter> allows to <change a value>" is, strictly speaking,
ambiguous. Does it mean that the parameter sets/clears a switch which makes
the change of possible (the strict meaning of "allows"), or that the
parameter changes the the value directly, in which case "allows to change"
can be replaced by "changes"? In many cases, I suspect that the latter is
intended.

There's an example below taken from
https://wiki.documentfoundation.org/HelpContent#Make_Images_Appear which
shows the problem: three of these paras use "allows to", three don't, but I
think they all have the same meaning!

    Create help file: creates a new .xhp file based on the template. If the
template is not found, the file can't be created and an error message is
displayed.
    About: displays the version number of the extension
    Set Document Root: allows to select the document as root file
    Edit meta data: allows to give a title to the help file and to leave a
comment. The Indexing button allows to include or ignore the file when
running a search
    Validate this help file: allows to run some checks on the xml structure
of the file
    Toggle l10n: sets the localize attribute on false:

Hi.
I come across this a lot in manuals I transcribe. I most frequently insert a "you".

Set Document Root: allows to select the document as root file >> Set Document Root: allows you to select the document as root file

Not sure of the context, the above is still ambiguous to me although it provides an example of insertion of "you" and because it is so frequent (in my work) a search and replace is a quick fix.
Steve

Hi steveedmonds,

Why not leave it out altogether? "Set Document Roots: Selects the document as root file."

Saves typing!

Best regards,

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

Hi Peter,

ptoye píše v Po 30. 11. 2015 v 04:28 -0700:

There's an example below taken from
https://wiki.documentfoundation.org/HelpContent#Make_Images_Appear which
shows the problem: three of these paras use "allows to", three don't, but I
think they all have the same meaning!

This is very easy to fix. wiki.documentfoundation.org is editable by
anyone who registers; so if you can register & log in, then you'll see a
small [edit] link next to the item that's wrong.

When you press it, it will lead you directly to the text - please just
correct it to use the correct English, check the draft, and publish it,
no approval by anybody is needed there.

Having said that; what is worse, we have these mistakes in the help
itself too. IIRC you told that it is hard for you to set up the git
repository - can we eg. meet on IRC to go through the process together,
so that you can make the improvements there too?

All the best,
Kendy

Jan,

OK, when I have time I'll fix the wiki, That's the easy bit.

For the help files, I already have a Git system on my PC (used with Visual Studio Express), but don't know Gerrit at all. I'll read through the documentation on how Git is used for the help files, but I think I'll need help on Gerrit. It won't be for a few days. I don't have an IRC client (or does WIndows 7 have one built-in - I've not found it?) so that will be the first thing. What timezone are you in - your name implies the Central European time zone - UTC+1, so it shouldn't be too difficult to find a time that we're both awake.

Best regards,

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

Hi Peter,

Peter Toye píše v St 02. 12. 2015 v 16:13 +0000:

OK, when I have time I'll fix the wiki, That's the easy bit.

Cool, thanks! :slight_smile:

For the help files, I already have a Git system on my PC (used with
Visual Studio Express), but don't know Gerrit at all. I'll read
through the documentation on how Git is used for the help files, but I
think I'll need help on Gerrit. It won't be for a few days.

I see. gerrit is (just) a review system; in other words, a system that
allows everybody to have write access - you can commit and push your
changes (to gerrit), where somebody with the appropriate rights will
read your change, and either comment on that (so that you know what to
fix), or will merge it to the main git.

You need to do a bit of a setup:

https://wiki.documentfoundation.org/Development/gerrit/setup

but then for your work, you'll push very similarly as with the normal
git.

I don't have an IRC client (or does WIndows 7 have one built-in -
I've not found it?) so that will be the first thing. What timezone are
you in - your name implies the Central European time zone - UTC+1, so
it shouldn't be too difficult to find a time that we're both awake.

Better if you have an IRC client, but if not, you can join via web too:

https://webchat.freenode.net/

Join the #libreoffice-dev channel, I'm sure you'll find many people who
will be able to help you with the gerrit setup, if I'm not around or not
responding from some reason (I'm "kendy" there).

All the best,
Kendy

Hi Jan,

I read through the pages on gerrit setup (two of them - they seem to be very similar to start with, and I fond that bit confusing!), and started to get onto the gerrit system. Then I found that the commands to use gerrit were totally Unix-oriented so asked on IRC and was pointed to the LO development on Windows wiki page, which implies that I have to install cygwin. Is this necessary just for gerrit registration? I won't be building LO itself, just editing the help files.

Best regards,

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

Tom,

Steve's idea is a good one, but who is the "you". In a help file it's fairly obvious - the person getting help. In an API definition it's not so obvious. Is it the programmer or the program user?

I take the issue you raise about translation. I'm a newbie in LO documentation (apart from using it, that is), and don't know the processes. For the help files it may not be too much of a problem as I think there are only 8 which use "allow to". But it's everywhere in the API documentation - that would be a major task. I won't take any action until I hear back from you.

There's a discussion here about a style guide - while grammatical issues may not be strictly "style" common mistranslations could well be pointed out there. Another issue is that some documents don't use articles ("a", "the") very well, Presumably a translation issue. Easy to do it your first language isn't the target language and in some cases even if it is.

Best regards,

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

Jan,

Sorry it's taken so long - I got held up as you might have seen.

I'm getting ready to make the first set of amendments now, but I'm still a bit confused about the workflow. Do I update the help file on the Git repository (using push) directly, or do I use gerrit? In the latter case I assume that I don't need Git except for my own purposes.

I've not yet tried to get onto gerrit, so I'll try to do that tomorrow (unless something of higher priority arrives). You have been warned....

Best regards,

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

I now think that I've managed to set up my Git repository correctly, so I'll
start editing.

I've two questions:

1) There are about 8 files to modify. Should I submit all of them in one
commit, or do each separately?

2) As well as the "allow to" issue, I've noticed that some files have
slightly ungrammatical English in that they leave out the articles ("A" and
"The") - easily done if your first language doesn't use them at all. I can
patch this at the same time. Again, is it worth while doing a separate
commit as logically the corrections are completely separate?

Hello Peter

Glad to see you made it.

I now think that I've managed to set up my Git repository correctly, so I'll
start editing.

I've two questions:

1) There are about 8 files to modify. Should I submit all of them in one
commit, or do each separately?

Your mileage may vary. 8 is a good number to not stress the patch
reviewer, especially if the patches are related.

2) As well as the "allow to" issue, I've noticed that some files have
slightly ungrammatical English in that they leave out the articles ("A" and
"The") - easily done if your first language doesn't use them at all. I can
patch this at the same time. Again, is it worth while doing a separate
commit as logically the corrections are completely separate?

On the same files as above, please include the grammatical corrections
you find.

Thank you

Olivier,

Thank you. I'll do that. Then I'll have the fun of working out how to upload to Gerrit. Never a dull moment.

Best regards,

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

One further issue: I don't know the LO bureaucracy but the "allow to" issue
hasn't been filed as a bug in Bugzilla. Should I do this or isn't it
necessary?

Hello Peter

Are you refering to help content or Guide Books?

On Guide books, there is no need for bugzilla.

On help contents, then it worth to note that HC is translated into
several languages. A change in the English string due to a style
improvement will put the string in fuzzy state, forcing the translators
to review the string. This is not always fun for them, because each
language has its style and the change in English may not apply for the
target language (I speak for myself because I am a translator). So in
case of HelpContent, I recomend proceeding changes of style only when
the help file is being touched by a content update, to prevent a massive
batch of string review.

And to answer your question, no need for bugzilla for style changes,
only for content change, update or creation.

Kind regards

Olivier

Hi Peter,

Hello Peter

Are you refering to help content or Guide Books?

On Guide books, there is no need for bugzilla.

On help contents, then it worth to note that HC is translated into
several languages. A change in the English string due to a style
improvement will put the string in fuzzy state, forcing the translators
to review the string. This is not always fun for them, because each
language has its style and the change in English may not apply for the
target language (I speak for myself because I am a translator). So in
case of HelpContent, I recomend proceeding changes of style only when
the help file is being touched by a content update, to prevent a massive
batch of string review.

I completely second Olivier here. If there is a possibility of scripting
to avoid the fuzzy tags on the target languages, then no problem.
Otherwise, like Olivier said, better to wait for an update or proceed
only with small volumes.
Cheers
Sophie

Sophi and Olivier,

I'm referring to help content only. The changes that I'm making are cosmetic - either removing grammatical errors ("allow to") or inserting articles. They shouldn't need translating as I'm sure the translators have already corrected this in their own languages.

I intend to change 8 files only. I have found a problem, though (see my latest thread), and will wait for this to be cleared up before submitting anything.

Best regards,

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

Hi :slight_smile:
It is small volumes at the moment. I think it's about 6 strings this
time.
Regards from
Tom :slight_smile: