Binosha Keyboard 0.9.7 - portable
=================================

Run BinoshaKeyboard.exe. Nothing to install and no .NET needed: the runtime is inside this folder.
An icon appears in the notification area (next to the clock).

First start: sign in and activate
  The program needs your Binosha account. The settings panel opens by itself at the corner of the screen, with a sign-in card over it
  (the settings are blurred behind it).
  1. Press "ورود با مرورگر". Your browser opens the Binosha website: sign in there (or create an account). Your password is typed only
     on the website, never in this program. When the website asks to open "Binosha Keyboard", allow it; you come back to the card.
  2. Activate it once with 50 BinoshaPoints. The button names the price; nothing is taken until you press it.
     If you have too few points, earn some on the site and press "به‌روزرسانی موجودی".
  3. That is all. It is a one-time payment: afterwards the program works offline and never asks you to sign in again.
  Until it is activated the program does nothing at all: it reads nothing you type.
  Signing in on another computer, or again after "Sign out", does not charge twice: the site remembers the activation.
  Staff accounts (author, editor, administrator) use the program free.

  Left-click the icon   opens the settings panel (with the sign-in card over it until the program is activated)
  Right-click the icon  menu:
      Settings...                      the settings panel
      Enabled / Paused                 turn the whole program on or off
      [x] Enable Auto-Correction       automatic replacement of known mistakes (see below)
      [x] Fix Wrong Layout             a word typed with the keyboard on the wrong language (see below)
      [x]    Automatically             ... converted by itself at a space; unchecked: only offered as a chip
      [x] Fingilish to Persian         the "تبدیل به فارسی" chip for Persian written in Latin letters
      [x] Next-word prediction         after a word and a space, offer the words that usually come next (see "Next word" below)
      [x] Launch at Startup            start the program when Windows starts (see "Starting with Windows" below)
      Open custom words file...
      Signed in: <name>                who is signed in: the name your Binosha profile shows (greyed: information only)
      Sign out                         opens the settings panel and asks there; the activation stays on your account
      Check for Updates...             asks the site now whether a newer version exists
      Exit

Settings panel
  - At the top it names the account and has a "خروج از حساب" (sign out) button. It asks once; after you agree the sign-in card
    comes back over the panel, so you can sign in again, even with another account (sign out of the website too if the browser keeps
    signing you in as the same person). The activation stays with the account, so signing in again costs nothing.
  - "پیشنهاد کلمه"      turns suggestions on or off. Off means the program is idle: it shows nothing and reads nothing.
  - "اصلاح غلط املایی"     turns the red spelling suggestions on or off.
  - "اصلاح خودکار"        turns automatic correction on or off.
  - "کلمه‌های من"       your own words: add one, or remove one with its X. An added word works at once.
  The panel closes with Esc, the X, or by clicking anywhere else. Typing in it never starts suggestions.

How it works
  - Type a word. After 2 letters a small bubble shows up to 2 suggestions and, last, the word as you typed it.
  - Press Shift twice quickly to type the highlighted suggestion. Up/Down move the highlight, Esc closes the bubble.
    Tab and Enter are never used by the program.
    The first few times, a second small bubble over the suggestions reminds you of this ("Shift Shift"). It stops as soon
    as you have done it once (or after 8 showings).
  - Unknown word? The "+" button (or Shift+Alt+A) adds it to your dictionary.
  - A word that looks like a typo gets red suggestions marked "اصلاح"; Shift twice replaces the whole word.
    The program recognises a word with two wrong letters (three in a long word), letters that sound the same in Persian
    (س ص ث, ز ذ ض ظ, ت ط, ه ح, ق غ), a doubled letter written once or a single one written twice, and two letters in the
    wrong order. The likeliest word comes first: a very common word a little further away beats a rare one that is closer.
    Some misspellings are in the word list itself as rare words ("خاهش"); those get the red suggestions too.
  - Double-click a misspelled word that is already in your text: the red suggestions appear above it. Click one (or press
    Shift twice) and it replaces the word. Esc, any other key, or a click elsewhere closes them. Nothing appears for a word
    that is spelled right, in a password field, or in text that cannot be edited (a web page). This needs a program that
    tells Windows what is selected; most do (Notepad, Word, browsers' text boxes), a few do not.
  - Went past a wrong word with Space? Press Backspace over the space, or the Left arrow, and the bubble opens
    for that word again. (After a mouse click the program cannot know where you are in the text, so this works
    from the keyboard only.)

Next word
  Finish a word with a space and, before you type anything else, the popup shows up to three words that often come next
  ("دست " offers شما, به, از). Press Shift twice to type the highlighted one and a space; its own next words then follow.
  - Down/Up move the highlight, Esc closes it. Any key you type closes it at once, and what you type is completed as usual.
    Up and Down belong to the popup while it is open: press Esc first to move between lines of your text.
  - It follows you. The pairs of words you type are counted on this computer, and the more you write a phrase, the sooner it
    leads. Only pairs you typed at least twice are kept on disk, in  user_bigrams.tsv  (next to settings.json: one
    "word TAB next word TAB times" per line). Delete the file to forget them. Nothing from it ever leaves your computer,
    nothing is counted in password fields, and no pair is counted across a comma, a full stop, a new line or a mouse click.
  - The program ships with a short list of the commonest pairs (dictionaries\bigrams.dat). It is hand-written, not counted
    from a large text, so for many words it has nothing to offer until you have written them yourself.
  - Switch: "Next-word prediction" in the tray menu.

Words with endings
  A word the dictionary lacks is still correct when it is a known word plus the usual prefix or ending: کتاب‌هایمان,
  خانه‌ام, می‌روم, نمیدانم, بزرگ‌ترین. Such words are not marked as typos and are never corrected automatically.
  Spelling suggestions also know where your fingers slip: a letter next to the right one on the keyboard (ک for گ, ا for ل,
  ف for ب) is a smaller mistake than a distant one, and two words typed without the space ("خیلیخوب") are offered apart
  ("خیلی خوب").

Wrong keyboard language
  You meant to type Persian but the keyboard was on English, so "sghl" came out instead of "سلام" (or the other way round:
  "اثممخ" for "hello"). When you press Space (or . ! ?) the program puts the right word there, and the space after it.
  - It only does this for something that means nothing as typed and is a common word on the other layout. A real word
    ("is", "as") is never touched, nor are your own words.
  - While you are still typing, the same conversion is offered as a chip marked "زبان کیبورد"; Shift twice takes it.
  - Press Backspace as the very next key and what you typed comes back; that token is then left alone.
  - Three settings: automatic (the default), chip only, or off. In the settings panel: "اصلاح زبان کیبورد" and, under it,
    "خودکار". In the tray menu: "Fix Wrong Layout" and "Automatically".
  - The keys are read from the keyboard layouts already installed on your computer: the ordinary "US" keyboard first,
    then any other English layout you have (US-International, UK, Dvorak...), against each Persian layout you have (both
    Windows Persian layouts work). With no such layout installed it assumes the US keyboard and Persian (Standard).
  - On US-International the keys ' " ` ^ ~ wait for the next letter and may leave "á" where you pressed ' and a; the
    program reads that as the two keys you pressed.
  - It never adds, removes or switches a keyboard layout: your list of keyboards in Windows is not touched, and the
    keyboard language is not switched for you.

Fingilish to Persian
  Type Persian in Latin letters ("salam", "chetori") and a chip marked "تبدیل به فارسی" offers the Persian word (سلام,
  چطوری). It is only ever a chip: nothing is converted unless you take it (Shift twice; Down first if it is not the
  highlighted one). Backspace right afterwards puts the Latin letters back.
  - When the word is also the start of an English word ("man", "to"), the English suggestion stays first and the Persian
    one is second, so Shift twice never turns English into Persian by surprise.
  - Latin spelling of Persian is ambiguous; the program picks the commonest Persian word that fits and may offer a second.
  - Switch: "فینگلیش به فارسی" in the settings panel, "Fingilish to Persian" in the tray menu.

A whole sentence in Fingilish
  Already wrote "salam chetori khobi che khabar?" Select it and one chip with the whole sentence in Persian
  ("سلام چطوری خوبی چه خبر؟") appears above it. Press Shift twice, or click the chip, and it replaces what you selected.
  - Select any way you like: drag with the mouse, double-click one word, click three times for the line, hold Shift and
    press the arrows (or Home/End), or Ctrl+A. If nothing appears, press Shift twice: the program then looks at what is
    selected, and Shift twice again takes it.
  - Spaces and punctuation stay where they are; ? , ; become ؟ ، ؛. A word the program cannot read stays as you wrote it.
  - Nothing appears for an English sentence, for text that is already Persian, in a password field, in text that cannot
    be edited, or for a selection longer than about 300 characters (select it in parts).
  - Esc, any other key, or a click elsewhere closes the chip. To take the Persian text back, use the editor's own undo
    (Ctrl+Z).
  - It reads the selection the way a screen reader does and types the Persian text over it. The clipboard is never used.
    A few programs do not tell Windows what is selected; nothing appears in those.
  - Latin spelling of Persian is ambiguous: each word becomes the commonest Persian word that fits, so read the chip
    before you take it ("bad" is read as بعد, not بد).
  - The same switch as above turns it off.

Automatic correction
  When a space or one of  . , ; : ! ? ، ؛ ؟  ends a word, a known common mistake (for example "سللم" or "راجب") is
  replaced at once by the right word, and the space or mark is put back. Rules that keep it safe:
  - Words you added with "+", or typed often enough to be learned, are never changed.
  - Words with digits, a half-space, an apostrophe or unusual capitals (iPhone, NASA) are never changed.
  - Enter never triggers it (by then a chat or search box has already sent the text).
  - If you type the next key before the program has replaced the word, it does nothing.
  - Press Backspace as the very next key and your own word comes back; that word is then left alone from then on.
  - Passwords: nothing is changed in a password field.
  Some programs correct text by themselves (Word, phones' keyboards); turn this off if the two clash.
  The list of mistakes is the file  dictionaries\autocorrect.tsv  (one "mistake TAB correction" per line).

Starting with Windows
  The first time you run this version, a small window asks: "آیا مایلید بینوشا کیبورد همزمان با روشن شدن ویندوز به صورت خودکار اجرا شود؟"
  (should Binosha Keyboard start by itself when Windows starts?). "بله، فعال شود" turns it on; "خیر", the X or Esc leaves it off. It is
  asked once and never again.
  - Change your mind at any time: right-click the tray icon and click "اجرا هنگام راه‌اندازی ویندوز (Launch at Startup)". The check mark
    shows what Windows will really do. The program is also listed in Task Manager > Startup apps, and switching it off there works too (the
    tray item then shows it unchecked; clicking it switches it back on).
  - What it does: one entry in YOUR list of startup programs (HKCU\Software\Microsoft\Windows\CurrentVersion\Run, value "BinoshaKeyboard"):
    the full path of BinoshaKeyboard.exe. No administrator rights, no service, no scheduled task. Turning it off removes it.
  - If you started the program with --data-dir (a USB stick), the startup entry carries the same option, so it starts with your own files.
  - If you move the folder, start the program from its new place once: the entry is updated by itself. If you delete the folder without
    switching it off first, Windows simply finds nothing to start; switch it off first (tray menu or Task Manager) to leave no trace.
  - A program that is not activated yet starts idle, like always: it reads nothing until you sign in and activate it.

The network
  The program contacts the Binosha site (binosha.com) only when YOU do one of these four things:
  - finish a sign-in you started in the browser (the link that brings you back carries a one-time code, never the key to your
    account; the program swaps that code for its sign-in and asks the site once who you are; no password is ever involved),
  - press the activation button,
  - sign out before you have activated (the program tells the site to cancel the sign-in it was holding),
  - choose "Check for Updates...".
  When the program no longer needs its sign-in key (right after the activation) it tells the site to cancel it, in that same moment.
  Once the program is activated it never contacts the site by itself: no background check, no timer, no usage data, nothing you
  typed. With no internet it simply does nothing (the update window says it could not connect).
  The sign-in link only works for the sign-in you started yourself, once, within a few minutes: a link from anywhere else is ignored.
  Check for Updates asks the site which version is published. If it is newer than yours (this is 0.9.7) the window shows what
  changed and a button that opens the download page in your browser. The program never downloads or installs anything itself.

Programs where letters are shortcuts
  In Photoshop, Illustrator and the like a single letter is a tool (V is Move, T is Type), not a word. The keyboard stays out of
  those programs, and also out of anything that is plainly not a place for text (a canvas, a toolbar, a file list): no popup,
  no automatic correction, nothing typed for you. Typing in a real text box of any other program works as before. The list of
  programs is "excludedApps" in settings.json (see below).

Where your data is kept
  Normally in  %LOCALAPPDATA%\Binosha\Keyboard\
      settings.json      the switches ("layoutFix" is "auto", "suggest" or "off"; "fingilish" is true or false), how many
                         more times the Shift reminder is shown, "excludedApps": the programs the keyboard stays out of
                         (a list of file names such as "photoshop.exe", where single letters are tool shortcuts: the list
                         starts with Photoshop, Illustrator, InDesign, After Effects, Premiere Pro, Lightroom, Blender and
                         AutoCAD; remove a name to use the keyboard there, add one to stay out; [] means none), and (if you
                         set one) "siteUrl": an HTTPS address of the Binosha site
      license.dat        your sign-in, encrypted for your Windows user (no password in it, and no token once activated)
      custom_words.tsv   your added words (one per line: word, optional tab and a number for rank)
      user-words.json    words the program learned from what you type
      user_bigrams.tsv   pairs of words you typed at least twice, for next-word suggestions (delete it to forget them)
  To keep everything inside this folder instead (for a USB stick), start it with
      BinoshaKeyboard.exe --data-dir data
  and the files go to a "data" folder next to the program. Use the same option every time.
  license.dat only works for the Windows user that made it: on another account you sign in again (no second payment).

The browser comes back to the program through the link type "binosha-keyboard://", which the program registers for your Windows user
(HKCU\Software\Classes\binosha-keyboard) each time it starts. Remove that key when you delete the program.
If you chose to start with Windows there is also the value "BinoshaKeyboard" under HKCU\Software\Microsoft\Windows\CurrentVersion\Run
(switch it off in the tray menu, or in Task Manager > Startup apps, before you delete the program).

To remove everything: exit the program, delete this folder and the data folder.

Files
  BinoshaKeyboard.exe   the whole program in one file (the .NET runtime is inside it). On its first start it unpacks a few
                        system libraries to %TEMP%\.net\BinoshaKeyboard; Windows may clear that folder, the program then
                        simply unpacks them again.
  dictionaries\   the Persian and English word lists, bigrams.dat (the next-word list) and autocorrect.tsv
  Fonts\          the Vazirmatn font licence (SIL Open Font License)
