Hey Attila.

Thanks for the patch. In terms of changing strings, I am waiting to update the documentation until all the changes are made. For instance, if GNOME adds a keybinding to toggle Orca on and off, that should be added and the Orca + Q might become unbound. Why ask translators to translate strings that I'll just turn around and change again?

Joanie, I absolute agree this.
If all changes are done and need help to actualizing the documentation, I welcome help this work if you have other tasks.
Please ping me if this task are actual.

Attila

Joanie, José found a chapter into help documentation with containing the enable locking keys related check box. The problem related I think following help page:
help/C/preferences_key_echo.page

Look following paragraph into source mallard help file:
    <section>
      <title>Enable locking keys</title>
      <p>
        This option controls whether or not <key>Caps Lock</key>, <key>Scroll
        Lock</key>, and <key>Num Lock</key> should be spoken when pressed.
      </p>
      <p>
        Default value: checked
      </p>
    </section>

This preference are removed from Orca GUI preferences dialog/key echo page.

Attila

Created attachment 238529 [details] [review]
Updated patch

Joanie, newest patch containing the 2012 year doed help/C/introduction.page file related modifications, and I removed now the José wrote non existing preference the help/C/preferences_key_echo.page file.

The newest features documenting into help (new structural navigation listing command, changed learning mode, newest unbounded bindings, etc) fit this development cicle your openion?

Attila

I'm going to try. Documentation is not subject to string freezes.

If I can help you anything this task related, please tell me.

Attila

Created attachment 238557 [details] [review]
Newest revision

Updates since the yesterday sent version:
1. In the help/C/preferences_key_bindings.page removed the alternate column related paragraph, this column are not existing into Orca gui preferences dialog/keybindings page. This problem José wrote with Orca list.
2. In the help/C/howto_learn_modes.page file I little modify the exiting documentation (describe help content presenting with F1 key, and describe new way activating the list shortcuts function).

Attila

Joanie, what can I help you the documentation related tasks? Can I help you the documentation revision related work?
Now I have more time to work this task.
If you would like, I welcome reading english language help content and try doing update related tasks to collect change suggestions with a bigger patch.
What branch possible commit future the updated documentation? Only master, or master and gnome-3-12 branch?
I don't no yet how many paragraphs need changing, but translators for example need enough time to translating changed documentation parts before coming out a new Orca maintenance release (for example 3.12.1).

Attila

Review of attachment 238557 [details] [review]:

I committed the parts of your patch where obsolete documentation is removed, namely the Alternate column and locking keys option.

I did not commit the Qt change because to be perfectly honest, it sort of supports AT-SPI2. But when I was doing some refactoring, I discovered that there are at least some cases where expected states and/or events were absent. So before suggesting that Orca + Qt should JustWork(tm), I want to review the current state.

I did not commit the List Shortcuts Mode change because that documentation was already updated to reflect the new keystroke along with the fact that it is no longer a "Mode" but a proper dialog with a proper list.

I did not commit the presentation of the version number because I don't think that necessarily belongs there.

In addition to the above, I have added documentation for the structural navigation commands. (Yes Attila, to both 3.12 and to master. <smiles>)

As for how you could help, let's split this stuff up into chunks (with separate patches for each chunk):

1. Obsolete documentation in which the only required change is to delete the text. An example would be the bits I committed from your last patch: https://git.gnome.org/browse/orca/commit/?id=e6c2d1c41af42e4da34dcd157d053561ad493a97

2. Command additions and changes that do not require descriptions or explanations. Just a list of short descriptors and keystrokes. An example would be the structural navigation commands additions I did. You can see that here:
https://git.gnome.org/browse/orca/commit/?id=ebe9db46e817afcadb6b0e4ff73a3197ab2c8488

Those sorts of patches are: Easy for me to review, easy for me to quickly correct any language nits, and easy to commit. And no discussion should be needed.

The last chunk would be additions and changes that do require descriptions and explanations. And/or might be something we need to discuss. Examples of these would be your proposed change regarding the statement about Qt as well as the suggested change about the fact that Orca announces the version. And here's what I would suggest we do to tackle working on these efficiently:

1. Get me a list -- not a patch, but a list -- of things you think should be changed or added.

2. You and I discuss that list and then possibly do some dividing and conquering. <smiles> In some cases, I might have a very strong opinion on what that text should look like. If so, I might opt to do it myself. In other cases, I'll probably say, "You're right, good point, please write some text on the foo page for it" and wait for a patch specific for that.

Sound like a plan?

Hi Joanie,

Very nice the already updated parts (I already looked the C/commands_structural_navigation.page file).
Some cosmetic suggestions:
1. Please change following titles in this file to more describe the purpose the described commands:
Headings: heading level navigation commands
Forms: forms handling related commands
links: links related commands
lists: lists related commands
Tables: Table navigation commands
Text Blocks: Text Blocks related commands
Other Elements: Other Elements related commands
For example the "Tables" title text more documentation presenting, so need a new replaced text in this file.
Following files use this string:
#: C/commands_structural_navigation.page:295 C/howto_tables.page:17
For example the "Tables" one word english text hungarian language possible translating with "táblázatok" text, and depending the context of actual text, have possibility to use "Táblázatnavigációs parancsok" text.
You accept this suggestions with section heading levels related in this file?

2. Your structure to paste the list of any HTML element related commands is good. But not better to doing a new section this file with describe one place the list of HTML elements related commands?
Look an example:
List of HTML objects related commands ( this is will be a second heading level with end of this help file)
The Screen Reader list of HTML objects feature provide possibility to collect various HTML elements with an easy handle list. You need use following commands, depending what objects want to collecting a list:
After this, simple need pasting all list of HTML objects related paragraphs. Personaly me both two methods is good.

If you tell me what suggestions accepting you this file related, I welcome doing a commit ready patch.

A general question with entire documentation related:
Orca generic name changed from "Orca Screen Reader" to "Screen Reader", but for example in the desktop icon file the X-GNOME-FullName containing "Orca Screen Reader" text.
Need replacing in the documentation the "Orca" related text parts with "Screen Reader" text? If we doing this, translators possible will be very angry.
Following files possible affected, simple Grep result with "Orca" search term, I already removed from the list the "Orca Modifier" related text parts, but not paste entire list:
commands_braille.page:    The following commands allow you to control <app>Orca</app> from your
commands_chat.page:    <app>Orca</app>. You will notice that several of these commands
commands_controlling_orca.page:    <title type="sort">1. Controlling and Learning to Use Orca</title>
commands_controlling_orca.page:    <title type="link">Controlling and Learning to Use Orca</title>
commands_controlling_orca.page:      Commands for interacting with <app>Orca</app>
commands_controlling_orca.page:  <title type="link">Controlling and Learning to Use Orca</title>
commands_controlling_orca.page:    <title>Commands for Controlling <app>Orca</app></title>
commands_controlling_orca.page:      The following commands can be used to get into <app>Orca</app>'s
commands_controlling_orca.page:      Preferences dialogs, toggle <app>Orca</app> on and off, and bypass
commands_controlling_orca.page:      <app>Orca</app> commands to avoid shortcut conflicts within the
commands_controlling_orca.page:          Toggle <app>Orca</app> on and off in GNOME:
commands_controlling_orca.page:          <link xref="preferences">Orca Preferences</link> dialog
commands_controlling_orca.page:          Orca's Preferences dialog for the focused application
commands_controlling_orca.page:    <title>Commands for Learning to Use <app>Orca</app></title>
commands_controlling_orca.page:      In Learn Mode, <app>Orca</app> will announce each keystroke you pressed
commands_controlling_orca.page:      along with any associated <app>Orca</app> command that keystroke is bound
commands_controlling_orca.page:      <app>Orca</app> commands you can use.

I not appending the list. If we replacing all proper "Orca" name with "Screen Reader" name, this is a very large change and generating lot of fuzzy messages.
I will doing a patch to you clear see how many messages will be changing if the proper patch is committed.

Attila

> 1. Please change following titles in this file to more describe the purpose the
> described commands:
> Headings: heading level navigation commands
> Forms: forms handling related commands
> links: links related commands
> lists: lists related commands
> [...]

Why? They are on the page for Structural Navigation Commands. So isn't it already obvious that all of those things are commands related to structural navigation? Your change, in my opinion, does not make things any more clear. And it will require translators to do work to change things. So I do not think this is a good idea. Sorry. Let's focus on finding things that truly need to be changed, such as what I described in comment 10, namely:

* obsolete things (because obsolete things are technically incorrect)
* command addition changes (because wrong commands are technically incorrect, and missing commands are, well, missing)
* Other things that the user really needs to know in order to be able to use Orca, and that is important enough to ask the translation team to translate.

> #: C/commands_structural_navigation.page:295 C/howto_tables.page:17
> For example the "Tables" one word english text hungarian language possible
> translating with "táblázatok" text, and depending the context of actual text,
> have possibility to use "Táblázatnavigációs parancsok" text.

I would have thought that in that case the context would come from the page content itself (i.e. that you would know how to translate it because the help content is like the translator notes). 
 
> 2. Your structure to paste the list of any HTML element related commands is
> good. But not better to doing a new section this file with describe one place
> the list of HTML elements related commands?

I had thought about that when I wrote that documentation, but I decided not to for a couple of reasons. If a user wants to know how to navigate amongst Foos in a document, there's only one place to look rather than two. Also, if the user is reading the documentation from top down, there is a pattern we want him/her to notice: LETTER - Next, SHIFT+LETTER - Previous, ALT+SHIFT+LETTER - List of. We also want one to notice where that is not the case (e.g. form fields, anchors, and separators).

(And, no, I don't think we want to add new list-of dialogs for anchors and separators.)

(In reply to comment #12)
> A general question with entire documentation related:
> Orca generic name changed from "Orca Screen Reader" to "Screen Reader"

This one let's put on the to discuss list. Because I do see your point here. I don't see it as a high-priority change. Nor do I see it as a 3.12-worthy change. But I'm not rejecting it. I want to tackle the must-do changes first, however. Fair enough?

Created attachment 273169 [details] [review]
Bigger patch with trying replace old Orca name with Screen Reader generic name

Hi Joanie,

I tryed replacing in Orca documentation the oldest used <app>Orca</app> name with the newest changed Screen Reader name.
Partialy I ready this task. This is a large patch, I suggest we working this change when all other gnome-3-12 branch documentation related tasks done .
I very suggesting if this attached change happening future the documentation, only the master branch you commit the Orca name related changes, because will be generating lot of number of fuzzy messages.
Need determining an another terminology related question final answer if we changing "Orca" name to "Screen Reader" future in the documentation.
What will be need happening the added keybindings with using "Orca" or "Orca Modifier" text a key combination?
In Orca preferences UI dialog/keybindings page the case now following:
The "Orca modifiers" combobox renamed with "Screen Reader Modifier Key(s)", I partialy already followed this change for example my patch with following files:
help/C/howto_the_orca_modifier.page, help/C/preferences_general.page
After when I killed all "Orca" related names with normal texts, I think 117 lines containing the Orca modifier texts.
Now, in both List shortcuts feature and key bindings dialog Orca not using the Orca modifier text, in laptop layout simple using localized "caps lock" text.
So we what doing future this key combinations if want replacing all "Orca" texts the new general Screen Reader part?

Attila

Review of attachment 273169 [details] [review]:

Thanks for this patch. But like I stated in my earlier comment, this is a topic that we need to consider. For instance, I'm not sure we want to do a global change of "Orca" to "Screen Reader". Beyond that, I don't think we need to add "available" in those places. And lastly, this particular bug is about updating the documentation to include new and changed features. Whether we say "Orca" or "Screen Reader" is not a new or changed feature.

Agree with you wrote. If we all places want follow up this general name change, too many places need doing this change.
But for example what need doing following situation?
The "Orca find" dialog the title changed with "Screen Reader Find Dialog" or similar when in UI replaced with Orca and Orca Screen related texts with Screen Reader.
Not need follow up this change in the documentation future?
Anyway, I next week reading entire gnome-3-12 help content.
If I founding any importanter parts with need doing change or update, I will describe you or attaching a patch if only need remove an obsoleted documentation part.

Attila

Hi Joanie,

I not begin readed yet detailed with Orca gnome-3-12 help content, but looked Orca preferences dialog/keybindings page the unbound section with containing unbounded keybindings.
When I morning doing Orca name replacement related testing patch, If I see right following unbound commands I think not describe awailable Orca documentation, sorry if I listing a command with already documented in Orca's help content any place:
Bookmark where am I with respect to current position,
Cycles to the next settings profile (this is a new feature I think since Orca 3.10),
Cycles to the next capitalization style (new feature since 3.10, capitalization style values need describing too),
Pans the braille display to the left (this unbound command I think duplicated bot main unbound section and braille bindings, I don't no why),
Pans the braille display to the right (this keystroke presenting both main unbound section and braille bindings, I don't no why),
Toggles the speaking of indentation and justification (I think this is a newest feature, the unbound binding absolute sure),
Cycles to the next speaking of punctuation level (newest feature since Orca 3.6 or 3.8),
Cycles to the next key echo level (newest feature),
Copies the contents under flat review to the clipboard (newest important feature since Orca 3.10),
Appends the contents under flat review to the clipboard (newest important feature since Orca 3.10),
Quit Orca (since Orca 3.8 this command are default unbound. The documentation need describe this unbound binding and the adwantage for example other environments related, example environments is LXDE or XFCE with need the user bound this command a keystroke).
With quit command related, other environments important to document this possibility, because LXDE and XFCE environments not have builtin bindings to toggle on/off screen reader support.
Can you examine this unbound bindings list and write missing parts the help content any proper place?

An another very nice function with not documented yet Orca side is your wonderful unified spell check support, with awailable since Orca 3.12 version.
In Gedit and Thunderbird Orca application-specific preferences dialog the last page awailable following check boxes, with not documented yet in Orca help document:
Spell error check box, default value is checked,
Spell suggestion check box, default value is checked,
Present context of error check box, default value is checked.
Your openion need documenting this check boxes purpose?

Attila

Hi Joanie,

In commands_bookmarks.page help file you added following paragraph:
<app>Orca</app> provides several commands which can be used to \"bookmark\"
a given object for the purpose of navigating back to it later. Most of these 
commands are \"bound\" to keystrokes. Please see <link xref=
\"howto_key_bindings\">Modifying Keybindings</link> for information on how "
"to bind unbound commands.

The problem have the second sentence. Not unbound the right word this context environment, or not need inserting a not word before the \"bound\" part?

Created attachment 273228 [details] [review]
Fix a typo error in help/C/preferences_braille.page file

I fixed a typo the contracted braille check box related (missed previous a t letter the check box name in the documentation), please commit this patch.
I have a question the braille preferences documentation related:
1. The braille preferences dialog page have following orders the GUI widgets:
Enable Braille support check box,
Disable end of line symbol check box,
Abbreviated role names check box,
Enable Contracted Braille check box,
Contraction table combo box,
verbosity radio button group,
selection radiobutton group,
Hiperlink radio button group.
Me absolute logical the now used braille preferences documentation structure, but not need your openion follow up this UI order? I described now the dialog tab order.

I found an another document part in this document the verbosity setting related with default not entire True I think, little need modifying the example or founding a better example:
"Verbosity

This radio button group determines the amount of information that will be brailled in certain situations. For example, if it is set to verbose, keyboard shortcut and role name information is displayed. This information is not displayed in brief mode."
Sure good the example? Orca doesn't presenting braille for example the mnemonics letters, both verbose and brief mode. 
Try for example looking in GNOME Terminal the edit menu content with braille, both verbose and brief verbosity levels.
The accelerators for example presenting both brief and verbose levels, mnemonics letters is not because Orca not yet supporting braille this feature. Oldest time I tryed doing a patch a report with trying implementing this function, but not actualized yet the master branch this function code. I not remember the report number, but I will try to search the report and future actualizing my patch with master branch if you future have time to review my implementation.
Rolenames related the case is following, very caotic now the working method, I not tryed previous this setting change because I always would like seeing the rolename type my display:
The combo box rolename presenting braille both verbose and brief levels, but the radio button, check box, slider, push button  role names only presenting with verbose level. With radio button and check box role related in brief mode only presenting the indicator before the rolename label (for example the enable speech related check box I right see the checked indicator before the label and not see the check box role name), the slider rolename I right seeing the slider label and slider value (a good example the speech rate with Orca preferences dialog/voice page).
When I tested the two setting difference now, I used GNOME Terminal Edit menu and Orca preferences dialog, because I think all typical rolenames available in the preferences dialog.
Can you known a better example the braille verbosity level related?
So, my short test showing the combobox rolename related I need reporting a bug with brief verbosity level related, if need this, next week monday I will be doing the report.
I very sorry previous I not detected this problem, but not too late fix this issue future with Orca 3.12 maintenance release I think.

Attila

Review of attachment 273228 [details] [review]:

Thanks! Committed.

(In reply to comment #19)
> Hi Joanie,
> 
> In commands_bookmarks.page help file you added following paragraph:
> <app>Orca</app> provides several commands which can be used to \"bookmark\"
> a given object for the purpose of navigating back to it later. Most of these 
> commands are \"bound\" to keystrokes. Please see <link xref=
> \"howto_key_bindings\">Modifying Keybindings</link> for information on how "
> "to bind unbound commands.
> 
> The problem have the second sentence. Not unbound the right word this context
> environment, or not need inserting a not word before the \"bound\" part?

I don't see a problem. "bound to keystrokes" means "have shortcuts". "bind" means "give a shortcut". And "unbound" means "doesn't have a shortcut." And looking at the list, I think it is accurate to say that most of those commands do have shortcuts.

Created attachment 273269 [details] [review]
A small cosmetic related change the help/C/commands_bookmarks.page help file

Joanie, original help/C/commands_bookmarks.page file have following part:
"Go to the previous bookmark for the application or page: Orca Modifier+Shift+B
Go to the next/previous bookmark for the application or page: Orca Modifier+B"
I doed a small change the second command related, simple removed the previous word the command description (I think this is unneed).
If you agree this change, please commit this patch.

I have got a little offtopic question with Yelp and keybindings related:
When I tryed reading entire help/C/commands_bookmarks.page help file in Yelp, I not see more  keystrokes. Orca doesn't announce the keystrokes with speech and braille this situation, and when I using the down arrow key, Orca repeating the previous line with containing the command name description.
Before I reporting unneed this bug with Orca, can you little looking following testcase?
1. Goto the Orca source directory.
2. Run yelp help/C/commands_bookmarks.page command, and if need, enable the caret navigation with F7.
3. Try reading the help content with down arrow key after you press once the h keystroke.
You listening only the speech output and braille output your display. This is an already known Webkit GTK issue or an Orca issue? The keybinding combinations related sintax in the Mallard document is right.
I using following Yelp version:
3.10.2

Attila

Created attachment 273318 [details] [review]
Fixed some options related parts in the introduction help content

Joanie, please review this patch.
I fixed some option short and longest option name. My question:
In the long name need the equals character after option name? The orca --help switch presented short help summary doesn't use the equals character.
Possible need fixing the equals character related parts.
An another question:
The --enable and --disable options possibility the braille-monitor switch is awailable the master and gnome-3-12 branches?

Attila

Comment on attachment 273318 [details] [review]
Fixed some options related parts in the introduction help content

Thanks. Patch committed. And, yes, the braille monitor option is still present and working.

Created attachment 273380 [details] [review]
Orca modifier combobox UI change related patch

Joanie, in Orca preferences dialog/keybindings page the Orca modifier combobox name is changed the 3.12 version.
Actual combobox  label is following:
Screen Reader Modifier Key(s)
I follow up this change the howto_the_orca_modifier.page help content, if you accept this change, please commit this patch.

Attila

Because the Orca modifier combobox related name in the UI changed with Screen Reader modifier(s), we keeping the now used Orca modifier terminology the documentation in other general parts with not related any UI elements, or we using screen reader modifier terminology?
Me not disturb the Orca modifier name terminology, affected documentation is for example the keyboard layout related documentation.

Attila

Created attachment 273381 [details] [review]
Fix a cosmetic error in help/C/howto_structural_navigation.page help content

Created attachment 273384 [details] [review]
Inserted a sentence with Control caret navigation related check box in the howto_forms.page help content

Created attachment 273385 [details] [review]
Little modification in help/C/howto_orca_find.page help content

Possible not need this modification, please look.

Attila

Created attachment 273388 [details] [review]
Larger modification in help/C/preferences_speech.page help file

Joanie, carefuly look this modification and not angry me if I doed a mistake.
Because the Orca 3.12 version and previous 3.10 version separate speech related preferences with the Voice and speech pages in preferences dialog, I reorder this help content.
So, I try collecting voice page awailable preferences with voice page part related documentation, and speech related preferences in Speech page related documentation part.
Possible not all places I using good indentation the Mallard document and visually need some reorder, but now the two pages awailable preferences is full categorized.

Attila

Created attachment 273401 [details] [review]
Fix braille verbosity setting description related paragraph

I try fixing the braille verbosity related paragraph with I wrote a previous comment.
I removed shortcut related part, and do a general description what happening if the user selecting the brief braille verbosity setting.
If the braille verbosity setting is brief, Orca presenting now only the combo box, menu and tearoff menu item role name, other role names is not presenting the braille display.
The mnemonics information is not presenting both verbose and brief braille verbosity setting mode, because Orca not supporting yet braille the present mnemonics feature (similar future feature with speech output already supported speak mnemonics feature).
The menu accelerator keys is presenting both verbose and brief mode, so the shortcut related part is not need the example.

Attila

Created attachment 273403 [details] [review]
Little change suggestion in help/C/preferences_key_bindings.page help file related

Joanie, I doed following changes this help file related:
1. Because in Orca preferences dialog/keybindings page the old "Orca modifier(s)" combo box label changed with "Screen Reader Modifier(s)" label, I follow up this change the documentation the first sentence.
2. I little modifying the key binding column related description. The keybinding column not the primary column with containing key binding, because the "Alternate" column with containing other keybindings is removed the table.
3. Final, I removed following paragraph, because Orca doesn't presenting I think the "Orca modifier" word in the table:
"Note that the key binding may include the word "Orca". This indicates that the Orca Modifier key should be held down along with the other keys."
Realy, when I browsing the keybindings table in the preferences dialog, for example laptop layout I see localized caps lock key name, not Orca or Orca modifier.

Please review this patch, and keep any modification with you accepting this help file related.

Attila

Created attachment 273408 [details] [review]
Add some UI changes in help/C/preferences_gecko.page help file

Joanie, I follow up some UI changes in this help file, and added some updated parts.
Please review this change carefuly.
Now I think this help content is full uptodate.

Attila

I think tomorrow I ending the preferences dialogs related documentation re reading.
Final, I need looking the commands related documentation with containing the keybindings. Hopefuly I ending this task with friday afternoon or evening.

Attila

Created attachment 273453 [details] [review]
Add two new unbound flat review commands in the help/C/commands_flat_review.page help content

End of this help content I added following unbound commands:
Copies the contents under flat review to the clipboard,
Appends the contents under flat review to the clipboard.

The main textual reviewing work related I ready. Some optional suggestions with now missing the documentation:
1. Please document your new universal spell check support related preferences an existing Orca's preferences document, or create a new help content.
Supported applications this feature related now:
Gedit, Thunderbird.
The Gecko available preferences help content I not added the affected new check boxes, because for example with Firefox related this preferences are not active.
Following check boxes purposes need documenting:
Spell error check box, default state is checked,
Spell suggestion check box, default state is checked,
Present context of error check box, default state is checked.

2. If need, please update with UI figures to the screen shot showing Orca actual preferences dialog awailable UI elements. Some UI element related labels or dialog titles is changed. An example the new separated voice and speech pages available preferences, some UI labels replaced with Orca name the new Screen Reader name, or entire removed the Orca name with some UI elements. The Orca find dialog the dialog title is changed.

3. If need, with main flat review related documentation please document the Copies the contents under flat review to the clipboard and Appends the contents under flat review to the clipboard command differences and purpose this commands.

4. Please document the capital style feature and available capital style levels, now only the cicle to the next capitalization style unbound command related description have the help/C/commands_speech.page help content.

5. If need, please add following technique any good place Orca documentation:
The commands_flat_review.page help content describing sayall command. If an Orca user press two quickly this keystroke, Orca sayall entire dialog content. I don't remember any place the Orca help content describing this technique or not, so possible important to add this information any sayall related content in the documentation.

6. With any good place please add the unbound "Quits the screen reader" unbound command documentation (the short command name and unbound state, and the longest command description purpose to why unbound this command by default).
In GNOME environment Orca users possible launching and quitting Orca the SUPER+ALT+S keystroke, but other desktop environments, for example LXDE or XFCE need the user bounding this command with a keystroke to have possibility quitting the screen reader.

Attila

Joanie, I forgot follow up a change in help/C/preferences_gecko.page file:
In Firefox and Thunderbird Orca's application-specific settings dialog last page missing the "Grab focus on objects when navigating" check box, this preference possible removed with Orca master and gnome-3-12 branch.
Very interesting, from the src/orca/guilabels.py file the "Grab focus on objects when navigating" translatable string is not removed, so I don't no what the actual state this preference.
I looked the src/orca/scripts/toolkits/Gecko/script_settings.py file and not founded the grabFocusOnAncestor preference related setting.
When you revieving my Gecko help preferences documentation related modification and Orca realy not supporting this preference, please remove this checkbox related paragraph from the help/C/preferences_gecko.page help document.
Your openion will be have enough time translators  finalize Orca's new updated documentation translation before Orca new 3.12.1 maintenance release coming out? When you would like publicating Orca 3.12.1 maintenance release?
Fortunately in my local system I always update Orca's hungarian help translation when any part is changing.

Comment on attachment 273269 [details] [review]
A small cosmetic related change the help/C/commands_bookmarks.page help file

Committed. Thanks!

Comment on attachment 273380 [details] [review]
Orca modifier combobox UI change related patch

Committed. Thanks!

Comment on attachment 273381 [details] [review]
Fix a cosmetic error in help/C/howto_structural_navigation.page help content

I committed part of this change. I agree that the punctuation is less than ideal, and that the colon should be removed and a period added. So that's the part I committed.

I disagree that we want to add the words "key combination" at the end. For one thing, I don't think it adds any meaning or makes things more clear for the reader. The documentation says press Ctrl+OrcaModifier+Space. What would you do differently if the documentation said press Ctrl+OrcaModifier+Space key combination? I think we can assume the reader seeing a combination of keys knows that it is a key combination.

For another thing, we don't add that phrase at the end of other keybindings -- including some on that very page.  So adding it in this one place makes things look odd and inconsistent. (And since it doesn't add any meaning or clarity as I mentioned above, I do not think we want to go through the entire documentation adding "key combination" everywhere.)

Comment on attachment 273385 [details] [review]
Little modification in help/C/howto_orca_find.page help content

I don't think this change is needed.

By the way, those strings are not GUI labels; they are descriptions. Also "The text to find" is .... Well, the text to find; it is not the location from which to start.

Let's leave this page as it is.

Comment on attachment 273401 [details] [review]
Fix braille verbosity setting description related paragraph

Hmmmmm. Shortcut information refers to things like Ctrl+C and not the mnemonic (underlined letter). Having said that, I'm seeing the shortcut presented for both verbosity levels.

So I think what we want to do here is not include this braille documentation issue as part of bug 690414. Let's open new bugs and determine first what the correct/expected braille really is:

* Should there really never, ever be role names?
* Should shortcuts (like Ctrl+C) really not be displayed in brief verbosity.

If, having solved those issues, the result does not match the documentation, then as part of those fixes, let's change the documentation to reflect the updated reality. Ok?

Comment on attachment 273403 [details] [review]
Little change suggestion in help/C/preferences_key_bindings.page help file related

I committed this change, but I did tweak the English a bit. I hope my tweaks fully reflect and address the fix you wanted to make. If not, you know where to find me. <smiles>

Comment on attachment 273453 [details] [review]
Add two new unbound flat review commands in the help/C/commands_flat_review.page help content

Committed with one tiny change: I capitalized the "u" in each "unbound" because that's what we do in all the other pages. (I noticed we didn't on the time-date-notifications documentation page, but that was the oddball page, so I changed those.)

Comment on attachment 273408 [details] [review]
Add some UI changes in help/C/preferences_gecko.page help file

Thanks for this patch. I did a different version which I have since committed.

The titles should reflect the name of the checkbox. That is why it said "This checkbox". I updated the titles.

I corrected the default value for the start of line. Thanks for catching that.

I added the autospeak section with different text. Also the default is checked for Firefox, but unchecked for Thunderbird. I'd have to review the history, but that was a design decision. Regardless, the documentation reflects these two different defaults.

I added a pointer note for the table options.

I removed the grab focus stuff.

So.... I think I addressed everything you found in need of changing through this patch. Please let me know if I missed something. Thanks!

Comment on attachment 273384 [details] [review]
Inserted a sentence with Control caret navigation related check box in the howto_forms.page help content

When that documentation was written it assumed only Gecko forms. While there is still work to be done for form accessibility in other applications (WebKit, Evince, LibreOffice, etc.), not all forms are Gecko forms. And I have seen form fields that you can arrow into and out of even without Orca being used. So rather than add a Gecko-only option, I think it makes more sense to remove the Gecko-specifics and make that statement more generic, reflecting the fact that depending on the form and application, you might be able to arrow into and out of form fields.  I have made and committed this change.

Comment on attachment 273388 [details] [review]
Larger modification in help/C/preferences_speech.page help file

Thanks for doing this! But I think what needs to be done is make the docs reflect the GUI. And in the docs, there is one doc page per gui page. So I did a similar split to the docs. I also added some missing default settings.

Hopefully I addressed all of the issues you found here. If not, please let me know.

(In reply to comment #36)

> 1. Please document your new universal spell check support related preferences

Done.

> 2. If need, please update with UI figures to the screen shot

Done, but not via updated images. <smiles> I took a look at what other GNOME app documentation does and I'm not seeing a bunch of dialog screen shots. Also, even if we don't change our GUI, each time GNOME decides a Gtk+ theme change is in order, our GUI looks different. Our images are not getting universally localized, so you have English images with non-English text. And the primary consumer of the documentation happens to be blind. Long way of saying, this screen shots are proving to be far more trouble for next to no benefit. We don't have screen shots in the docs any more.
 
> 3. If need, with main flat review related documentation please document the
> Copies the contents under flat review to the clipboard and Appends the contents
> under flat review to the clipboard command differences and purpose this
> commands.

I don't think this is needed. We have the commands added, thanks to you patch. We have flat review well documented. And surely people will understand what "copy to the clipboard" and "append to the clipboard" mean.

> 4. Please document the capital style feature and available capital style
> levels, now only the cicle to the next capitalization style unbound command
> related description have the help/C/commands_speech.page help content.

Understood, but those docs do not just "nicely fit" anywhere. The best place to put them would be in the preferences docs, but they are not in the GUI. And the original solution was a quick fix to solve a problem/complaint a user had. I'd like to do it better, and then document the result. The world will not come to an end if this one command -- which is now in our docs -- is not explained in depth. I opened bug 727691 to deal with that, docs included. That's going on the 3.14 todo list.

> 5. If need, please add following technique any good place Orca documentation:
> The commands_flat_review.page help content describing sayall command.

I added SayAll double-clicked to the page you mentioned. I don't think it needs further how-to explanation.

> 6. With any good place please add the unbound "Quits the screen reader"

Done.

So.... I think that I've gone through all of your patches, committed quite a few, did new versions for a few others that I thought should be handled differently. And hopefully addressed everything else you pointed out or asked.

Lastly, in response to your question about 3.12.1: I do the release on the GNOME schedule (more or less). Tarballs are due on the 14th. I can squeeze by being a day late. I had emailed the i18n list telling giving them the heads-up that docs were changing and that I'd ping the list when those changes were complete. So as soon as you tell me they are complete, I'll tell them to proceed.

Thanks again for all your help with this!

I will looking your modifications when working monday to update Orca's help hungarian documentation translation, but basicaly I think looks good the modified sections. After this, I think possible changing this bug status with resolved, fixed state and other language translators will be have enough time to doing translation updates.
Now, Orca documentation again uptodate and fine, describing all new keybinding commands and newest features.

With braille documentation related you wrote following:
"Hmmmmm. Shortcut information refers to things like Ctrl+C and not the mnemonic
(underlined letter). Having said that, I'm seeing the shortcut presented for
both verbosity levels.

So I think what we want to do here is not include this braille documentation
issue as part of bug 690414. Let's open new bugs and determine first what the
correct/expected braille really is:

* Should there really never, ever be role names?
* Should shortcuts (like Ctrl+C) really not be displayed in brief verbosity.

If, having solved those issues, the result does not match the documentation,
then as part of those fixes, let's change the documentation to reflect the
updated reality. Ok?"
Absolute, I think little need  redesigning the braille verbosity related Brief mode, but fit this the 3.14 cicle I think. Need future a research and more answers from Orca users what want seeing  he's braille display if using Brief verbosity level (verbose level absolute good, because if this verbosity level selected, user want seeing all informations hopefuly). You always doing this with Orca list and this method usual working good (+1 or -1 style answers).
Look my openion, I usual using verbose verbosity level, but looked previous brief verbosity level little bit when I worked the documentation update:
The accelerators me openion both two verbosity levels need presenting, this is the default action. This information is important to the user use more quickly an application with have accelerators (CTRL+A, CTRL+C, etc). I promise you the mnemonics feature future I will working, very would like to Orca 3.14 version supports this function not only speech mode.
Rolenames is a different story, because some rolenames have good indicators with marking the proper rolename and state, but some rolenames is not. Indicators awailable rolenames for example is check boxes, radio buttons.
But without rolename information difficult to identifying brief verbosity level the slider, push button, combobox rolenames, because this situation seeing only the label and value, except the combo box rolename.
An another Braille brief verbosity level report I suggested a future feature with provide user freedom the rolenames related to determine each verbosity level what want seeing he's display and what not, but this feature implementation require more coding work I think.

Attila

Hi Joanie,

I think we ready, every yesterday added new document parts good.
If you not want doing another update the documentation, I will closing this bug with resolved, fixed state after your confirming comment.

Attila

Thanks!! Yes, let's close this one. And I need to really force myself to not let documentation updating get behind, like I was guilty of here. Sorry about that!!

I'll give the i18n list the "all clear".

Many thanks Joanie the I18n team notification.
I closed the bug with resolved, fixed state.
You wrote following:
"And I need to really force myself to not
let documentation updating get behind, like I was guilty of here. Sorry about
that!!"
No problem, now Orca documentation is actual again.
When a new feature future adding with Orca, I will listening the commit message and orca-list notification. If the actual development documentation not containing the new feature description or a change and helping you, I will trying create a description the proper feature to the documentation. You always need doing more tasks with Orca related development cicle to development cicle, and this is not easy. A day have only 24 hours.