It turns out that our docs are not simply out of date. They are:

* Out of date
* Insufficient
* Not in format GNOME is adopting (Mallard)

Solving the insufficiency issue is resulting in our having way more documentation than belongs in the GNOME Accessibility Guide. Therefore the decision has been made by the Orca team in partnership with the Documentation team to relocate our docs to our module.

The GNOME Accessibility Guide will continue to contain Orca documentation, sufficient to get users started and should point to our new documentation.

Had I remembered this bug existed, I'd have logged commits as I was going. Now I'm going to be lazy to get this bug caught up.

commit 3cc54f74850f5a01e00f93df5e8fa8d58c893456
Author: Joanmarie Diggs <joanmarie.diggs@gmail.com>
Date:   Fri Dec 17 16:41:04 2010 -0500

    Doc rewrite in progress: Added an introduction to Bookmarks.

commit d85589e47ade6f845072ca2cc9f0c65997e9d4ad
Author: Joanmarie Diggs <joanmarie.diggs@gmail.com>
Date:   Fri Dec 17 16:17:57 2010 -0500

    Doc rewrite in progress: More Structural Navigation content, added table navigation content

commit 0303b7a5ca94c4ee6d25d32144622b7bdb7dcbbf
Author: Joanmarie Diggs <joanmarie.diggs@gmail.com>
Date:   Thu Dec 16 22:44:46 2010 -0500

    Docs rewrite in progress: Added structural navigation; made miscellaneous tweaks

commit bbfbf520f791ef47e04d611176d6aa913327983a
Author: Joanmarie Diggs <joanmarie.diggs@gmail.com>
Date:   Thu Dec 16 20:38:20 2010 -0500

    Doc rewrite in progress: Added a Live Regions page

commit e4cdc03367f0107652cf90178c1c147f26eb43d8
Author: Joanmarie Diggs <joanmarie.diggs@gmail.com>
Date:   Thu Dec 16 18:42:54 2010 -0500

    Fix for bug #637422 - bookmarkCurrentWhereAmI() is not presenting roles correctly

commit 547b22dbc222005eded0a1f06df10fe9f2d62819
Author: Joanmarie Diggs <joanmarie.diggs@gmail.com>
Date:   Thu Dec 16 11:59:48 2010 -0500

    Fix earlier snafu

commit afa0379bb62adb6ce76238676b9af7141c62270c
Author: Joanmarie Diggs <joanmarie.diggs@gmail.com>
Date:   Thu Dec 16 09:12:24 2010 -0500

    Mallard requires gnome-doc-utils 0.17.3 or above

commit f3a4169647de490945ea41bd02ed98d5fc585b68
Author: Joanmarie Diggs <joanmarie.diggs@gmail.com>
Date:   Thu Dec 16 08:47:38 2010 -0500

    More make distcheck work

commit a79af62bea5919e9cc856b95c7f73a61ea3623b3
Author: Joanmarie Diggs <joanmarie.diggs@gmail.com>
Date:   Thu Dec 16 08:10:47 2010 -0500

    Add help to Makefile.am for make distcheck

commit a479412e8032156641a67df3a9f6f45f40e90c82
Author: Joanmarie Diggs <joanmarie.diggs@gmail.com>
Date:   Wed Dec 15 21:01:52 2010 -0500

    Doc rewrite in progress: Notifications

commit c42f65c87b4266b2f0f17e9953df511fc3ae0644
Author: Joanmarie Diggs <joanmarie.diggs@gmail.com>
Date:   Wed Dec 15 20:14:21 2010 -0500

    Doc rewrite in progress: Mouse Review

commit 4b46a52999ed61a71ca0574c55749813f87c5b1a
Author: Joanmarie Diggs <joanmarie.diggs@gmail.com>
Date:   Wed Dec 15 17:59:25 2010 -0500


    Doc rewrite in progress: Mouse Review

commit 4b46a52999ed61a71ca0574c55749813f87c5b1a
Author: Joanmarie Diggs <joanmarie.diggs@gmail.com>
Date:   Wed Dec 15 17:59:25 2010 -0500

    Doc rewrite in progress: Where Am I

commit e43f60914a652bbd8f3874e927db9df1a067bcf0
Author: Joanmarie Diggs <joanmarie.diggs@gmail.com>
Date:   Wed Dec 15 16:47:10 2010 -0500

    Doc rewrite in progress: Spelling error indication

commit 9da6292eddeaef884af25961b52a89e868a9c683
Author: Joanmarie Diggs <joanmarie.diggs@gmail.com>
Date:   Wed Dec 15 16:28:19 2010 -0500

    Doc rewrite in progress: Flat review and Orca Find.

commit e8365badd99a5e83dae1edf7a1e1009cc8b92e62
Author: Joanmarie Diggs <joanmarie.diggs@gmail.com>
Date:   Wed Dec 15 10:43:32 2010 -0500

    Minor corrections

commit 85b6a347a2991a0a6efd8e53cb6d185a7304ef45
Author: Joanmarie Diggs <joanmarie.diggs@gmail.com>
Date:   Wed Dec 15 10:33:36 2010 -0500

    Start of the doc rewrite. A work in progress. Not "hooked up" yet.

* filled in some missing GUI items
* added a link on the main page to the GNOME Desktop Accessibility
  Guide
* corrected some typos

http://git.gnome.org/browse/orca/commit/?id=20076b22ff9c3201568a1d6df8a1fc0e03de4601

* hooked up the new help
* just... one... more... typo

http://git.gnome.org/browse/orca/commit/?id=61e871ea869ad4a51d36fbdc44bab38b8db66c09

Joanie, the new documentation is will be fantastic and wonderful if ready in the future.
When I begin translating the documentation, I see a mistake with original english documentation with verbosity setting with this day:
#: C/preferences_speech.page:114(p)
msgid ""
"The <gui>Verbosity</gui> setting determines the amount of information that "
"will be spoken in various situations. For example, if it is set to verbose, "
"<app>Orca</app> will speak shortcut keys for items in menus. When it is set "
"to brief, these shortcut keys are not announced."

The problem is following with the last two sentence:
1. The shortcut keys is only spokening if the speak object mnemonics check box is checked, independent the verbosity setting, I verifyed. So, both verbose and brief settings are spokening Orca the shortcut key informations if the speak object mnemonics check box is checked.
If this checkbox is not checked and the user choosing verbose setting, the shortcut keys is not spokening automaticaly, only where am I or detailed where am I command spokening shortcut key informations. This is true with brief verbosity setting too.

Another possible wrong text with text attributes part:
#: C/preferences_text_attributes.page:53(p)
msgid ""
"For example, by default the \"underline\" text attribute has a value of "
"\"none.\" This causes <app>Orca</app> to inform you about underlined text as "
"long as the text is actually underlined. If you always want this attribute "
"to be spoken irrespective of whether or not the text is underlined, then the "
"attribute should be checked and the <gui>Present unless</gui> value cleared."

Sure cleared automaticaly the present unless column value if the attribute is checked?
Old acguide containing following text, but this old text too not right full I think:
msgid ""
"For example, by default the \"underline\" text attribute has a value of "
"\"none.\" If the user has this attribute checked and the user types "
"<keycombo><keycap>Orca_Modifier</keycap><keycap>F</keycap></keycombo> and "
"the text in question is not underlined, then this attribute is not spoken. "
"If you always want this attribute to be spoken irrespective of whether the "
"text is underlined, then the attribute should be checked and the \"Present "
"unless\" value cleared."

If I remember right, the present unless column value is cleared only if the user navigate this column with right arrow key, press enter key, delete the text and press enter key again. But possible I remember wrong.

Attila

When I bring up the main page, the first thing that pops out to me is while reading down the page line by line, I come across several sections with headings but no indications of anything being a link.  Yet if I go back to the top of the same page and press tab, I land on some of these sections.  Actually as I right this, I realize these aren't links to something else but I seemed to be able to tab to them non the less.  I think what I might be missing here is a table of contents.  Most other help manuals seem to start out with a table of contents and end up being merely a link farm.  I'm glad the Orca page has meaningful content right on the front page.  But I think a table of contents at or near the top would be a good help too.

Since Joanie asked for nitpicking, and I've been doing the same to all
the X.Org docs recently, and know how useful fresh eyeballs can be to
that, here's some minor nits & random comments/suggestions (from browsing
the raw sources via the git web view):

preferences_gekco.page - typo in 'gecko' in the file name.

preferences_key_bindings.page - should you explain that KP_Insert is
 the one on the keypad for people who don't know X keysyms by heart
 like we do?

preferences_speech.page - some info about the differences between
 the different Punctuation Level settings might be nice, like you
 already have for Verbosity.

preferences_pronunciation.page - I'm weird enough that I'd probably
 prefer hearing "LOL" over "laugh out loud" - on the other hand, 
 pronouncing "a11y" as "accessibility" instead of "A eleven why"
 would not only be a relevant example but a bit of bonus education
 about what "a11y" means to newbies.  8-)

commands_mouse & commands_reading.page - should mention somewhere on the 
 page that "KP" is an abbreviation for the numeric keypad, and maybe add
 a pointer to howto_keyboard_layout for laptop vs. desktop keyboard setting

howto_keyboard_layout - should include text like preferences_general.page
 does that the difference between laptop & desktop is whether you have
 a keypad.

howto_text_setup - "even if the graphical desktop is not running" does not
 match with "Open a <gui>Run</gui> dialog" - perhaps change the alternative
 to something like "...you can use a terminal window or the system text 
 console."

howto_text_setup.page vs. preferences_speech.page - is the preference
 "speech server" or "speech synthesizer"?   (or is it different between
 the text & gui setups though the other choices sound the same)

I do wonder if the term "focus" needs to be explained to new users somewhere
given the number of pages that use the term, or if it's obvious enough to them.

Adding screen shots. Still have a few more to go.

http://git.gnome.org/browse/orca/commit/?id=dab2b17e3f173d8f4cb5e049b13bfc33a89598c0

Btw, Alan and Attila, thanks so much for the feedback! Once I finish figures, etc. I'll take a look.

(In reply to comment #6)
> Since Joanie asked for nitpicking, and I've been doing the same to all
> the X.Org docs recently, and know how useful fresh eyeballs can be to
> that, here's some minor nits & random comments/suggestions (from browsing
> the raw sources via the git web view)

Alan, you rock. Thanks so much!!
 
> preferences_gekco.page - typo in 'gecko' in the file name.

D'oh! Fixed.

> preferences_key_bindings.page - should you explain that KP_Insert is
>  the one on the keypad for people who don't know X keysyms by heart
>  like we do?

Good point. Done.

> preferences_speech.page - some info about the differences between
>  the different Punctuation Level settings might be nice, like you
>  already have for Verbosity.

I'll do this as part of adding the screenshot bits which I still need to do -- and am procrastinating on -- to that page.

> preferences_pronunciation.page - I'm weird enough that I'd probably
>  prefer hearing "LOL" over "laugh out loud" - on the other hand, 
>  pronouncing "a11y" as "accessibility" instead of "A eleven why"
>  would not only be a relevant example but a bit of bonus education
>  about what "a11y" means to newbies.  8-)

Good idea! Done.

> commands_mouse & commands_reading.page - should mention somewhere on the 
>  page that "KP" is an abbreviation for the numeric keypad, and maybe add
>  a pointer to howto_keyboard_layout for laptop vs. desktop keyboard setting

Done.

> howto_keyboard_layout - should include text like preferences_general.page
>  does that the difference between laptop & desktop is whether you have
>  a keypad.

Done.

> howto_text_setup - "even if the graphical desktop is not running" does not
>  match with "Open a <gui>Run</gui> dialog" - perhaps change the alternative
>  to something like "...you can use a terminal window or the system text 
>  console."

Done.

> howto_text_setup.page vs. preferences_speech.page - is the preference
>  "speech server" or "speech synthesizer"?   (or is it different between
>  the text & gui setups though the other choices sound the same)

Ugh. Just opened bug 637545 for the inconsistent use of language.

> I do wonder if the term "focus" needs to be explained to new users somewhere
> given the number of pages that use the term, or if it's obvious enough to them.

Hmmm.... Good question. Maybe so. Maybe we need to create a glossary of terms. I'll give it some thought, ask the users, ask the Doc Team lead, etc.

Thanks again very much!!

(In reply to comment #4)
> Joanie, the new documentation is will be fantastic and wonderful if ready in
> the future.

Yeah, I'm actually pretty happy with how things are progressing.

> The problem is following with the last two sentence:
> 1. The shortcut keys is only spokening if the speak object mnemonics check box
> is checked, independent the verbosity setting, I verifyed. So, both verbose and
> brief settings are spokening Orca the shortcut key informations if the speak
> object mnemonics check box is checked.
> If this checkbox is not checked and the user choosing verbose setting, the
> shortcut keys is not spokening automaticaly, only where am I or detailed where
> am I command spokening shortcut key informations. This is true with brief
> verbosity setting too.

To be honest, that might be a bug. But given that we want accurate documentation, I will change the example to the following:

~~~~~~~~~~~~~~
The <gui>Verbosity</gui> setting determines the amount of information
that will be spoken in various situations. For example, if it is set
to verbose, and you arrow into a word that is misspelled, <app>Orca</app>
will announce that the word is misspelled. When the level is set to brief,
this announcement will not be made.
~~~~~~~~~~~~~~

I have verified this to be the case both in the code and by actual testing. <smile>

Thanks for pointing that problem out!

As for the other issue you point out, I'm wondering if what the fix is is better language on my part because from my testing just now, what the documentation states is correct.

> Another possible wrong text with text attributes part:
> #: C/preferences_text_attributes.page:53(p)
> msgid ""
> "For example, by default the \"underline\" text attribute has a value of "
> "\"none.\" This causes <app>Orca</app> to inform you about underlined text as "
> "long as the text is actually underlined. If you always want this attribute "
> "to be spoken irrespective of whether or not the text is underlined, then the "
> "attribute should be checked and the <gui>Present unless</gui> value cleared."

But you ask:

> Sure cleared automaticaly the present unless column value if the attribute is
> checked?

I never said that there was any relationship between these two columns. What the docs are attempting to say is "If you always want to hear if text is underlined whether it's underlined or not, you must do two things:

1. Be sure that it's checked, at least in the speak column.
2. Go over and remove "none" (i.e. clear "none" from present unless column).

> If I remember right, the present unless column value is cleared only if the
> user navigate this column with right arrow key, press enter key, delete the
> text and press enter key again. But possible I remember wrong.

Nope, you remember 100% correctly. So.... How to clear up the confusion? I hope that the following language more clearly describes the two things you must do:

For example, by default the "underline" text attribute has a
value of "none." This causes <app>Orca</app> to inform you
about underlined text as long as the text is actually underlined.
If you always want this attribute to be spoken irrespective of
whether or not the text is underlined, the <gui>Present unless</gui>
column should be empty for underline. In addition, you should be sure that the
<gui>Speak</gui> column for underline is checked.

Please let me know if that addresses everything you've described here. And thanks again for the review!

http://git.gnome.org/browse/orca/commit/?id=150fd99577450cfc50cb676884f25edbd10d45d2

(In reply to comment #5)
> When I bring up the main page, the first thing that pops out to me is while
> reading down the page line by line, I come across several sections with
> headings but no indications of anything being a link.

[snip]

> But I think a table of contents at
> or near the top would be a good help too.

As you already know (but for the sake of documenting the conversation, along with a change I've since made, on this bug): I replied to your comment on the orca-list so that others could weigh in. One of the things I pointed out was that Mallard guide pages essentially *are* a sort of table of contents and that the real problem could easily be that my attempt to provide "helpful text" at the top wasn't actually, uh, helpful. <smile>

So, what I've done in response is remove (most of) the helpful text and replaced it with a "Quick Reference" section which includes links to the commands and preferences. In other words, commands and preferences are just other items in the functional table of contents that is the main guide page.

I still have to decide what to do about the gnome desktop accessibility guide sentence. But I also have to figure out how to make Yelp open it rather than the browser, which I assume means figuring out what Mallard expects when it comes to referencing local help that is not part of our help. So I'll ask Shaun (doc team lead) about both.

In the meantime Steve, please let me know if the change I made makes things better/less confusing/more table-of-contentsy/whatever. <smile>

Thanks (again) for the feedback!

Joanie, following yelp style link supporting Mallard?
I found following external help link for example with accessibility-guide translation file with linked an another help page:
msgid ""
"To report a bug or make a suggestion regarding the GNOME Desktop or this "
"manual, follow the directions in the <ulink type=\"help\" url=\"ghelp:user-"
"guide?feedback\">GNOME Feedback Page</ulink>."

Or an equals example with linked a topics inside with accessibility guide, not external help page:
#: C/gnome-access-guide.xml:48(para)
msgid ""
"For further mouse- or pointer-based accessibility support, see the <link "
"linkend=\"mousetweaks\">MouseTweaks</link> and <link linkend=\"dtconfig-14"
"\">Configuring an Accessible Keyboard</link> sections. These tools supply "
"several accessibility aids for pointer devices and keyboards."

This link examples working with Mallard too? If yes, not need future opening old accessibility guide with Firefox.

The you suggested verbosity setting manual example is very good, thank you the commit.

I hope the link examples is working right, and this examples help you.

Attila

Attila, I could have sworn I tried:

 <link href="ghelp:gnome-access-guide>foo</link>

I guess I didn't. Thanks!!

Sadly it still looks odd, so I'm going to try to see if I can do something about that before I commit it. But it is displaying in Yelp for me now. Sweet!!

So, this style link working. Very nice!

Attila

(In reply to comment #13)
> So, this style link working. Very nice!

Yup! You totally rock. Pull from master and check it out.

In file help/C/howto_profiles.page, find the string of text, "will told." This should be changed to "will be told" to make proper sense.

What I'm about to report might need to go in a different bug.  What I notice since the changes to Mallard is while reading down the page, the only time I heard "link" spoken was for the intro guide at the top of the page.  As I read down the page with the down-arrow key, I just heard text including titles.  One might guess some of them would be links to select but Orca didn't speak "link" for any of those.  Now if I press tab or back-tab, then it would land on the appropriate links on down the page.  I also think there is a problem where links are not keeping up with current cursor position; this is the same thing I'm observing with Firefox 4.0 Betas.  What I mean with this is if you tab to a given link and then use down arrow to read on down the page past what are known links, pressing the tab key will take you to the next link that followed the last tab press.  It's like the arrowing through the document is not updating the current location to tab to the next link in line.  Anyway, the big thing here is links are not identified or spoken while arrowing through the document like is done on HTML documents in Firefox.

(In reply to comment #15)
> In file help/C/howto_profiles.page, find the string of text, "will told." This
> should be changed to "will be told" to make proper sense.

Proper sense is so, so totally overrated. <grins>

Thanks Steve. Changed in master!

(In reply to comment #16)
> What I'm about to report might need to go in a different bug.  

1. Yes to different bug
2. Assuming it goes into a bug at all.

> What I notice
> since the changes to Mallard is while reading down the page, the only time I
> heard "link" spoken was for the intro guide at the top of the page. As I read
> down the page with the down-arrow key, I just heard text including titles. 

The link is being exposed to us as the first child of the section. The link itself is not getting focus. That's presumably why we're not speaking it as a link.

> One
> might guess some of them would be links to select but Orca didn't speak "link"
> for any of those.

Yeah, and then one might press return on them thinking they'd definitely work, and there's an excellent chance one would be wrong.

> Now if I press tab or back-tab, then it would land on the
> appropriate links on down the page. 

Which is a decent interim solution, I think, given what I'm going to say momentarily.

> I also think there is a problem where
> links are not keeping up with current cursor position; this is the same thing
> I'm observing with Firefox 4.0 Betas. 

Yelp 2.x is Gecko-based, so this is not especially surprising. Yelp 3 will be WebKitGtk based. The way WebKitGtk does things is totally different from Gecko.

So I think the thing to do is wait until those WebKitGtk Yelps start becoming more widely available. Also note that I am soon going to re-setup my build environment. I'm currently in Natty broken dependency hell on my primary machine and want to finish up some work before I trash my system further. Then I can test Orca with the new Yelp.

Joanie, I found some issues with I not known already reported another user or not.
Now I not read detailed with this bugreport comments, because I yesterday done only old accessibility guide orca related translation merging and full actualizing the merged translations with the new documentation. I would like prewious finalizing this bigger task before christmas holiday, this is done now. Next year remaining now only 411 untranslated messages, with fit before final documentation release I think.
1. When I opening any help page, the next, further reading, see also etc strings are presenting untranslated now. Perhaps I not translated yet only this strings and this is change when the documentation translation is 100%?
You easy verify this if you activate Orca preferences dialog, and the general page press help button.

2. For example have some titles with the Orca application preferences help documentations. Not possible doing a heading level this titles to easyest the navigation? Or this is impossible or redundant work?
For example when I opening help content in Orca preferences dialog general page (clicking the help button), have some titles with not possible jumping with normal heading commands:
- Table navigation
- Speech
- Braille
- Key echo
Etc
Only possible activating this sections if I moving the Tab or Shift+Tab key with this section, but need listening the description field after the section title.
This is only 2.x Yelp problem and resolving with Yelp 3.0?
Or Mallard provide this style navigation?

3. Perhaps need correcting following text part with the documentation:
In the braille section the braille verbosity setting I found following text:
#: C/preferences_braille.page:97(p)
msgid ""
"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."

I newer see detailed Orca with braille display: When the braille page the verbose setting is selected, sure presenting the menues, controls mnemonics informations? Prewious have similar mistake with speech page verbosity setting with you already fixed related with shortcut key too if the verbose setting is selected with speech page verbosity setting.

4. Some questions, not an issue or bug:
When Orca final first stable version is release, and after this period any documentation translator found a bug or mistake the own language translation and update the documentation translation, this change updated automaticaly when next Orca maintenance version is awailable? For example, now have lot of language translators with not yet beginning translating the new documentation, only Spanish and hungarian language have partialy translated documentation. For example if other languages have not full done translated documentation when first Orca stable release is released, and before next maintenance version this languages finalized the translation, possible updating this translations before next maintenance version?
What date the original english documentation freeze and what the final date when possible reporting bugs with now awailable english documentation?

Iwish you happy christmas, and a happy new year!

Attila

Joanie, I found another issue with original documentation:
Have some missed typos with Orca keybinding commands paragraph, more with desktop layout keybinding commands, not have space after the colon character before the <key> or <keyseq> markups.
An example:
#: C/howto_orca_find.page:30(p) C/commands_find.page:30(p)
msgid "Desktop:<keyseq><key>KP Delete</key></keyseq>"

If need, the right future fixed line is following:
#: C/howto_orca_find.page:30(p) C/commands_find.page:30(p)
msgid "Desktop: <keyseq><key>KP Delete</key></keyseq>"

Usual, laptop style bindings not containing this type miss typos I think.
Need fixing this type bugs? If not fixed this bug, Yelp presenting this example with following wrong text?
Desktop: KP Delete
I don't possible testing this, because I translated all key bindings with hungarian language and putted space after colon character before markup command with hungarian translation with this day.

Attila

(In reply to comment #20)
> Joanie, I found another issue with original documentation:
> Have some missed typos with Orca keybinding commands paragraph, more with
> desktop layout keybinding commands, not have space after the colon character
> before the <key> or <keyseq> markups.

Ugh! And thanks to the miracle of copy and paste, I repeated the error over and over and over again. :-/ Thanks for catching those Attila!

http://git.gnome.org/browse/orca/commit/?id=61b4d3a51943dac3aa1e984506c9feeb0d063a5a

Hey Attila.

> 1. When I opening any help page, the next, further reading, see also etc
> strings are presenting untranslated now.

That is bug 630053. Since Gabor filed it, perhaps you and he have since touched base?

> 2. For example have some titles with the Orca application preferences help
> documentations. Not possible doing a heading level this titles to easyest the
> navigation? Or this is impossible or redundant work?

Well, main titles are Heading 1's. Section titles are Heading 2's. So you could get to Table Navigation, which is way down along the page, by pressing 2, 2, u, u. If I made each link a heading, that would change it to 2, 2, 3, 3. It's still 4 keystrokes. So I think that would make it redundant work because it wouldn't save you any time or keystrokes.
 
> 3. Perhaps need correcting following text part with the documentation:
> In the braille section the braille verbosity setting I found following text:
> #: C/preferences_braille.page:97(p)
> msgid ""
> "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."

I'll double check this and if need be, rewrite it. The funny thing is that instances where you have pointed out things as being factually/technically incorrect are things which came from our existing documentation in the Accessibility guide. :-/ I suppose it's a good thing we're going through it all now....

> 4. Some questions, not an issue or bug:
> When Orca final first stable version is release, and after this period any
> documentation translator found a bug or mistake the own language translation
> and update the documentation translation, this change updated automaticaly when
> next Orca maintenance version is awailable?

Yup. Now that Orca help is part of Orca, translations added to Orca (wherever they happen to be) get released as part of Orca.

> only Spanish and hungarian language have partialy translated documentation. For
> example if other languages have not full done translated documentation when
> first Orca stable release is released, and before next maintenance version this
> languages finalized the translation, possible updating this translations before
> next maintenance version?

I'll cross that bridge when we get to it. My temptation is to say that if there is a next maintenance version still, we'll just wait until that next maintenance version. However should we be done with all the maintenance versions and suddenly a bunch of translated help content gets committed, I would be more than happy to do a "special" additional release and ping distros so that the new upstream translations make it downstream.

> What date the original english documentation freeze and what the final date
> when possible reporting bugs with now awailable english documentation?

Right now I think that's up in the air. I had asked Shaun (doc team lead) if documentation were subject to the same string freezes as the UI. He said no. So my plan is to still pretend that we're under that freeze just so that I don't put stuff off to the last minute, and to ensure that the i18n team has as much time as possible before the release to tackle our new help content. But in terms of you getting back to me with documentation bugs, I think you've still got plenty of time. So please keep reading and reporting the errors. <smile>

> Iwish you happy christmas, and a happy new year!

Same to you Attila! Thanks for all your work!!

The braille issue is a bug in Orca's braille presentation. Plus, unlike with the Speech case, I cannot fix the docs by providing another example because there is no other example to provide. See bug 637884 for the braille issue. The docs will stand is they are for the moment.

To my knowledge, aside from making time to write the document and form field content, I'm caught up on all doc issues. If I missed a correction that needed to be made, please let me know.

Thanks!

Joanie, I agree your answer.
For example after the Application-Unique Preferences second heading level, the gecko navigation and table navigation topics is links, but I misunderstand this because Orca now not spokening the link role type text if I navigate this links with arrow keys.
Perhaps this is changing with Yelp webkit based 3.0 version.
When I using Tab key, Orca spokening the link word and spokening the descriptions (desc labelled short paragraphs).

Thank you the missed typos fixes.

I wish you happy christmas!

Attila

Joanie, I found two bugs with the documentation:
the documentation with dinamic headers related I see following paragraph, with I think possible are not full right:
#: C/howto_tables.page:135(p)
msgid ""
"To clear headers, simply double-click the command you used to set them. Thus "
"double-clicking <keyseq><key>Orca Modifier</key><key>R</key></keyseq> tells "
"<app>Orca</app> there are no row headers. Double-clicking <keyseq><key>Orca "
"Modifier</key><key>C</key></keyseq> tells <app>Orca</app> there are no "
"column headers."
If you looking prewious paragraphs, Orca modifyer+r setting dinamic column header with current table row, Orca modifyer+c setting dinamic row header with current column in a table if I understand right with english documentation.
So, if I known right, double press Orca modifyer+r delete column headers, double press Orca modifyer+c deleting row headers.
Look following learning mode messages:
#. Translators: Orca allows you to dynamically define which
#. row of a spreadsheet or table counts as column headers.
#.
#: ../src/orca/scripts/apps/soffice/script.py:247
msgid "Clears the dynamic column headers."

#. Translators: Orca allows you to dynamically define which
#. column of a spreadsheet or table counts as row headers.
#.
#: ../src/orca/scripts/apps/soffice/script.py:264
msgid "Clears the dynamic row headers"

Perhaps only need replacing the two type header word after the keystrokes, like following:
#: C/howto_tables.page:135(p)
msgid ""
"To clear headers, simply double-click the command you used to set them. Thus "
"double-clicking <keyseq><key>Orca Modifier</key><key>R</key></keyseq> tells "
"<app>Orca</app> there are no column headers. Double-clicking <keyseq><key>Orca "
"Modifier</key><key>C</key></keyseq> tells <app>Orca</app> there are no "
"row headers."
Or if the documentation is right, need replacing two header related keystrokes with Orca level, and modifying the prewious paragraphs in the documentation (r equals row headers, c equals column headers keystrokes are perhaps better).

I found a missed typo with following paragraph:
#: C/preferences_introduction.page:50(p)
msgid ""
"In contrast to Orca preferences, there are appliation-unique preferences. "
"These preferences allow you to customize <app>Orca</app> functionality that "
"only applies in certain environments, such as on web pages or in chat "
"applications. As a result, you will only find these options available in the "
"application-specific preferences dialogs and only for those applications to "
"which these options apply."
The problemis the appliation-unique word, application-unique is the right.

Attila

(In reply to comment #25)
 
> Perhaps only need replacing the two type header word after the keystrokes, like
> following:

Yup. Changed. No matter how hard I try, my brain is wired to get those backwards. Thanks for spotting that error!
 
> The problemis the appliation-unique word, application-unique is the right.
 
Indeed it is. Thanks for spotting that as well!

I seriously appreciate how closely you are going over all the content, Attila.

http://git.gnome.org/browse/orca/commit/?id=01c1232bfd07f562d9f19a02591d2dcd595e55b2

Joanie, thank you the fix commits.
I have got a question with keyboard layout documentation part section related, this is formatting specific:
How can you determining if in a section have subsections need gets a heading level format, for example a second heading level?
Look following title, with not have now heading level style:
#: C/howto_keyboard_layout.page:41(title)
msgid "Changing Your Keyboard Layout"

For example, if you look Orca introduction page, wonderful formatted the subsections with headings, this is very easying the navigation with a section the subsections, for example:
#: C/introduction.page:62(title)
msgid "Quitting <app>Orca</app>"
#: C/introduction.page:88(title)
msgid "Load-Time Options"
Very interesting, all I showed examples have title attribute, This is seeing for example the translation po files, but the "Changing Your Keyboard Layout" subsection not get automaticaly a heading level.
Why happening this, or what formatting tag determining this? I not see any extra tags with this examples.

If you going to http://library.gnome.org/users/orca/2.91 page, you see a difference with two section if you try navigating with normal h or Shift+h keyboard command with a section subsections.
Very good formatted document part for example is following:
http://library.gnome.org/users/orca/2.91/introduction.html
Perhaps missing subsection heading level formatting containing document part (my first example with top of the comment) is following:
http://library.gnome.org/users/orca/2.91/howto_keyboard_layout.html

Attila

Joanie, another example documentation section with perhaps need defining second heading levels with subsections:
http://library.gnome.org/users/orca/2.91/howto_key_bindings.html
Perhaps following subsections need second heading level formatting I think with howto_key_bindings.page XML file:
#: C/howto_key_bindings.page:21(title)
msgid "Binding an Unbound Command"

#: C/howto_key_bindings.page:58(title)
msgid "Changing Existing Bindings"

#: C/howto_key_bindings.page:90(title)
msgid "Restoring Original Bindings"

#: C/howto_key_bindings.page:112(title)
msgid "Unbinding Bound Commands"

Not matter if I writing this formatting related suggestions when I reviewing the translated hungarian documentation? Already reviewed sections full good with this formatting request related exception prewious comment wrote example section and this section.
Lot of redundant work resulting you doing this format requests? If yes, how can I possible helping you?

Attila

Profile related section is have similar missing second heading level formatting related problem, but this is now not interesting.
Please look following paragraphs, because this paragraphs is get a numbered steps with Yelp after following title:
#: C/howto_profiles.page:90(title)
msgid "Changing an Existing Profile"

#: C/howto_profiles.page:92(p)
msgid ""
"Follow the steps described above to load the profile you wish to change."

#: C/howto_profiles.page:97(p)
msgid "Follow the steps described above to save a new profile."

This two paragraph get a numbered simbol (1 and 2 step). After this two paragraph, I see following paragraph with a numbered 3 step number in Yelp for example:
#: C/howto_profiles.page:100(p)
msgid ""
"When prompted for the new profile name, type the same name as current "
"profile. When you press the <gui>OK</gui> button, you will be told there is "
"a name conflict."

This is right?

Attila

Attila, regarding all of the "it's not a heading" comments, thanks for identifying those. That is not something I am doing or not doing -- not explicitly anyway. If I mark something as a section title in mallard, it gets exposed to us as a heading; it seems that if I mark something as a steps title, it does not get marked as a heading.

I'm chatting with the doc team lead about this. But I think steps should be marked as steps and sections marked as sections. So we'll see what we can work out.

Update: Shaun is going to make them headings. That won't help us in Gecko/Yelp 2. But it will help us going forward.

(In reply to comment #29)
 
> This is right?

I feel like I'm missing something. I believe what is stated is right. I believe how it is marked up is right. Therefore, if you don't agree, please tell me very clearly and briefly what you think is wrong. Or alternatively, please give me a diff demonstrating what you would correct.

My apologies for failing to just "get it."

Joanie, I understand the difference now.
Look for example keyboard layout related before the steps describe paragraph title:
  <steps>
    <title>
      Changing Your Keyboard Layout
    </title>
Because next paragraph is a step describe, better I think following modification:
  <steps>
    <title>
      If you would like changing your keyboard layout, perform following steps:
    </title>
So, this difference tells the user this is not a new subsection, not an openable section, next paragraphs describe a steps an operation.
Need this because now Orca doesn't tells users if using arrow keys the openable sections, I reported this issue with bug 638645.

The diff make is standard way if I make a branch this bug, and attaching normal patch?

Attila

Created attachment 178385 [details] [review]
Fix patch for documentation

Joanie, please look the difference, and if my fix way is good, please commit the patch.
I little modifiing titles before steps descriptions with following documents, now this titles are better understable (have colons before step titles):
1. howto_keyboard_layout.page
2. howto_learn_modes.page
3. howto_key_bindings.page
4. howto_profiles.page

In profiles documentation I removed the description and title with the figure, and joined the figure description sentence with prewious paragraph, I think this is resulting the section text is better.
I modifyed the change existing profile section, now not presenting unneed item numbers before steps, and I hope this part is right now (all steps right presented when I read the modified version).
I fixed the wrong item number with last sentence the startup profile related.

Attila

I wrote wrong the prewious comment with following sentence, the right determining is following:
The before steps titles is easy differencing with normal titles, because have colons with end of this titles.

Comment on attachment 178385 [details] [review]
Fix patch for documentation

Attila, I did the step titles the way I did them on purpose. In addition, as I stated in an earlier comment, Shaun (the Doc Team lead and guy in charge of Mallard) is going to change things so that steps titles are headings just like section titles. As a result, what you propose means that users will find long sentences with colons instead of headings when they navigate. I'm sorry, but I am not accepting this change within our documentation. Let's instead wait for Shaun to make his change. Thanks!

Ok, I agree with section titles you wrote.
You partialy agree my profile documentation part doed modifications, except colons with step titles?
need doing following style modification after the "changing an existing profile" step title:
"1. Get in to the Orca preferences dialog.
2. Load the profile with you would like change settings.
3. Change settings with you would like.
4. Click save as button.
...
"
etc.

I doing a new diff what can I would like changing the profile documentation part, now the first two steps only containing following:
"1. Follow the steps described above to load the profile you wish to change.
2. Follow the steps described above to save a new profile."

But if this modification is full unneed your openion, I full agree.

Attila

Created attachment 178429 [details] [review]
An another profile documentation related modification

Joanie, please look this patch.
I doed following modifications with profile documentation:
In change existing profile section, I modified following think:
- I merged the load profile parts and partialy the save profile parts, this is resulting unneed the user scroll up if not remember the load profile parts and save profile partssteps.
Original documentation is containing following steps:
"1. Follow the steps described above to load the profile you wish to change.
2. Follow the steps described above to save a new profile.
3. When prompted for the new profile name, type the same name as current "
profile. When you press the OK button, you will be told there is a name conflict.
4. Press the Yes button to confirm you wish to overwrite the existing profile with the new settings."

My modification is following, I mistake the prewious patch the modifications this part related:
"Changing an existing profile settings and saving the existing profile name
1. Get in to the Orca preferences dialog box.
2. On the General page, select profile to load on the active profile combo box.
3. Press the load button.
4. You will be asked to confirm. Press the Yes button.
5. Change whatever settings you wish.
6. On the General page, press the Save As button. 
7. When prompted for the new profile name, type the same name as current profile. When you press the OK button, you will be told there is a name conflict.
8. Press the Yes button to confirm you wish to overwrite the existing profile with the new settings."
I doed this modification, because another parts with profile documentation is similar.

In "changing the Start-up profile part I removed the unneed item number with last sentence.

If you agree this modifications, I am very happy, but if not, I absolute agree if the purpose shorting the existing profile steps numbers. :-):-)

Created attachment 178495 [details] [review]
Important joined patch with containing some bug fixes

Joanie, this joined patch containing my yesterday doed profile documentation related modifications, and containing following importanter bug fixes with documentation related, this two another bug fix is absolute sure need:
- in help/C/preferences_general.page file not have <indent> and </indent> tag before and after the Orca startup profile combo box documentation.
This is resulting the start-up profile combo box documentation not displayed, now this is fixed.

- In preferences_magnifier.page file I fixed a wrong paragraph with related the cursor size setting.
Original paragraph containing following after cursor size section title:
"This value determines the size of the border in pixels."

Please review this patch. If the profile related modifications is not need your openion with howto_profiles.page file, I welcome doing a simple patch with containing only the two another sure need commit changes.

Attila

Created attachment 178499 [details] [review]
Joined patch with containing bug fixes

Joanie, I very hope this is my  final patch for documentation.
This patch containing all prewious doed important and optional modifications, and following new modification with same important and need committing:
In help/C/preferences_chat.page the "Speak messages from" radio button default value is wrong, original string is following, but this is not a check box:
"Default: checked"
I fixed this with following right information:
"Default: all channels

So, now my patch containing 3 important need committing modifications, and some optional profile documentation related modifications with help/C/howto_profiles.page file.
In the joined patch commit message I detailed wrote the modifications.

Joanie, if you have a very little time, possible reviewing my last patch and answer what I doed fixes and modifications you are agree and will be committing after if I need doing perhaps  you request modifications?

Only this bug fix committing missing, I full done another strings translation with Orca hungarian documentation, and only need reviewing the translation with hungarian translator coordinator before he committing the translation.

Hey Attila.

Because we are now in string change announcement period, I prefer to do any and all string changes at one time so that I can make one announcement. I will look at this before too long, along with other things requiring string changes. Thanks!

Joanie, thank you the answer.
I forgot the string change period.
My more changes resulting string change (for example the cursor size paragraph fix and chat documentation related fix), of course better announce all string change required fixes with one announcement.
The tag fixes is a different situation, because for example the start-up profile documentation strings is already present in preferences_general.page, only not presenting the screen because missing the <item and </item tag.
Before and after the paragraph.

Attila

Attila, I took a look at your patch:

1. In the future please don't include that huge a commit message.

2. Your change about "These options appear at the bottom of the ...." causes the figure to no longer have a title or a caption. I intentionally gave the figure a title and a caption. Therefore, for now I plan not accept that change.

3. The title "Changing an Existing Profile" means changing an existing profile. <smile> In order to change an existing profile, you must save that profile using the same name.  In other words, saving the profile is a step. It doesn't belong in the title. In this same section, you re-wrote out steps which are displayed above. The reason I chose not to do that was because I was trying to make a point: The first step is to load the profile. You should already know how to do that because the steps are described above. The second step is to save the new profile. You should already know how to do that because the steps are described above. The important difference -- really the only thing users should care about in this section is the following: You're going to be given a dialog stating there is a conflict. Therefore, for now I plan not to accept that change.

4. I see your point about "The next time you launch Orca is not a step." The thing is, your change moves it outside the step block which visually looks funny. And since our documentation is designed also for developer testing with Orca and possibly sighted teachers and trainers, the funny-factor should be avoided. Therefore, I combined that sentence with the previous step.

The default value thing and the cursor/border thing were a copy and paste errors. Thanks for catching them. I've made those changes. Ditto on the missing item tags. 

http://git.gnome.org/browse/orca/commit/?id=15c841c4f3852e8cffe44973c5ad2846be8422f3

Comment on attachment 178499 [details] [review]
Joined patch with containing bug fixes

Obsoleted by this commit:

http://git.gnome.org/browse/orca/commit/?id=15c841c4f3852e8cffe44973c5ad2846be8422f3

Joanie, many thanks the detailed comment and commit the possible fixes.
You wrote:
"2. Your change about "These options appear at the bottom of the ...." causes
the figure to no longer have a title or a caption. I intentionally gave the
figure a title and a caption. Therefore, for now I plan not accept that change."
Full agree. In future for example the next development version possible merging this figure desc sentence with prewious paragraph? Now seeing the figure title (managing multiple configurations), and after this following what place found the user with profile related settings with a shord desc field.
How can looking my this related modification visual, very not beautiful? I only see when reading Orca my modified profile documentation hawe a right continous readable text.

"4. I see your point about "The next time you launch Orca is not a step." The
thing is, your change moves it outside the step block which visually looks
funny. And since our documentation is designed also for developer testing with
Orca and possibly sighted teachers and trainers, the funny-factor should be
avoided. Therefore, I combined that sentence with the previous step."
Full agree. Absolute good now, very sorry I not see how looking visual my prewious doed modification this related. I see only my last sentence have a new paragraph with not have right unneed step number. :-):-)

Attila