NVDA Settings Documentation


Quentin Christensen
 

David,

Those questions about using shorter lines and justifying them are all visual layout things you might do in the HTML code itself to make text stand out.  The line length in NVDA's browse mode settings is purely about the maximum amount of text NVDA will read each time you press the down arrow when reading a web page.  If the line is shorter, then it just reads to the end of the line.  NVDA doesn't change how anything appears visually.

Re Word, no it doesn't use NVDA's maximum line length in Browse mode.  Without looking at the code, my off the top of my head guess is because it doesn't need to use a virtual document for Word because the caret can move around the text just fine.  In a web browser, NVDA take the information from the browser and presents its own virtual representation of that (again, not changing what is shown on screen, and this is why sometimes users have found that NVDA can be at a point on a web page not visible on screen - although we regularly work to improve that synchronisation, and I'm not sure if it is still an issue actually).

Quentin.

On Fri, Oct 23, 2020 at 9:42 AM Gene <gsasner@...> wrote:
If the app uses browse mode, use page layout means that a page will be
formatted more the way a sighted user would see it.  The one instance I am
aware of is that if you don't use page layout, more than one link may be
shown on a line or I believe a link may be on the same line as nonlink text.
I don't use page layout because I want links each to be on their own lines.

Gene
-----Original Message-----
From: Robert Logue
Sent: Thursday, October 22, 2020 5:34 PM
To: nvda@nvda.groups.io
Subject: Re: [nvda] NVDA Settings Documentation

This is so helpful.  I've wondered about these settings for a while but
didn't look at the documentation.

I just tried setting the line length to 40 which actually is helpful in this
web mail web app.

Now I'm curious how the line and page length settings are effected by use
page layout...

Thanks Gene.


Bob

----- Original Message -----
From: "Gene" <gsasner@...>
To: nvda@nvda.groups.io
Sent: Monday, October 19, 2020 6:03:12 PM
Subject: Re: [nvda] NVDA Settings Documentation

It might be a good idea to add that when moving by line in a web page
looking for something, the user might want to make the lines shorter so that
you don't have to listen to long lines of text to make sure you haven't
missed the information when you move to another line.











--
Quentin Christensen
Training and Support Manager


Gene
 

If the app uses browse mode, use page layout means that a page will be formatted more the way a sighted user would see it. The one instance I am aware of is that if you don't use page layout, more than one link may be shown on a line or I believe a link may be on the same line as nonlink text. I don't use page layout because I want links each to be on their own lines.

Gene

-----Original Message-----
From: Robert Logue
Sent: Thursday, October 22, 2020 5:34 PM
To: nvda@nvda.groups.io
Subject: Re: [nvda] NVDA Settings Documentation

This is so helpful. I've wondered about these settings for a while but didn't look at the documentation.

I just tried setting the line length to 40 which actually is helpful in this web mail web app.

Now I'm curious how the line and page length settings are effected by use page layout...

Thanks Gene.


Bob

----- Original Message -----
From: "Gene" <gsasner@gmail.com>
To: nvda@nvda.groups.io
Sent: Monday, October 19, 2020 6:03:12 PM
Subject: Re: [nvda] NVDA Settings Documentation

It might be a good idea to add that when moving by line in a web page
looking for something, the user might want to make the lines shorter so that
you don't have to listen to long lines of text to make sure you haven't
missed the information when you move to another line.


Gene
 

The item is identified as maximum line length. It means that a line longer than the maximum number of carachters the function is set for will begin a new line at about the point of the maximum letters. If a line is shorter, it will be unaffected. Since words are not broken, this will mean the the maximum line length isn't exact. But note carefully that we are talking about a browse mode setting.

Web pages usually don't have line breaks. So you are telling the screen-reader how long to make the maxsimum line. there is a default setting, of course, but I can think of a circumstance where I might want to change it. I discussed this before as a means of skimming by line more efficiently by having shorter lines.

An interesting question is whether this setting is used in Microsoft Word if you turn on browse mode. As I understand it, you can use browse mode in a word document to do some things more efficiently than if you are just working with the document directly. Does browse mode in word break lines where soft returns are in a document or at a setting like maximum line length?

Gene

-----Original Message-----
From: Dave Grossoehme
Sent: Thursday, October 22, 2020 5:06 PM
To: nvda@nvda.groups.io
Subject: Re: [nvda] NVDA Settings Documentation



Good Day: What happens if there is a shorter line than normal in the middle of your text somewhere, or if the page has a horizontal line to divide the text? I think there is more to this than what the first idea came out to be. That's why you need to identifiy everything. That's why my programming instructors pointed out in more detail, than I can ever express.

Dave




On 10/20/2020 8:53 AM, Brian Vogel wrote:
On Mon, Oct 19, 2020 at 10:32 PM, Gene wrote:
I would compare it to Word Wrap in Notepad except that you define the number of characters before the wrap occurs.-
Gene, that is a good analogy. But what I want to know is what "reading command context(s)" this has an effect on. I'm imagining only line-by-line reading, but . . .

Having something under the setting such as, "If a document has a line longer than the number of characters you set, for line reading it will be split into multiple virtual lines of the maximum length you specify."

I also wonder if it's intelligent as far as splitting at word boundaries, not hard and fast character counts. Mid-word splits would make things potentially very ugly.

That setting, naked as it is, is not something that's intuitive, clearly, just based on this topic. And I'm not saying that you're arguing that it is, just restating the need for some context regarding settings where the effect of same is in no way immediately obvious to the uninitiated (and even the initiated, much later on).

--


Brian - Windows 10 Pro, 64-Bit, Version 2004, Build 19041

It’s hard waking up and realizing it’s not always black and white.

~ Kelley Boorn


Robert Logue
 

This is so helpful. I've wondered about these settings for a while but didn't look at the documentation.

I just tried setting the line length to 40 which actually is helpful in this web mail web app.

Now I'm curious how the line and page length settings are effected by use page layout...

Thanks Gene.


Bob

----- Original Message -----
From: "Gene" <gsasner@gmail.com>
To: nvda@nvda.groups.io
Sent: Monday, October 19, 2020 6:03:12 PM
Subject: Re: [nvda] NVDA Settings Documentation

It might be a good idea to add that when moving by line in a web page
looking for something, the user might want to make the lines shorter so that
you don't have to listen to long lines of text to make sure you haven't
missed the information when you move to another line.


 

Hi,
As for that, I'm not sure.
Cheers,
Joseph

-----Original Message-----
From: nvda@nvda.groups.io <nvda@nvda.groups.io> On Behalf Of Dave Grossoehme
Sent: Thursday, October 22, 2020 3:16 PM
To: nvda@nvda.groups.io
Subject: Re: [nvda] NVDA Settings Documentation

Joseph: Does that account for compound and/or hyphenized words?

Dave


On 10/20/2020 9:48 AM, Joseph Lee wrote:
Hi,
Had to dig into C++ part of NvDA to figure this out:
This setting sets browse mode line length, so yes, it applies to when reading by line. Specifically, based on what I can tell, it will do its best to break at word boundaries. This is one of the reasons why links can "span" across multiple lines in browse mode.
In terms of documenting this, one way to improve this is taking Brian's suggestions into account: expand that section and give practical examples, like the following:

This field sets the maximum length of a line in browse mode (in characters) for reading by line purposes.
Unlike documents in programs such as Word and Notepad, browse mode documents do not have a specific line length or a new line character to denote ends of lines.
Because of this, you can set arbitrary line lengths between 10 and 250 characters, and NVDA will try to split lines at word boundaries.
A side effect of this setting is that links and other elements will be split onto multiple browse mode lines.

I'm sure we can make it better, but at least the one I wrote above might be a useful starting point and captures the discussion so far.
Cheers,
Joseph



-----Original Message-----
From: nvda@nvda.groups.io <nvda@nvda.groups.io> On Behalf Of Gene
Sent: Tuesday, October 20, 2020 9:23 AM
To: nvda@nvda.groups.io
Subject: Re: [nvda] NVDA Settings Documentation

We'll see what others say but I know it applies to moving by lines. If I do something else that causes a line to be read, such as move by screen, with page up or down, or move to beginning or end of a document or tab, I would think it would apply in all those contexts, but we'll see what others say.

The intelligent question is a very interesting one and One I haven't thought of. Based on my experience, I don't recall ever having words split when I read in browse mode and the document has no such splitting, I think it is intelligent.

Just how much of such discussions should be in the user guide depends on what the purpose of the guide is. Perhaps some of these stipulations should be in some sort of document for developers or a wiki rather than in a user guide.

I wonder if this or that effect of a command my not be considered when discussing it by those who really know details. A wiki might be a good way to address this. I just found this very interesting discrepancy:
If I set the line length to a short amount, moving using k to move by link will cause an entire link to be read, no matter how long. Moving by arrow or tab and shift tab, will cause the line length stipulated to be read with more of the link being read as I move in the link. Its an interesting discrepancy and one I wonder if those knowledgeable in the matter have given any thought about as to implementation and what is desirable.

Gene
-----Original Message-----
From: Brian Vogel
Sent: Tuesday, October 20, 2020 10:53 AM
To: nvda@nvda.groups.io
Subject: Re: [nvda] NVDA Settings Documentation

On Mon, Oct 19, 2020 at 10:32 PM, Gene wrote:
I would compare it to Word Wrap in Notepad except that you define the number of characters before the wrap occurs.- Gene, that is a good analogy. But what I want to know is what "reading command context(s)" this has an effect on. I'm imagining only line-by-line reading, but . . .

Having something under the setting such as, "If a document has a line longer than the number of characters you set, for line reading it will be split into multiple virtual lines of the maximum length you specify."

I also wonder if it's intelligent as far as splitting at word boundaries, not hard and fast character counts. Mid-word splits would make things potentially very ugly.

That setting, naked as it is, is not something that's intuitive, clearly, just based on this topic. And I'm not saying that you're arguing that it is, just restating the need for some context regarding settings where the effect of same is in no way immediately obvious to the uninitiated (and even the initiated, much later on).


Dave Grossoehme
 

Joseph:  Does that account for compound and/or hyphenized words?

Dave

On 10/20/2020 9:48 AM, Joseph Lee wrote:
Hi,
Had to dig into C++ part of NvDA to figure this out:
This setting sets browse mode line length, so yes, it applies to when reading by line. Specifically, based on what I can tell, it will do its best to break at word boundaries. This is one of the reasons why links can "span" across multiple lines in browse mode.
In terms of documenting this, one way to improve this is taking Brian's suggestions into account: expand that section and give practical examples, like the following:

This field sets the maximum length of a line in browse mode (in characters) for reading by line purposes.
Unlike documents in programs such as Word and Notepad, browse mode documents do not have a specific line length or a new line character to denote ends of lines.
Because of this, you can set arbitrary line lengths between 10 and 250 characters, and NVDA will try to split lines at word boundaries.
A side effect of this setting is that links and other elements will be split onto multiple browse mode lines.

I'm sure we can make it better, but at least the one I wrote above might be a useful starting point and captures the discussion so far.
Cheers,
Joseph



-----Original Message-----
From: nvda@nvda.groups.io <nvda@nvda.groups.io> On Behalf Of Gene
Sent: Tuesday, October 20, 2020 9:23 AM
To: nvda@nvda.groups.io
Subject: Re: [nvda] NVDA Settings Documentation

We'll see what others say but I know it applies to moving by lines. If I do something else that causes a line to be read, such as move by screen, with page up or down, or move to beginning or end of a document or tab, I would think it would apply in all those contexts, but we'll see what others say.

The intelligent question is a very interesting one and One I haven't thought of. Based on my experience, I don't recall ever having words split when I read in browse mode and the document has no such splitting, I think it is intelligent.

Just how much of such discussions should be in the user guide depends on what the purpose of the guide is. Perhaps some of these stipulations should be in some sort of document for developers or a wiki rather than in a user guide.

I wonder if this or that effect of a command my not be considered when discussing it by those who really know details. A wiki might be a good way to address this. I just found this very interesting discrepancy:
If I set the line length to a short amount, moving using k to move by link will cause an entire link to be read, no matter how long. Moving by arrow or tab and shift tab, will cause the line length stipulated to be read with more of the link being read as I move in the link. Its an interesting discrepancy and one I wonder if those knowledgeable in the matter have given any thought about as to implementation and what is desirable.

Gene
-----Original Message-----
From: Brian Vogel
Sent: Tuesday, October 20, 2020 10:53 AM
To: nvda@nvda.groups.io
Subject: Re: [nvda] NVDA Settings Documentation

On Mon, Oct 19, 2020 at 10:32 PM, Gene wrote:
I would compare it to Word Wrap in Notepad except that you define the number of characters before the wrap occurs.- Gene, that is a good analogy. But what I want to know is what "reading command context(s)" this has an effect on. I'm imagining only line-by-line reading, but . . .

Having something under the setting such as, "If a document has a line longer than the number of characters you set, for line reading it will be split into multiple virtual lines of the maximum length you specify."

I also wonder if it's intelligent as far as splitting at word boundaries, not hard and fast character counts. Mid-word splits would make things potentially very ugly.

That setting, naked as it is, is not something that's intuitive, clearly, just based on this topic. And I'm not saying that you're arguing that it is, just restating the need for some context regarding settings where the effect of same is in no way immediately obvious to the uninitiated (and even the initiated, much later on).


 

On Thu, Oct 22, 2020 at 06:06 PM, Dave Grossoehme wrote:
That's why my programming instructors pointed out in more detail, than I can ever express.
-
A) You are making this way more complicated than it actually is.
B) Descriptions are not meant to be exhaustive, but illustrative.  You do not attempt to put every condition handled gracefully by a piece of software in the user documentation or settings panels.  There is a balance to be struck, and if it's a choice between "short and sweet" or "long and hard to comprehend" the former is the correct choice for end user documentation in every instance.
 
--

Brian - Windows 10 Pro, 64-Bit, Version 2004, Build 19041  

It’s hard waking up and realizing it’s not always black and white.

     ~ Kelley Boorn

 


Dave Grossoehme
 

Good Day:  What happens if there is a shorter line than normal in the middle of your text somewhere, or if the page has a horizontal line to divide the text?  I think there is more to this than what the first idea came out to be.  That's why you need to identifiy everything.  That's why my programming instructors pointed out in more detail, than I can ever express.

Dave


On 10/20/2020 8:53 AM, Brian Vogel wrote:
On Mon, Oct 19, 2020 at 10:32 PM, Gene wrote:
I would compare it to Word Wrap in Notepad except that you define the number of characters before the wrap occurs.
-
Gene, that is a good analogy.  But what I want to know is what "reading command context(s)" this has an effect on.  I'm imagining only line-by-line reading, but . . .

Having something under the setting such as, "If a document has a line longer than the number of characters you set, for line reading it will be split into multiple virtual lines of the maximum length you specify."

I also wonder if it's intelligent as far as splitting at word boundaries, not hard and fast character counts.  Mid-word splits would make things potentially very ugly.

That setting, naked as it is, is not something that's intuitive, clearly, just based on this topic.  And I'm not saying that you're arguing that it is, just restating the need for some context regarding settings where the effect of same is in no way immediately obvious to the uninitiated (and even the initiated, much later on).
 
--

Brian - Windows 10 Pro, 64-Bit, Version 2004, Build 19041  

It’s hard waking up and realizing it’s not always black and white.

     ~ Kelley Boorn

 


Dave Grossoehme
 

Good Day:  My first thought is if you wish to have a block of text stand out, and you want it to spand out to the left, right, or both left and right, but still be centered.  There could be other times for this for a block of text, but getting in to the different options which might even get into different programming coding layouts.

Dave


On 10/20/2020 1:44 AM, Pranav Lal wrote:

Hi all,

<snip I guess when working out where best to add information, what would you suggest needs adding?  That seems to describe the feature to me, but maybe I am too familiar with it to see what is missing?

PL] When would I want to alter this setting?

 

Pranav


Dave Grossoehme
 

Good Day:  Is the limit, the number of characters possible on a line, such as 66 characters use to be the limit in the dos days.  Or the limit number count as many characters that can be placed in a computer screen, or is it limited to a computer page size on the screen?  It might be nice to know what general applications this action is good for.

Dave


On 10/19/2020 4:45 PM, Brian Vogel wrote:
Quentin,

         Here's some input in the form of questions.

         What constitutes a line?

          Does the maximum number of characters result in truncation and, if so, under what reading conditions?  (I can't imagine this setting affects read all behavior, for instance).

          If a line (after defined) is longer than that maximum, what happens when that occurs during browse mode?

--

Brian - Windows 10 Pro, 64-Bit, Version 2004, Build 19041  

It’s hard waking up and realizing it’s not always black and white.

     ~ Kelley Boorn

 


Quentin Christensen
 

Off the top of my head, this doesn't work in Word, because as you down arrow to move by line, the caret DOES move down a line, and so NVDA reads the next line (that behaviour is the same in focus or browse mode).  Using the Move to next line in review command (numpad 9 or NVDA+down arrow) also moves to the next actual line.


On Thu, Oct 22, 2020 at 8:41 AM Dave Grossoehme <dave@...> wrote:
Good |Day:  This brings a question to mind on this setting. Would that
work for a line in Word, if wrap is turned on?  Which a line of text
that continues to wrap.

Dave


On 10/19/2020 2:14 AM, Gene wrote:
> I haven't looked at the user guide a lot.  However, I found yesterday,
> regarding the line length documentation this:
> 12.1.14. Browse Mode (NVDA+control+b)
> The Browse Mode category in the NVDA Settings dialog is used to
> configure NVDA's behaviour when you read and navigate complex
> documents such as web pages. This category contains the following
> options:
> Maximum Number of Characters on One Line
> This field sets the maximum length of a line in browse mode (in
> characters).
>
> That's true but how many people would understand where it might be
> useful? I found the same feature useful in JAWS years ago becaused
> when I moved from line to line manually, the lines as displayed were
> too long to find something conveniently.  I wanted lines shorter so I
> could skim by line much faster and more efficiently.
>
> There are two things that come to mind:
> When browse mode is discussed earlier, should the section that shows
> the settings with explanation be referenced as a further information
> or see also, or for settings, see or something of the sort?  Also, is
> this section and some other parts of the user guide intended for those
> who already have an idea of how such settings might be used in general
> or for a more advanced user who may either understand the information
> or play around and see what the effect is of settings information that
> isn't clear.
>
> Manuals, in my experience are usually concise and I think that is one
> reason tutorials are so much more popular.   But the degree of
> concision may be opened to useful discussion.
>
> Gene
> -----Original Message----- From: Quentin Christensen
> Sent: Monday, October 19, 2020 4:01 AM
> To: nvda@nvda.groups.io
> Subject: Re: [nvda] NVDA Settings Documentation
>
>
> Hi everyone,
>
> Lots of good points here.  So firstly, from a very simplistic view -
> if there are any settings which experienced people such as yourselves
> can't get an explanation of from the User Guide, then that's
> definitely something we should address.  Please either let me know (or
> file a GitHub issue) as you find examples.
>
> Re the user guide being too thick and heavy for new users to get start
> with - that's largely because that's not who it is really aimed at. 
> For a lot of users, the Basic Training for NVDA would be the best
> place to start. There is potentially a gap for a short "quick start"
> guide, and I'd be happy to explore that further with anyone who has
> ideas on the subject.
>
> Joseph, re some sort of training for new contributors - that too is a
> great idea, and I'd be happy to work further with you on it.
>
> I've made a note to follow all of this up (since it's into the evening
> here and I'm trying to figure out book week costumes while getting the
> kids to bed).
>
>
> On Mon, Oct 19, 2020 at 10:44 AM Robert Doc Wright godfearer
> <godfearer@...> wrote:
>
> Where I need direction on what I need to study in order to be a tech
> writer for NVDA. I believe that once I understand something I can
> teach it to anyone. My stumbling block is that I have had some
> programming classes but that was twenty years ago. I taught myself
> basic web design from a book. What do I need to know to be of help
> where the users guide is concerned?
> ******
> Jesus says, follow me and I'll help you through the rough spots.
> the world says, hey come with me. My way is broad and easy. So what if
> you get crap on your shoes. You can always wash it off, can't you!
>
>
> Family times where there is fun for every ear!
> http://stream.wrighthere.net:8000/stream.mp3
>
> Or ask your A device to play Family times on tuneIn
> You can also find us on your mobile device install OoTunes and search
> for Family times
> ----- Original Message ----- From: Joseph Lee
> To: nvda@nvda.groups.io
> Sent: Sunday, October 18, 2020 1:45 PM
> Subject: Re: [nvda] NVDA Settings Documentation
>
>
> Hi,
>
> Agreed (that’s one of the reasons why I comment a lot in my add-on
> source code).
>
> One holiday wish I have (possibly a long-term wish) is to help folks
> get started on revamping the NVDA community documentation. At least
> this can include add-on user guides, but I foresee a day where the
> screen reader user guide would not escape this rewrite in hopes of
> making it more relevant for users. I would go so far as ask NVDA code
> contributors to add extensive documentation in source code itself – it
> is now possible to do it easily with help from a module called Sphinx,
> a source code based documentation generator. There are major issues to
> consider, however:
>
> Who is the target audience: thinking about this changes the game, as
> it will dictate tone, style, word usage, and organization of the
> document and supplemental materials.
> Mindset of code contributors: are we just software developers or
> technical authors? Some people would argue that developers should
> focus on programming and testing, leaving the task of documenting what
> developers wrote to technical authors, and this separation of concerns
> may foster better communication amongst team members. On the other
> hand, by forcing developers to become technical authors, they can make
> crucial decisions about the user-visible aspects of a given product a
> bit early.
> How can we show we accept diversity in terms of culture, language,
> skill level, and other factors: although the community documentation
> was written by NV Access people at first, it is increasingly written
> by people from diverse backgrounds in terms of culture, language,
> skill level, and other factors (although I did receive training on
> technical communication and software development, I’m not a native
> English speaker). This is more so for parts that are written by people
> who may have different interpretation about a UI message or concepts,
> more so if the author’s native language is not English (the reverse is
> true for translators as they need to grasp concepts written in English
> in their native languages).
>
>
>
> My responses to the above questions are:
>
> Who is the target audience: it varies. For NVDA user guide, it is
> users with differing skill levels. For add-on guides, they target end
> users. For this reason, whenever I edit the NVDA user guide or add-on
> guides, I think about what users expect and NVDA’s response. This
> changes if we’re dealing with a document meant for developers (such as
> add-on internals and such).
> Mindset of code contributors: I believe that, as much as programming
> skills is important, willingness to communicate with audiences (users,
> other contributors, industry experts, etc.) is also important. One way
> to practice both is thinking and writing to and about users, therefore
> I tend to fall into a bit of the latter category from above:
> programming is, in one way or another, writing. Python is just one of
> the more specialized languages used to communicate with another entity
> (the machine), and if one can teach a computer to do something (along
> with fixing mistakes), it would be possible to train developers to
> respect users more by writing good documentation (of course someone
> may need to look at the documentation for style and such). My
> philosophy partly stems from my experiences as a former computer
> science major at a college I attended (different from the one I’m
> about to graduate from): my first computer science professor stressed
> the importance of source code comments and documentation, and I still
> practice this lesson today, which fuels my overall frustration with
> the current state of NVDA user guide and source code documentation in
> general. I think one exercise code contributors can do before
> submitting anything to GitHub (specifically, pull; requests) is
> writing an early user facing documentation, because doing so helps you
> improve your writing skills and think carefully about the impact of
> your changes when users meet them (I sometimes find myself struggling
> for minutes to hours over UI messages and documentation for this
> reason; I know what my code will do, but I hit a roadblock when
> explaining what I’ve done to would-be users before actually writing
> code).
> How can we show we are a group of people coming from diverse
> backgrounds: I think this goal was somewhat achieved when we look at
> recent NVDA work – many new features and bug fixes included in NVDA
> 2020.3 were written by someone other than an NV Access staff member,
> from people living in different countries and speaking many languages.
> But I know that we can improve on that somehow.
>
>
>
> Another wish I have, mostly for Quentin: can we develop some sort of a
> training program for would-be contributors wishing to improve the
> overall NVDA community documentation, including the user guide? It may
> include basics on technical writing, tone and style, audience
> analysis, exercises where coding and documentation should be done
> together, and documentation production in a variety of formats
> (including online media). I think this may help us dive deeper into
> user guide issues being brought up, including the guide being “too
> thick” for newbies (in terms of understanding, lack of solid examples,
> and friendliness), especially for preferences chapter.
>
> Cheers,
>
> Joseph
>
>
>
>
>
>
>
>
>
> From: nvda@nvda.groups.io <nvda@nvda.groups.io> On Behalf Of Brian Vogel
> Sent: Sunday, October 18, 2020 11:56 AM
> To: nvda@nvda.groups.io
> Subject: Re: [nvda] NVDA Settings Documentation
>
>
>
>
>
> Joseph,
>
>           While I applaud your efforts, and tutorials are invaluable,
> I wasn't even going that far.  I'm talking basic documentation, where
> each item in a panel/pane/settings group in a given pane are briefly
> documented. There are myriad NVDA settings that, if their actual
> function is not directly obvious, which is the case, for example, with
> most checkboxes, then they're a black hole.
>
>            Even I will admit that for all software it is a limited
> number of end users who refer to this sort of thing.  That being said,
> some do, and it serves as a very important basis for new developers to
> develop depth of knowledge of "what's in there and what it's for."
>
>             I was just commenting to someone for whom I've done custom
> VBA scripting for Outlook that I am eternally grateful to myself for
> having developed the habit of rigorously commenting my code, at a bare
> minimum, as even I would have no idea what some of what I've written
> actually does when looking at it much later. Complex stuff doesn't
> remain in "off the top of my head" mode (for most "mes") as time moves
> on.  That's one of the reasons that basic documentation is so important.







--
Quentin Christensen
Training and Support Manager


Dave Grossoehme
 

Good |Day:  This brings a question to mind on this setting. Would that work for a line in Word, if wrap is turned on?  Which a line of text that continues to wrap.

Dave

On 10/19/2020 2:14 AM, Gene wrote:
I haven't looked at the user guide a lot.  However, I found yesterday, regarding the line length documentation this:
12.1.14. Browse Mode (NVDA+control+b)
The Browse Mode category in the NVDA Settings dialog is used to configure NVDA's behaviour when you read and navigate complex documents such as web pages. This category contains the following options:
Maximum Number of Characters on One Line
This field sets the maximum length of a line in browse mode (in characters).

That's true but how many people would understand where it might be useful? I found the same feature useful in JAWS years ago becaused when I moved from line to line manually, the lines as displayed were too long to find something conveniently.  I wanted lines shorter so I could skim by line much faster and more efficiently.

There are two things that come to mind:
When browse mode is discussed earlier, should the section that shows the settings with explanation be referenced as a further information or see also, or for settings, see or something of the sort?  Also, is this section and some other parts of the user guide intended for those who already have an idea of how such settings might be used in general or for a more advanced user who may either understand the information or play around and see what the effect is of settings information that isn't clear.

Manuals, in my experience are usually concise and I think that is one reason tutorials are so much more popular.   But the degree of concision may be opened to useful discussion.

Gene
-----Original Message----- From: Quentin Christensen
Sent: Monday, October 19, 2020 4:01 AM
To: nvda@nvda.groups.io
Subject: Re: [nvda] NVDA Settings Documentation


Hi everyone,

Lots of good points here.  So firstly, from a very simplistic view - if there are any settings which experienced people such as yourselves can't get an explanation of from the User Guide, then that's definitely something we should address.  Please either let me know (or file a GitHub issue) as you find examples.

Re the user guide being too thick and heavy for new users to get start with - that's largely because that's not who it is really aimed at.  For a lot of users, the Basic Training for NVDA would be the best place to start. There is potentially a gap for a short "quick start" guide, and I'd be happy to explore that further with anyone who has ideas on the subject.

Joseph, re some sort of training for new contributors - that too is a great idea, and I'd be happy to work further with you on it.

I've made a note to follow all of this up (since it's into the evening here and I'm trying to figure out book week costumes while getting the kids to bed).


On Mon, Oct 19, 2020 at 10:44 AM Robert Doc Wright godfearer <godfearer@comcast.net> wrote:

Where I need direction on what I need to study in order to be a tech writer for NVDA. I believe that once I understand something I can teach it to anyone. My stumbling block is that I have had some programming classes but that was twenty years ago. I taught myself basic web design from a book. What do I need to know to be of help where the users guide is concerned?
******
Jesus says, follow me and I'll help you through the rough spots.
the world says, hey come with me. My way is broad and easy. So what if you get crap on your shoes. You can always wash it off, can't you!


Family times where there is fun for every ear!
http://stream.wrighthere.net:8000/stream.mp3

Or ask your A device to play Family times on tuneIn
You can also find us on your mobile device install OoTunes and search for Family times
----- Original Message ----- From: Joseph Lee
To: nvda@nvda.groups.io
Sent: Sunday, October 18, 2020 1:45 PM
Subject: Re: [nvda] NVDA Settings Documentation


Hi,

Agreed (that’s one of the reasons why I comment a lot in my add-on source code).

One holiday wish I have (possibly a long-term wish) is to help folks get started on revamping the NVDA community documentation. At least this can include add-on user guides, but I foresee a day where the screen reader user guide would not escape this rewrite in hopes of making it more relevant for users. I would go so far as ask NVDA code contributors to add extensive documentation in source code itself – it is now possible to do it easily with help from a module called Sphinx, a source code based documentation generator. There are major issues to consider, however:

Who is the target audience: thinking about this changes the game, as it will dictate tone, style, word usage, and organization of the document and supplemental materials.
Mindset of code contributors: are we just software developers or technical authors? Some people would argue that developers should focus on programming and testing, leaving the task of documenting what developers wrote to technical authors, and this separation of concerns may foster better communication amongst team members. On the other hand, by forcing developers to become technical authors, they can make crucial decisions about the user-visible aspects of a given product a bit early.
How can we show we accept diversity in terms of culture, language, skill level, and other factors: although the community documentation was written by NV Access people at first, it is increasingly written by people from diverse backgrounds in terms of culture, language, skill level, and other factors (although I did receive training on technical communication and software development, I’m not a native English speaker). This is more so for parts that are written by people who may have different interpretation about a UI message or concepts, more so if the author’s native language is not English (the reverse is true for translators as they need to grasp concepts written in English in their native languages).



My responses to the above questions are:

Who is the target audience: it varies. For NVDA user guide, it is users with differing skill levels. For add-on guides, they target end users. For this reason, whenever I edit the NVDA user guide or add-on guides, I think about what users expect and NVDA’s response. This changes if we’re dealing with a document meant for developers (such as add-on internals and such).
Mindset of code contributors: I believe that, as much as programming skills is important, willingness to communicate with audiences (users, other contributors, industry experts, etc.) is also important. One way to practice both is thinking and writing to and about users, therefore I tend to fall into a bit of the latter category from above: programming is, in one way or another, writing. Python is just one of the more specialized languages used to communicate with another entity (the machine), and if one can teach a computer to do something (along with fixing mistakes), it would be possible to train developers to respect users more by writing good documentation (of course someone may need to look at the documentation for style and such). My philosophy partly stems from my experiences as a former computer science major at a college I attended (different from the one I’m about to graduate from): my first computer science professor stressed the importance of source code comments and documentation, and I still practice this lesson today, which fuels my overall frustration with the current state of NVDA user guide and source code documentation in general. I think one exercise code contributors can do before submitting anything to GitHub (specifically, pull; requests) is writing an early user facing documentation, because doing so helps you improve your writing skills and think carefully about the impact of your changes when users meet them (I sometimes find myself struggling for minutes to hours over UI messages and documentation for this reason; I know what my code will do, but I hit a roadblock when explaining what I’ve done to would-be users before actually writing code).
How can we show we are a group of people coming from diverse backgrounds: I think this goal was somewhat achieved when we look at recent NVDA work – many new features and bug fixes included in NVDA 2020.3 were written by someone other than an NV Access staff member, from people living in different countries and speaking many languages. But I know that we can improve on that somehow.



Another wish I have, mostly for Quentin: can we develop some sort of a training program for would-be contributors wishing to improve the overall NVDA community documentation, including the user guide? It may include basics on technical writing, tone and style, audience analysis, exercises where coding and documentation should be done together, and documentation production in a variety of formats (including online media). I think this may help us dive deeper into user guide issues being brought up, including the guide being “too thick” for newbies (in terms of understanding, lack of solid examples, and friendliness), especially for preferences chapter.

Cheers,

Joseph









From: nvda@nvda.groups.io <nvda@nvda.groups.io> On Behalf Of Brian Vogel
Sent: Sunday, October 18, 2020 11:56 AM
To: nvda@nvda.groups.io
Subject: Re: [nvda] NVDA Settings Documentation





Joseph,

          While I applaud your efforts, and tutorials are invaluable, I wasn't even going that far.  I'm talking basic documentation, where each item in a panel/pane/settings group in a given pane are briefly documented. There are myriad NVDA settings that, if their actual function is not directly obvious, which is the case, for example, with most checkboxes, then they're a black hole.

           Even I will admit that for all software it is a limited number of end users who refer to this sort of thing.  That being said, some do, and it serves as a very important basis for new developers to develop depth of knowledge of "what's in there and what it's for."

            I was just commenting to someone for whom I've done custom VBA scripting for Outlook that I am eternally grateful to myself for having developed the habit of rigorously commenting my code, at a bare minimum, as even I would have no idea what some of what I've written actually does when looking at it much later. Complex stuff doesn't remain in "off the top of my head" mode (for most "mes") as time moves on.  That's one of the reasons that basic documentation is so important.


 

Gene,

          There's definitely intelligence being displayed in relation to links, at the very least.  It would be disastrous to split links in virtually any context I can think of.  They really are an atomic unit.

--

Brian - Windows 10 Pro, 64-Bit, Version 2004, Build 19041  

It’s hard waking up and realizing it’s not always black and white.

     ~ Kelley Boorn

 


 

Hi,
Had to dig into C++ part of NvDA to figure this out:
This setting sets browse mode line length, so yes, it applies to when reading by line. Specifically, based on what I can tell, it will do its best to break at word boundaries. This is one of the reasons why links can "span" across multiple lines in browse mode.
In terms of documenting this, one way to improve this is taking Brian's suggestions into account: expand that section and give practical examples, like the following:

This field sets the maximum length of a line in browse mode (in characters) for reading by line purposes.
Unlike documents in programs such as Word and Notepad, browse mode documents do not have a specific line length or a new line character to denote ends of lines.
Because of this, you can set arbitrary line lengths between 10 and 250 characters, and NVDA will try to split lines at word boundaries.
A side effect of this setting is that links and other elements will be split onto multiple browse mode lines.

I'm sure we can make it better, but at least the one I wrote above might be a useful starting point and captures the discussion so far.
Cheers,
Joseph

-----Original Message-----
From: nvda@nvda.groups.io <nvda@nvda.groups.io> On Behalf Of Gene
Sent: Tuesday, October 20, 2020 9:23 AM
To: nvda@nvda.groups.io
Subject: Re: [nvda] NVDA Settings Documentation

We'll see what others say but I know it applies to moving by lines. If I do something else that causes a line to be read, such as move by screen, with page up or down, or move to beginning or end of a document or tab, I would think it would apply in all those contexts, but we'll see what others say.

The intelligent question is a very interesting one and One I haven't thought of. Based on my experience, I don't recall ever having words split when I read in browse mode and the document has no such splitting, I think it is intelligent.

Just how much of such discussions should be in the user guide depends on what the purpose of the guide is. Perhaps some of these stipulations should be in some sort of document for developers or a wiki rather than in a user guide.

I wonder if this or that effect of a command my not be considered when discussing it by those who really know details. A wiki might be a good way to address this. I just found this very interesting discrepancy:
If I set the line length to a short amount, moving using k to move by link will cause an entire link to be read, no matter how long. Moving by arrow or tab and shift tab, will cause the line length stipulated to be read with more of the link being read as I move in the link. Its an interesting discrepancy and one I wonder if those knowledgeable in the matter have given any thought about as to implementation and what is desirable.

Gene
-----Original Message-----
From: Brian Vogel
Sent: Tuesday, October 20, 2020 10:53 AM
To: nvda@nvda.groups.io
Subject: Re: [nvda] NVDA Settings Documentation

On Mon, Oct 19, 2020 at 10:32 PM, Gene wrote:
I would compare it to Word Wrap in Notepad except that you define the number of characters before the wrap occurs.- Gene, that is a good analogy. But what I want to know is what "reading command context(s)" this has an effect on. I'm imagining only line-by-line reading, but . . .

Having something under the setting such as, "If a document has a line longer than the number of characters you set, for line reading it will be split into multiple virtual lines of the maximum length you specify."

I also wonder if it's intelligent as far as splitting at word boundaries, not hard and fast character counts. Mid-word splits would make things potentially very ugly.

That setting, naked as it is, is not something that's intuitive, clearly, just based on this topic. And I'm not saying that you're arguing that it is, just restating the need for some context regarding settings where the effect of same is in no way immediately obvious to the uninitiated (and even the initiated, much later on).

--


Brian - Windows 10 Pro, 64-Bit, Version 2004, Build 19041

It’s hard waking up and realizing it’s not always black and white.

~ Kelley Boorn


Gene
 

We'll see what others say but I know it applies to moving by lines. If I do something else that causes a line to be read, such as move by screen, with page up or down, or move to beginning or end of a document or tab, I would think it would apply in all those contexts, but we'll see what others say.

The intelligent question is a very interesting one and One I haven't thought of. Based on my experience, I don't recall ever having words split when I read in browse mode and the document has no such splitting, I think it is intelligent.

Just how much of such discussions should be in the user guide depends on what the purpose of the guide is. Perhaps some of these stipulations should be in some sort of document for developers or a wiki rather than in a user guide.

I wonder if this or that effect of a command my not be considered when discussing it by those who really know details. A wiki might be a good way to address this. I just found this very interesting discrepancy:
If I set the line length to a short amount, moving using k to move by link will cause an entire link to be read, no matter how long. Moving by arrow or tab and shift tab, will cause the line length stipulated to be read with more of the link being read as I move in the link. Its an interesting discrepancy and one I wonder if those knowledgeable in the matter have given any thought about as to implementation and what is desirable.

Gene

-----Original Message-----
From: Brian Vogel
Sent: Tuesday, October 20, 2020 10:53 AM
To: nvda@nvda.groups.io
Subject: Re: [nvda] NVDA Settings Documentation

On Mon, Oct 19, 2020 at 10:32 PM, Gene wrote:
I would compare it to Word Wrap in Notepad except that you define the number of characters before the wrap occurs.-
Gene, that is a good analogy. But what I want to know is what "reading command context(s)" this has an effect on. I'm imagining only line-by-line reading, but . . .

Having something under the setting such as, "If a document has a line longer than the number of characters you set, for line reading it will be split into multiple virtual lines of the maximum length you specify."

I also wonder if it's intelligent as far as splitting at word boundaries, not hard and fast character counts. Mid-word splits would make things potentially very ugly.

That setting, naked as it is, is not something that's intuitive, clearly, just based on this topic. And I'm not saying that you're arguing that it is, just restating the need for some context regarding settings where the effect of same is in no way immediately obvious to the uninitiated (and even the initiated, much later on).

--


Brian - Windows 10 Pro, 64-Bit, Version 2004, Build 19041

It’s hard waking up and realizing it’s not always black and white.

~ Kelley Boorn


 

On Mon, Oct 19, 2020 at 10:32 PM, Gene wrote:
I would compare it to Word Wrap in Notepad except that you define the number of characters before the wrap occurs.
-
Gene, that is a good analogy.  But what I want to know is what "reading command context(s)" this has an effect on.  I'm imagining only line-by-line reading, but . . .

Having something under the setting such as, "If a document has a line longer than the number of characters you set, for line reading it will be split into multiple virtual lines of the maximum length you specify."

I also wonder if it's intelligent as far as splitting at word boundaries, not hard and fast character counts.  Mid-word splits would make things potentially very ugly.

That setting, naked as it is, is not something that's intuitive, clearly, just based on this topic.  And I'm not saying that you're arguing that it is, just restating the need for some context regarding settings where the effect of same is in no way immediately obvious to the uninitiated (and even the initiated, much later on).
 
--

Brian - Windows 10 Pro, 64-Bit, Version 2004, Build 19041  

It’s hard waking up and realizing it’s not always black and white.

     ~ Kelley Boorn

 


Pranav Lal
 

Hi all,

<snip I guess when working out where best to add information, what would you suggest needs adding?  That seems to describe the feature to me, but maybe I am too familiar with it to see what is missing?

PL] When would I want to alter this setting?

 

Pranav


Gene
 

I would compare it to Word Wrap in Notepad except that you define the number of characters before the wrap occurs. I think the comparison is especially apt to Notepad because you can write as long a line as you wish in Notepad but the wrap makes it manageable on-screen.

Gene

-----Original Message-----
From: Brian Vogel
Sent: Monday, October 19, 2020 7:38 PM
To: nvda@nvda.groups.io
Subject: Re: [nvda] NVDA Settings Documentation

Gene,

Interesting. And nothing I ever, in a million years, would have "read in" to this setting. It sounds like it's a way to break up text into segments a maximum of X characters long, at most.

--


Brian - Windows 10 Pro, 64-Bit, Version 2004, Build 19041

It’s hard waking up and realizing it’s not always black and white.

~ Kelley Boorn


 

Gene,

            Interesting.  And nothing I ever, in a million years, would have "read in" to this setting.  It sounds like it's a way to break up text into segments a maximum of X characters long, at most.

--

Brian - Windows 10 Pro, 64-Bit, Version 2004, Build 19041  

It’s hard waking up and realizing it’s not always black and white.

     ~ Kelley Boorn

 


Gene
 

There is no truncating. I worked with the feature in JAWS years ago. I don't remember the line length in JAWS, if it was the same, longer or shorter than in NVDA, both using default settings. The point of it is that the MSAA buffer needs to have a line length set. the underlying page has none and the line length is determined by how much will fit on the screen being used unless the page designer has placed line codes on the page, which they usually don't. So you can set the length of a line you hear when you up and down arrow on a page.

If I am looking for something on a page and I want to be able to move quickly from line to line listening to a bit and then moving on, I may want shorter lines than the default so I can quickly move by line and when I'm close to what I'm looking for, slow down. If lines are too long, I may miss what I'm looking for because it may be near the ende of a long line and I may move down before hearing it.

Others may have other uses. That is the use I made of the feature. I set the line length to be shorter and left it there so I could move quickly from line to line and not have too much on a line to prevent easy skimming.

Gene

-----Original Message-----
From: Brian Vogel
Sent: Monday, October 19, 2020 6:45 PM
To: nvda@nvda.groups.io
Subject: Re: [nvda] NVDA Settings Documentation

Quentin,

Here's some input in the form of questions.

What constitutes a line?

Does the maximum number of characters result in truncation and, if so, under what reading conditions? (I can't imagine this setting affects read all behavior, for instance).

If a line (after defined) is longer than that maximum, what happens when that occurs during browse mode?

--


Brian - Windows 10 Pro, 64-Bit, Version 2004, Build 19041

It’s hard waking up and realizing it’s not always black and white.

~ Kelley Boorn