diff --git a/doc/develop.jax b/doc/develop.jax index 52fc82589..c373a91aa 100644 --- a/doc/develop.jax +++ b/doc/develop.jax @@ -1,4 +1,4 @@ -*develop.txt* For Vim バージョン 9.1. Last change: 2025 Jul 18 +*develop.txt* For Vim バージョン 9.1. Last change: 2025 Jul 22 VIMリファレンスマニュアル by Bram Moolenaar @@ -9,9 +9,9 @@ Vimの開発 *development* この文書は、Vimの更なる開発に参加しようという人にとって重要である。 1. 設計上の目標 |design-goals| -2. コーディングスタイル |coding-style| -3. 決定事項 |design-decisions| -4. 想定していること |design-assumptions| +2. 決定事項 |design-decisions| +3. 想定していること |design-assumptions| +4. コーディングスタイル |coding-style| ソースコードの概要については "src" ディレクトリのREADME.txtを見てください。 @@ -161,7 +161,197 @@ Vimは、そのユーザーに特定の作業パターンを強いるよりは ============================================================================== -2. コーディングスタイル *coding-style* +2. 決定事項 *design-decisions* + +折り畳み(folding) + +同じバッファにいくつもの折り畳み状態を設定可能にする。例えば、あるウィンドウに +関数を折り畳んだ状態で表示し、他のウィンドウで関数の中身を表示するなど。 + +折り畳みはテキストを表示する方法である。テキストを変更すべきではない。したがっ +てバッファ内のテキストをウィンドウに表示する際のフィルタとして実行される。 + + +ウィンドウの名前 + +"ウィンドウ" という単語は一般にいくつかの意味で使われている。スクリーン上のウィ +ンドウ、xtermのウィンドウ、Vimのバッファを表示するウィンドウなど。 + +混乱を避けるため、時にウィンドウと呼ばれる他の物には別の名前が付けられている。 +ここに関連する物の概観を示す: + +スクリーン(screen) ディスプレイ全体。GUIでは例えば1024x768ピクセルの画 + 面。Vimシェルはスクリーン全体を使うことも一部を使う + こともできる。 +シェル(shell) Vimアプリケーション。スクリーン全体(例えばコンソール + で実行した時)、あるいはその一部(xtermやGUI)。 +ウィンドウ(window) バッファの表示画面。Vimは複数のウィンドウを持つこと + ができる。ウィンドウはコマンドラインやメニューバー、 + ツールバーなどといっしょに表示される。これらはシェル + に納まる。 + + +スペルチェック *develop-spell* + +Vim にスペルチェックを追加することになったとき、利用可能なスペルチェックのライ +ブラリやプログラムについて調査が行われた。その結果は残念なことに、Vim 内でスペ +ルチェックエンジンとして使えるものはないとわかった。これには様々な理由がある: + +- マルチバイトエンコーディングをサポートしていない。1つのファイル内で複数の言 + 語を使えるようにするために、少なくとも UTF-8 はサポートしていなければならな + い。 + オンザフライな変換は常に可能とは限らない(iconv に対応している必要がある)。 +- プログラムとライブラリに対して: それらをそのまま(as-is)使うには、Vim と別個 + にインストールしなければならない。これはたいてい不可能ではないが、難点である。 +- パフォーマンス: いくつかのテストによると、スペルチェックを構文強調のようにオ + ンザフライで(再描画中に)行うことは可能であった。しかし他のコードで使われたメ + カニズムはもっと遅かった。例えば、Myspell はハッシュテーブルを使用する。ほと + んどのスペルチェッカが使用している接辞圧縮を使うと遅くなった。 +- aspell のような外部プログラムを使うには、通信メカニズムを用意しなければなら + ない。これをポータブルな方法で行うのは複雑過ぎる(Unix だけなら比較的簡単だが、 + それでは十分ではない)。そしてパフォーマンスが問題になる(何回ものプロセス切替 + が行われる)。 +- "Etten-Leur" や "et al." など、単語でない単語のサポートを欠いている。そのた + めこれらの部分を OK とマークしなければならないが、そうすると信頼性が低下する。 +- 地域や方言のサポートを欠いている。英語の単語をすべて受け付け、カナダ語でない + 単語を別に扱うことが難しくなる。 +- 頻度が低い単語のサポートを欠いている。正しいがめったに使われないたくさんの単 + 語が、よく使われる単語のスペルミスとみなされてしまう。 +- スペル候補を作成するには速度はそれほど重要ではなく、他のプログラムやライブラ + リをインストールすることは許容できる。しかし、単語リストが異なるとスペル候補 + が誤単語になってしまう。 + + +スペル候補 *develop-spell-suggestions* + +候補の作成には2つの基本的なメカニズムがある: +1. 誤った単語を少し変更して正しい単語とマッチするかチェックする。あるいは、正 + しい単語全てに対し、それを少し変更して誤った単語とマッチするかチェックする。 + 変更とは、文字の削除・文字の挿入・2つの文字の交換などである。 +2. 誤った単語と正しい単語のリストの両方に soundfolding (発音が近い単語を同じグ + ループとみなすこと) を行って、そこでマッチを見つける。1番目のメカニズムと同 + 様にいくつか変更をしてもよい。 + +最初のメカニズムはタイプミスを見つけるのにはよい。ハッシュテーブルの実験と、他 +のスペルチェッカのソリューションを見ると、これにはtrie(ツリー構造の一種)が最適 +であるとの結論になった。メモリ使用量の削減と、賢い変更を試みるということの両方 +の面でである。例えば、文字を挿入するときは正しい単語につながる文字だけを試せば +よい。他の(ハッシュテーブルを使った)メカニズムは、単語のすべての位置で、ありう +るすべての文字を試さねばならない、また、ハッシュテーブルを使うには、単語の境界 +が個別に認識されなければならないのに対し、trie はそれを要求しない。そのためメ +カニズムがより単純になる。 + +ある単語の発音は知っているがスペルを知らないという場合に soundfolding は有用で +ある。例えば、"dictionary" という単語を "daktonerie" と書いてしまうかもしれな +い。これを最初の方法で訂正しようとすると変更回数が非常に多くなってしまい、正し +いスペルを見つけるのは困難である。それに対し、これらの単語にsoundfoldingを行う +と "tktnr" と "tkxnry" になり、2文字しか違わない。 + +soundfoldの同値(音が似ている単語)により単語を見つけるには全てのsoundfolded +wordsのリストが必要である。どれが最良の方法かを探すための実験が行われた。案: +1. 修正候補を探すときに、その場でsound foldingを行う。つまり、正しい単語のtrie + をたどりながら、各単語をsoundfoldingし、それがスペルミスしている単語からど + れだけ異なるかをチェックする。これはメモリ効率の面でとても優れているが、時 + 間は長くかかる。英語の場合、高速なPCで2秒ほどかかる。これは対話的な利用とし + て受け入れられる。しかしいくつかの言語(ドイツ語、カタルニャ語など)に対して + は10秒以上かかり、受け入れがたい。バッチ処理(自動訂正)に使うには全ての言語 + で遅すぎる。 +2. soundfoldされた単語に対してtrieを使い、soundfoldingなしのときとまったく同じ + ように検索できるようにする。そのためには、soundfoldされた各単語に対し、正し + い単語のリストを記憶しておく必要がある。そうすると照合がとても高速になるが、 + 1MB〜10MBのオーダーの大量のメモリを必要とする。ある言語の場合は元の単語のリ + ストよりも多くなる。 +3. 2番目の案と同様だが、接辞圧縮を使い、soundfoldした基本単語だけを保存するこ + とによりメモリ消費量を減らす。これはAspellが採用している方法である。不利点 + は、誤った単語をsoundfoldする前に接辞を取り除いておかねばならないことである。 + そのため、単語の先頭・末尾における誤りに対しては対応できない。また、誤った + 単語が正しい単語から大きく異なるときは遅くなる。 + +我々が採用したのは、2番目のメカニズムを使い、別ファイルを使う方法である。こう +することによって、十分なメモリを持っているユーザーはとてもよい候補を得ることが +できるし、メモリが不足しているユーザーやスペルチェックだけで候補は出さなくてよ +いというユーザーはそれほどメモリを使わなくてすむ。 + + +単語の頻度 + +候補をソートするにはどの単語が共通であるかを知ると役に立つ。理論的には単語の頻 +度は単語とともに辞書の中に保持することができる。しかしそうすると単語につき回数 +を保持しなければならない。これは単語ツリー圧縮を大いに劣化させる。また、全ての +言語に対して単語の頻度を保守するのは大変な作業である。 +また、テキストに既に出てきている単語を優先するとよいだろう。このようにして特定 +のテキスト内に表れる単語は候補の中で優先度が高くなる。 + +実装されたのは、表示中に単語を数えることである。ハッシュテーブルを使ってその単 +語の回数を高速に検索する。回数は接辞ファイルでCOMMONアイテムにリストされている +単語から初期化される。そのため新規ファイルの編集を始めたときも機能する。 + +これは理想的ではない。Vimが長時間稼動しているほど回数は大きくなるためである。 +しかし実用的には単語の回数を使わない場合に比べて注目に値するほどの改善である。 + +============================================================================== +3. 想定していること *design-assumptions* + +以下のセクションでは、すべての Vim コードとビルドツールが遵守する必要がある移 +植性と互換性の制約を定義する。 + + +MAKEFILES *assumptions-makefiles* + *POSIX.1-2001* + +Vim のメイン Makefile は最大限の移植性を目指しており、POSIX.1-2001 の make で +定義された機能のみに依存し、それ以降の POSIX 標準や GNU/BSD 拡張は無視してい +る。具体的には、以下の点を避けている。 + + – % パターンルール + – POSIX.1-2001 外のモダンなな代入 (`:=`, `::=`) + – 特別なターゲット (`.ONESHELL`, `.NOTPARALLEL`, `.SILENT`, …) + – 順序のみの前提条件 (`|`) または自動ディレクトリ作成 + – GNU/BSD 条件文 (`ifdef`, `ifndef`, `.for`/`.endfor`, …) + +POSIX.1-2001 は従来のサフィックスルールのみをサポートしているため、別ディレク +トリに構築されるすべてのオブジェクトには明示的なルールが必要である。例: + + objects/evalbuffer.o: evalbuffer.c + $(CCC) -o $@ evalbuffer.c + +この冗長性により、同じ Makefile で、Linux、*BSD、macOS、Solaris、AIX、HP-UX、 +および事実上すべての Unix 系 OS 上でデフォルトの `make` を使用して Vim を変更 +せずにビルドできるようになる。 + +一部のプラットフォーム固有の Makefile (Windows、NSIS、Cygwin など) では、基本 +的な make との互換性が不要な場合に、より高度な機能が使用されることがある。 + + +☆C コンパイラ *assumptions-C-compiler* + *ANSI-C* *C89* *C90* *C95* *C99* + +Vim は最大限の移植性 (|design-multi-platform| を参照) を目指しており、OpenVMS +VAX V7.3 では Compaq C V6.4-005 を使用してビルドする必要がある。 + +したがって、私たちが従う最新の ISO C 標準は次のとおりである: + + `C95` (ISO/IEC 9899:1990/AMD1:1995) + +さらに、以下の 2 つの `C99` 機能が明示的に許可される: + – |style-comments| で要求される `//` コメント。 + – `_Bool` 型。 + +プラットフォーム固有のコードでは、そのプラットフォームでサポートされている新し +いコンパイラ機能が使用される場合がある。 + + +☆変数のサイズ *assumptions-variables* + + char 8-bit signed + char_u 8-bit unsigned + int 32- or 64-bit signed (レガシーシステムでは 16-bit が可能) + unsigned 32- or 64-bit unsigned + long 少なくとも 32-bit signed (ポインタを保持できる十分な大きさ) + + +============================================================================== +4. コーディングスタイル *coding-style* Vimのソースコードに変更を加える際、守るべきルールがある。ソースを読めるもの、 保守できるものとして保つため、これらのルールに従って欲しい。 @@ -200,23 +390,6 @@ sound.c と sign.c は、配布された .clang-format ファイルに従って 可能性があり、同様に再フォーマットされる可能性がある。 -☆Cコンパイラ *style-compiler* *ANSI-C* *C89* *C99* - -サポートされている最小の C コンパイラのバージョンは C89 (ANSI C とも呼ばれてい -る) である。C99 のような後継の標準規格はあまり普及していない、もしくは少なくと -も 100% サポートされているわけではない。したがって、C99 機能の一部のみを使用 -し、一部を明示的に禁止する (これは時間の経過とともに徐々に調整される)。 - -使用してはいけない機能 ~ - -これらの C99 の機能は、コンパイラのサポートが不十分なため使用してはいけない: -- 可変長配列 (C11 でもこれはオプショナルな機能である)。 -- C99 の _Bool 型と _Complex 型。 -- "inline" (ほとんど必要ない、コンパイラに最適化させよう。) -- フレキシブル配列メンバ: HP-UX C コンパイラはサポートしていない。(John - Marriott) - - ☆コメント *style-comments* 関数本体内に複数行のコメントを入れないようにすること。関数が非常に複雑で、一部 @@ -515,146 +688,5 @@ OK: do while (cond); -============================================================================== -3. 決定事項 *design-decisions* - -折り畳み(folding) - -同じバッファにいくつもの折り畳み状態を設定可能にする。例えば、あるウィンドウに -関数を折り畳んだ状態で表示し、他のウィンドウで関数の中身を表示するなど。 - -折り畳みはテキストを表示する方法である。テキストを変更すべきではない。したがっ -てバッファ内のテキストをウィンドウに表示する際のフィルタとして実行される。 - - -ウィンドウの名前 - -"ウィンドウ" という単語は一般にいくつかの意味で使われている。スクリーン上のウィ -ンドウ、xtermのウィンドウ、Vimのバッファを表示するウィンドウなど。 - -混乱を避けるため、時にウィンドウと呼ばれる他の物には別の名前が付けられている。 -ここに関連する物の概観を示す: - -スクリーン(screen) ディスプレイ全体。GUIでは例えば1024x768ピクセルの画 - 面。Vimシェルはスクリーン全体を使うことも一部を使う - こともできる。 -シェル(shell) Vimアプリケーション。スクリーン全体(例えばコンソール - で実行した時)、あるいはその一部(xtermやGUI)。 -ウィンドウ(window) バッファの表示画面。Vimは複数のウィンドウを持つこと - ができる。ウィンドウはコマンドラインやメニューバー、 - ツールバーなどといっしょに表示される。これらはシェル - に納まる。 - - -スペルチェック *develop-spell* - -Vim にスペルチェックを追加することになったとき、利用可能なスペルチェックのライ -ブラリやプログラムについて調査が行われた。その結果は残念なことに、Vim 内でスペ -ルチェックエンジンとして使えるものはないとわかった。これには様々な理由がある: - -- マルチバイトエンコーディングをサポートしていない。1つのファイル内で複数の言 - 語を使えるようにするために、少なくとも UTF-8 はサポートしていなければならな - い。 - オンザフライな変換は常に可能とは限らない(iconv に対応している必要がある)。 -- プログラムとライブラリに対して: それらをそのまま(as-is)使うには、Vim と別個 - にインストールしなければならない。これはたいてい不可能ではないが、難点である。 -- パフォーマンス: いくつかのテストによると、スペルチェックを構文強調のようにオ - ンザフライで(再描画中に)行うことは可能であった。しかし他のコードで使われたメ - カニズムはもっと遅かった。例えば、Myspell はハッシュテーブルを使用する。ほと - んどのスペルチェッカが使用している接辞圧縮を使うと遅くなった。 -- aspell のような外部プログラムを使うには、通信メカニズムを用意しなければなら - ない。これをポータブルな方法で行うのは複雑過ぎる(Unix だけなら比較的簡単だが、 - それでは十分ではない)。そしてパフォーマンスが問題になる(何回ものプロセス切替 - が行われる)。 -- "Etten-Leur" や "et al." など、単語でない単語のサポートを欠いている。そのた - めこれらの部分を OK とマークしなければならないが、そうすると信頼性が低下する。 -- 地域や方言のサポートを欠いている。英語の単語をすべて受け付け、カナダ語でない - 単語を別に扱うことが難しくなる。 -- 頻度が低い単語のサポートを欠いている。正しいがめったに使われないたくさんの単 - 語が、よく使われる単語のスペルミスとみなされてしまう。 -- スペル候補を作成するには速度はそれほど重要ではなく、他のプログラムやライブラ - リをインストールすることは許容できる。しかし、単語リストが異なるとスペル候補 - が誤単語になってしまう。 - - -スペル候補 *develop-spell-suggestions* - -候補の作成には2つの基本的なメカニズムがある: -1. 誤った単語を少し変更して正しい単語とマッチするかチェックする。あるいは、正 - しい単語全てに対し、それを少し変更して誤った単語とマッチするかチェックする。 - 変更とは、文字の削除・文字の挿入・2つの文字の交換などである。 -2. 誤った単語と正しい単語のリストの両方に soundfolding (発音が近い単語を同じグ - ループとみなすこと) を行って、そこでマッチを見つける。1番目のメカニズムと同 - 様にいくつか変更をしてもよい。 - -最初のメカニズムはタイプミスを見つけるのにはよい。ハッシュテーブルの実験と、他 -のスペルチェッカのソリューションを見ると、これにはtrie(ツリー構造の一種)が最適 -であるとの結論になった。メモリ使用量の削減と、賢い変更を試みるということの両方 -の面でである。例えば、文字を挿入するときは正しい単語につながる文字だけを試せば -よい。他の(ハッシュテーブルを使った)メカニズムは、単語のすべての位置で、ありう -るすべての文字を試さねばならない、また、ハッシュテーブルを使うには、単語の境界 -が個別に認識されなければならないのに対し、trie はそれを要求しない。そのためメ -カニズムがより単純になる。 - -ある単語の発音は知っているがスペルを知らないという場合に soundfolding は有用で -ある。例えば、"dictionary" という単語を "daktonerie" と書いてしまうかもしれな -い。これを最初の方法で訂正しようとすると変更回数が非常に多くなってしまい、正し -いスペルを見つけるのは困難である。それに対し、これらの単語にsoundfoldingを行う -と "tktnr" と "tkxnry" になり、2文字しか違わない。 - -soundfoldの同値(音が似ている単語)により単語を見つけるには全てのsoundfolded -wordsのリストが必要である。どれが最良の方法かを探すための実験が行われた。案: -1. 修正候補を探すときに、その場でsound foldingを行う。つまり、正しい単語のtrie - をたどりながら、各単語をsoundfoldingし、それがスペルミスしている単語からど - れだけ異なるかをチェックする。これはメモリ効率の面でとても優れているが、時 - 間は長くかかる。英語の場合、高速なPCで2秒ほどかかる。これは対話的な利用とし - て受け入れられる。しかしいくつかの言語(ドイツ語、カタルニャ語など)に対して - は10秒以上かかり、受け入れがたい。バッチ処理(自動訂正)に使うには全ての言語 - で遅すぎる。 -2. soundfoldされた単語に対してtrieを使い、soundfoldingなしのときとまったく同じ - ように検索できるようにする。そのためには、soundfoldされた各単語に対し、正し - い単語のリストを記憶しておく必要がある。そうすると照合がとても高速になるが、 - 1MB〜10MBのオーダーの大量のメモリを必要とする。ある言語の場合は元の単語のリ - ストよりも多くなる。 -3. 2番目の案と同様だが、接辞圧縮を使い、soundfoldした基本単語だけを保存するこ - とによりメモリ消費量を減らす。これはAspellが採用している方法である。不利点 - は、誤った単語をsoundfoldする前に接辞を取り除いておかねばならないことである。 - そのため、単語の先頭・末尾における誤りに対しては対応できない。また、誤った - 単語が正しい単語から大きく異なるときは遅くなる。 - -我々が採用したのは、2番目のメカニズムを使い、別ファイルを使う方法である。こう -することによって、十分なメモリを持っているユーザーはとてもよい候補を得ることが -できるし、メモリが不足しているユーザーやスペルチェックだけで候補は出さなくてよ -いというユーザーはそれほどメモリを使わなくてすむ。 - - -単語の頻度 - -候補をソートするにはどの単語が共通であるかを知ると役に立つ。理論的には単語の頻 -度は単語とともに辞書の中に保持することができる。しかしそうすると単語につき回数 -を保持しなければならない。これは単語ツリー圧縮を大いに劣化させる。また、全ての -言語に対して単語の頻度を保守するのは大変な作業である。 -また、テキストに既に出てきている単語を優先するとよいだろう。このようにして特定 -のテキスト内に表れる単語は候補の中で優先度が高くなる。 - -実装されたのは、表示中に単語を数えることである。ハッシュテーブルを使ってその単 -語の回数を高速に検索する。回数は接辞ファイルでCOMMONアイテムにリストされている -単語から初期化される。そのため新規ファイルの編集を始めたときも機能する。 - -これは理想的ではない。Vimが長時間稼動しているほど回数は大きくなるためである。 -しかし実用的には単語の回数を使わない場合に比べて注目に値するほどの改善である。 - -============================================================================== -4. 想定していること *design-assumptions* - -変数のサイズ: -char 8 bit signed -char_u 8 bit unsigned -int 32 or 64 bit signed (限定された機能については16ビットもありうる) -unsigned 32 or 64 bit unsigned (16ビットについてはintと同様) -long 32 or 64 bit signed, can hold a pointer - -Note いくつかのコンパイラは長すぎる行は文字列をうまく扱えない。C89の標準規格で -は509文字までに制限されている。 vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/en/develop.txt b/en/develop.txt index 726a59778..9b2e21b5d 100644 --- a/en/develop.txt +++ b/en/develop.txt @@ -1,4 +1,4 @@ -*develop.txt* For Vim version 9.1. Last change: 2025 Jul 18 +*develop.txt* For Vim version 9.1. Last change: 2025 Jul 22 VIM REFERENCE MANUAL by Bram Moolenaar @@ -10,9 +10,9 @@ This text is important for those who want to be involved in further developing Vim. 1. Design goals |design-goals| -2. Coding style |coding-style| -3. Design decisions |design-decisions| -4. Assumptions |design-assumptions| +2. Design decisions |design-decisions| +3. Assumptions |design-assumptions| +4. Coding style |coding-style| See the file README.txt in the "src" directory for an overview of the source code. @@ -159,7 +159,204 @@ VIM IS... NOT *design-not* ============================================================================== -2. Coding style *coding-style* +2. Design decisions *design-decisions* + +Folding + +Several forms of folding should be possible for the same buffer. For example, +have one window that shows the text with function bodies folded, another +window that shows a function body. + +Folding is a way to display the text. It should not change the text itself. +Therefore the folding has been implemented as a filter between the text stored +in a buffer (buffer lines) and the text displayed in a window (logical lines). + + +Naming the window + +The word "window" is commonly used for several things: A window on the screen, +the xterm window, a window inside Vim to view a buffer. +To avoid confusion, other items that are sometimes called window have been +given another name. Here is an overview of the related items: + +screen The whole display. For the GUI it's something like 1024x768 + pixels. The Vim shell can use the whole screen or part of it. +shell The Vim application. This can cover the whole screen (e.g., + when running in a console) or part of it (xterm or GUI). +window View on a buffer. There can be several windows in Vim, + together with the command line, menubar, toolbar, etc. they + fit in the shell. + + +Spell checking *develop-spell* + +When spell checking was going to be added to Vim a survey was done over the +available spell checking libraries and programs. Unfortunately, the result +was that none of them provided sufficient capabilities to be used as the spell +checking engine in Vim, for various reasons: + +- Missing support for multibyte encodings. At least UTF-8 must be supported, + so that more than one language can be used in the same file. + Doing on-the-fly conversion is not always possible (would require iconv + support). +- For the programs and libraries: Using them as-is would require installing + them separately from Vim. That's mostly not impossible, but a drawback. +- Performance: A few tests showed that it's possible to check spelling on the + fly (while redrawing), just like syntax highlighting. But the mechanisms + used by other code are much slower. Myspell uses a hashtable, for example. + The affix compression that most spell checkers use makes it slower too. +- For using an external program like aspell a communication mechanism would + have to be setup. That's complicated to do in a portable way (Unix-only + would be relatively simple, but that's not good enough). And performance + will become a problem (lots of process switching involved). +- Missing support for words with non-word characters, such as "Etten-Leur" and + "et al.", would require marking the pieces of them OK, lowering the + reliability. +- Missing support for regions or dialects. Makes it difficult to accept + all English words and highlight non-Canadian words differently. +- Missing support for rare words. Many words are correct but hardly ever used + and could be a misspelled often-used word. +- For making suggestions the speed is less important and requiring to install + another program or library would be acceptable. But the word lists probably + differ, the suggestions may be wrong words. + + +Spelling suggestions *develop-spell-suggestions* + +For making suggestions there are two basic mechanisms: +1. Try changing the bad word a little bit and check for a match with a good + word. Or go through the list of good words, change them a little bit and + check for a match with the bad word. The changes are deleting a character, + inserting a character, swapping two characters, etc. +2. Perform soundfolding on both the bad word and the good words and then find + matches, possibly with a few changes like with the first mechanism. + +The first is good for finding typing mistakes. After experimenting with +hashtables and looking at solutions from other spell checkers the conclusion +was that a trie (a kind of tree structure) is ideal for this. Both for +reducing memory use and being able to try sensible changes. For example, when +inserting a character only characters that lead to good words need to be +tried. Other mechanisms (with hashtables) need to try all possible letters at +every position in the word. Also, a hashtable has the requirement that word +boundaries are identified separately, while a trie does not require this. +That makes the mechanism a lot simpler. + +Soundfolding is useful when someone knows how the words sounds but doesn't +know how it is spelled. For example, the word "dictionary" might be written +as "daktonerie". The number of changes that the first method would need to +try is very big, it's hard to find the good word that way. After soundfolding +the words become "tktnr" and "tkxnry", these differ by only two letters. + +To find words by their soundfolded equivalent (soundalike word) we need a list +of all soundfolded words. A few experiments have been done to find out what +the best method is. Alternatives: +1. Do the sound folding on the fly when looking for suggestions. This means + walking through the trie of good words, soundfolding each word and + checking how different it is from the bad word. This is very efficient for + memory use, but takes a long time. On a fast PC it takes a couple of + seconds for English, which can be acceptable for interactive use. But for + some languages it takes more than ten seconds (e.g., German, Catalan), + which is unacceptably slow. For batch processing (automatic corrections) + it's too slow for all languages. +2. Use a trie for the soundfolded words, so that searching can be done just + like how it works without soundfolding. This requires remembering a list + of good words for each soundfolded word. This makes finding matches very + fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte. + For some languages more than the original word list. +3. Like the second alternative, but reduce the amount of memory by using affix + compression and store only the soundfolded basic word. This is what Aspell + does. Disadvantage is that affixes need to be stripped from the bad word + before soundfolding it, which means that mistakes at the start and/or end + of the word will cause the mechanism to fail. Also, this becomes slow when + the bad word is quite different from the good word. + +The choice made is to use the second mechanism and use a separate file. This +way a user with sufficient memory can get very good suggestions while a user +who is short of memory or just wants the spell checking and no suggestions +doesn't use so much memory. + + +Word frequency + +For sorting suggestions it helps to know which words are common. In theory we +could store a word frequency with the word in the dictionary. However, this +requires storing a count per word. That degrades word tree compression a lot. +And maintaining the word frequency for all languages will be a heavy task. +Also, it would be nice to prefer words that are already in the text. This way +the words that appear in the specific text are preferred for suggestions. + +What has been implemented is to count words that have been seen during +displaying. A hashtable is used to quickly find the word count. The count is +initialized from words listed in COMMON items in the affix file, so that it +also works when starting a new file. + +This isn't ideal, because the longer Vim is running the higher the counts +become. But in practice it is a noticeable improvement over not using the word +count. + +============================================================================== +3. Assumptions *design-assumptions* + +The following sections define the portability and compatibility constraints +that all Vim code and build tools must adhere to. + + +MAKEFILES *assumptions-makefiles* + *POSIX.1-2001* + +Vim's main Makefiles target maximum portability, relying solely on features +defined in POSIX.1-2001 `make` and ignoring later POSIX standards or GNU/BSD +extensions. In practical terms, avoid: + + – % pattern rules + – modern assignment (`:=`, `::=`) outside POSIX.1-2001 + – special targets (`.ONESHELL`, `.NOTPARALLEL`, `.SILENT`, …) + – order-only prerequisites (`|`) or automatic directory creation + – GNU/BSD conditionals (`ifdef`, `ifndef`, `.for`/`.endfor`, …) + +Since POSIX.1-2001 supports only traditional suffix rules, every object built +in a separate directory must have an explicit rule. For example: + + objects/evalbuffer.o: evalbuffer.c + $(CCC) -o $@ evalbuffer.c + +This verbosity ensures that the same Makefile builds Vim unchanged with the +default `make` on Linux, *BSD, macOS, Solaris, AIX, HP-UX and virtually any +Unix-like OS. + +Some platform-specific Makefiles (e.g., for Windows, NSIS, or Cygwin) may use +more advanced features when compatibility with basic make is not required. + + +C COMPILER *assumptions-C-compiler* + *ANSI-C* *C89* *C90* *C95* *C99* + +Vim strives for maximum portability (see |design-multi-platform|) and must +still build with Compaq C V6.4-005 on OpenVMS VAX V7.3. + +Therefore, the latest ISO C standard we follow is: + + `C95` (ISO/IEC 9899:1990/AMD1:1995) + +In addition, the following two `C99` features are explicitly allowed: + – `//` comments, as required by |style-comments|; + – the `_Bool` type. + +Platform-specific code may use any newer compiler features supported on that +platform. + + +SIZE OF VARIABLES *assumptions-variables* + + char 8-bit signed + char_u 8-bit unsigned + int 32- or 64-bit signed (16-bit possible on legacy systems) + unsigned 32- or 64-bit unsigned + long at least 32-bit signed (large enough to hold a pointer) + + +============================================================================== +4. Coding style *coding-style* These are the rules to use when making changes to the Vim source code. Please stick to these rules, to keep the sources readable and maintainable. @@ -198,23 +395,6 @@ Other source files do not yet correspond to the .clang-format file. This may change in the future and they may be reformatted as well. -C COMPILER *style-compiler* *ANSI-C* *C89* *C99* - -The minimal C compiler version supported is C89, also known as ANSI C. -Later standards, such as C99, are not widely supported, or at least not 100% -supported. Therefore we use only some of the C99 features and explicitly -disallow some (this will gradually be adjusted over time). - -Features not to be used ~ - -These C99 features are not to be used, because not enough compilers support -them: -- Variable length arrays (even in C11 this is an optional feature). -- C99 _Bool and _Complex types. -- "inline" (it's hardly ever needed, let the optimizer do its work) -- flexible array members: Not supported by HP-UX C compiler (John Marriott) - - COMMENTS *style-comments* Try to avoid putting multiline comments inside a function body: if the @@ -513,153 +693,4 @@ OK: do while (cond); -============================================================================== -3. Design decisions *design-decisions* - -Folding - -Several forms of folding should be possible for the same buffer. For example, -have one window that shows the text with function bodies folded, another -window that shows a function body. - -Folding is a way to display the text. It should not change the text itself. -Therefore the folding has been implemented as a filter between the text stored -in a buffer (buffer lines) and the text displayed in a window (logical lines). - - -Naming the window - -The word "window" is commonly used for several things: A window on the screen, -the xterm window, a window inside Vim to view a buffer. -To avoid confusion, other items that are sometimes called window have been -given another name. Here is an overview of the related items: - -screen The whole display. For the GUI it's something like 1024x768 - pixels. The Vim shell can use the whole screen or part of it. -shell The Vim application. This can cover the whole screen (e.g., - when running in a console) or part of it (xterm or GUI). -window View on a buffer. There can be several windows in Vim, - together with the command line, menubar, toolbar, etc. they - fit in the shell. - - -Spell checking *develop-spell* - -When spell checking was going to be added to Vim a survey was done over the -available spell checking libraries and programs. Unfortunately, the result -was that none of them provided sufficient capabilities to be used as the spell -checking engine in Vim, for various reasons: - -- Missing support for multibyte encodings. At least UTF-8 must be supported, - so that more than one language can be used in the same file. - Doing on-the-fly conversion is not always possible (would require iconv - support). -- For the programs and libraries: Using them as-is would require installing - them separately from Vim. That's mostly not impossible, but a drawback. -- Performance: A few tests showed that it's possible to check spelling on the - fly (while redrawing), just like syntax highlighting. But the mechanisms - used by other code are much slower. Myspell uses a hashtable, for example. - The affix compression that most spell checkers use makes it slower too. -- For using an external program like aspell a communication mechanism would - have to be setup. That's complicated to do in a portable way (Unix-only - would be relatively simple, but that's not good enough). And performance - will become a problem (lots of process switching involved). -- Missing support for words with non-word characters, such as "Etten-Leur" and - "et al.", would require marking the pieces of them OK, lowering the - reliability. -- Missing support for regions or dialects. Makes it difficult to accept - all English words and highlight non-Canadian words differently. -- Missing support for rare words. Many words are correct but hardly ever used - and could be a misspelled often-used word. -- For making suggestions the speed is less important and requiring to install - another program or library would be acceptable. But the word lists probably - differ, the suggestions may be wrong words. - - -Spelling suggestions *develop-spell-suggestions* - -For making suggestions there are two basic mechanisms: -1. Try changing the bad word a little bit and check for a match with a good - word. Or go through the list of good words, change them a little bit and - check for a match with the bad word. The changes are deleting a character, - inserting a character, swapping two characters, etc. -2. Perform soundfolding on both the bad word and the good words and then find - matches, possibly with a few changes like with the first mechanism. - -The first is good for finding typing mistakes. After experimenting with -hashtables and looking at solutions from other spell checkers the conclusion -was that a trie (a kind of tree structure) is ideal for this. Both for -reducing memory use and being able to try sensible changes. For example, when -inserting a character only characters that lead to good words need to be -tried. Other mechanisms (with hashtables) need to try all possible letters at -every position in the word. Also, a hashtable has the requirement that word -boundaries are identified separately, while a trie does not require this. -That makes the mechanism a lot simpler. - -Soundfolding is useful when someone knows how the words sounds but doesn't -know how it is spelled. For example, the word "dictionary" might be written -as "daktonerie". The number of changes that the first method would need to -try is very big, it's hard to find the good word that way. After soundfolding -the words become "tktnr" and "tkxnry", these differ by only two letters. - -To find words by their soundfolded equivalent (soundalike word) we need a list -of all soundfolded words. A few experiments have been done to find out what -the best method is. Alternatives: -1. Do the sound folding on the fly when looking for suggestions. This means - walking through the trie of good words, soundfolding each word and - checking how different it is from the bad word. This is very efficient for - memory use, but takes a long time. On a fast PC it takes a couple of - seconds for English, which can be acceptable for interactive use. But for - some languages it takes more than ten seconds (e.g., German, Catalan), - which is unacceptably slow. For batch processing (automatic corrections) - it's too slow for all languages. -2. Use a trie for the soundfolded words, so that searching can be done just - like how it works without soundfolding. This requires remembering a list - of good words for each soundfolded word. This makes finding matches very - fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte. - For some languages more than the original word list. -3. Like the second alternative, but reduce the amount of memory by using affix - compression and store only the soundfolded basic word. This is what Aspell - does. Disadvantage is that affixes need to be stripped from the bad word - before soundfolding it, which means that mistakes at the start and/or end - of the word will cause the mechanism to fail. Also, this becomes slow when - the bad word is quite different from the good word. - -The choice made is to use the second mechanism and use a separate file. This -way a user with sufficient memory can get very good suggestions while a user -who is short of memory or just wants the spell checking and no suggestions -doesn't use so much memory. - - -Word frequency - -For sorting suggestions it helps to know which words are common. In theory we -could store a word frequency with the word in the dictionary. However, this -requires storing a count per word. That degrades word tree compression a lot. -And maintaining the word frequency for all languages will be a heavy task. -Also, it would be nice to prefer words that are already in the text. This way -the words that appear in the specific text are preferred for suggestions. - -What has been implemented is to count words that have been seen during -displaying. A hashtable is used to quickly find the word count. The count is -initialized from words listed in COMMON items in the affix file, so that it -also works when starting a new file. - -This isn't ideal, because the longer Vim is running the higher the counts -become. But in practice it is a noticeable improvement over not using the word -count. - -============================================================================== -4. Assumptions *design-assumptions* - -Size of variables: -char 8 bit signed -char_u 8 bit unsigned -int 32 or 64 bit signed (16 might be possible with limited features) -unsigned 32 or 64 bit unsigned (16 as with ints) -long 32 or 64 bit signed, can hold a pointer - -Note that some compilers cannot handle long lines or strings. The C89 -standard specifies a limit of 509 characters. - vim:tw=78:ts=8:noet:ft=help:norl: