Documentation

I'm going to submit a revised documentation of the "bisect" module. I revised much of the page.

I've already prepared a draft (see the attachment), but I suspect math notions that I don't know may be hiding behind the scene. So I've asked a question at math.stackexchange.com. If Python 3.11 development window allows, let us wait for a week or two; mathematical explanation will be, if possible, more universal.

Rationale:

• Currently bisect functions are explained to find "an insertion point". It's correct, but in fact it's not limited to insertion. Rather it should be "to locate the point that devides the list by a value."

• The current docs for "bisect_left" and "bisect_right" are separate, hurting their readability. In particular "suitable for list.insert()" appears only for the former, but it's true for both. (This flaw made me ponder for a while.)
  ** The split into two also makes doc maintenance difficult. (The description of the new parameter "key" is repeated, while others are not. There's some feeling of scatteredness.)

• Only "<=" and "<" will be used, replacing ">=" and ">". From my experience, this often improves readability in circumstances like this doc.

• In my draft there's an expression like "the point that can divide the list". Without "can", readers may think there's the side effect that modifies the original list, by breaking into two. So if you adopt it, please don't drop that "can".

• The section "Searching Sorted Lists" gives in fact examples, so I combined it into the section "Examples".

• And so on.

I haven't compile-checked my draft. Sorry. (It's quite a task for a one-time contributor. ;-)

# And I know Python development prefers pull requests. Sorry for that, too.

Thank you very much for maintaining the Python doc. Regards.
bisect.txt - in fact a .rst file.