Update ft_hare.{txt,jax}

doc/ft_hare.jax

@@ -1,72 +1,133 @@
 *ft_hare.txt*	Hare プログラミング言語のサポート
 
 ==============================================================================
-☆内容									*hare*
+☆内容							*hare* *hare.vim*
 
-1. 前書き							  |hare-intro|
-2. ファイルタイププラグイン					 |hare-plugin|
-3. 設定							       |hare-settings|
+1. 前書き			|ft-hare-intro|
+2. ファイルタイププラグイン	|ft-hare-plugin|
+3. Haredoc ファイルタイプ	|ft-haredoc-plugin|
+4. インデント設定		|ft-hare-indent|
+5. コンパイラサポート		|compiler-hare|
 
 ==============================================================================
-☆前書き							  *hare-intro*
+☆前書き						*ft-hare-intro*
 
-このプラグインは、Hare プログラミング言語に構文のハイライト、インデント、その
-他の機能を提供する。Hare モジュール内の README ファイルのサポートも提供されて
-いるが、これは |g:filetype_haredoc| を設定して有効にする必要がある。
+このプラグインは、Hare プログラミング言語の構文のハイライト、インデント、およ
+びその他のサポート機能を提供する。
 
-==============================================================================
-☆ファイルタイププラグイン					 *hare-plugin*
 
-このプラグインは、HAREPATH 環境変数の内容を含むように 'path' の値を自動的に設
-定し、|gf| などのコマンドで標準ライブラリまたはサードパーティのモジュールを直
-接開くことができるようにする。HAREPATH が設定されていない場合、デフォルトで、
-ほとんどの Unix 系ファイルシステムの推奨パス、つまり /usr/src/hare/stdlib およ
-び /usr/src/hare/third-party が使用される。
+☆ファイルタイププラグイン				*ft-hare-plugin*
 
-==============================================================================
-☆設定							       *hare-settings*
+このプラグインには、動作を微調整するために |vimrc| 内で定義できるいくつかの異
+なる変数がある。
 
-このプラグインは、vimrc で定義して動作を設定できる少数の変数を提供する。
+さらに、`{ }` ブロックの折り畳みもサポートされている。折り畳みを有効にするに
+は、|after-directory| 内のファイル (例えば、~/.vim/after/ftplugin/hare.vim) に
+以下のコードを追加する: >
 
-							  *g:filetype_haredoc*
-このプラグインは、Hare モジュールを自動的に検出し、README ファイルに "haredoc"
-ファイルタイプを設定できる。ヒューリスティックとして使用される再帰的ディレクト
-リ検索はパフォーマンスに若干の影響を与えるため、この機能はデフォルトで無効に
-なっており、特別にオプトインする必要がある: >
-	let g:filetype_haredoc = 1
-<
-検索動作を調整する方法については、|g:haredoc_search_depth| を参照。
+	setlocal foldmethod=syntax
 
-						    *g:hare_recommended_style*
-公式の Hare スタイルガイドに従って、次のオプションがデフォルトで設定される: >
+ブロックベースの折り畳みでは小さな折り畳みが多数作成される傾向があるため、
+'foldminlines' や 'foldnestmax' などの関連するオプションをいくつか設定すること
+を検討すること。
+
+						*g:hare_recommended_style*
+Hare の公式スタイルガイドに従って、次のオプションがデフォルトで設定されている:
+>
 	setlocal noexpandtab
 	setlocal shiftwidth=0
 	setlocal softtabstop=0
 	setlocal tabstop=8
 	setlocal textwidth=80
-<
-この動作を無効にするには: >
+
+この動作を無効にするには、|vimrc| に次の行を追加する: >
+
 	let g:hare_recommended_style = 0
 <
-							  *g:hare_space_error*
-デフォルトでは、末尾の空白文字とスペース文字が前にあるタブはエラーとしてハイラ
-イトされる。挿入モードでは、これは自動的にオフになる。このハイライトを完全に無
-効にするには: >
-	let g:hare_space_error = 0
-<
-						      *g:haredoc_search_depth*
-デフォルトでは、|g:filetype_haredoc| が有効な場合、カレントディレクトリとその
-直下のサブディレクトリのみ Hare ファイルが検索される。最大検索深度は以下のよう
-に調整する: >
-	let g:haredoc_search_depth = 2
+						*g:hare_symbol_operators*
+デフォルトでは、記号演算子は特別な構文ハイライト表示を受けない (`!`、`?`、`::`
+のみ例外)。他のほとんどの演算子の構文ハイライトを有効にするには、|vimrc| に以
+下の行を追加する: >
+
+	let g:hare_symbol_operators = 1
 <
+							*g:hare_space_error*
+デフォルトでは、末尾の空白文字とスペースに続く <Tab> 文字はエラーとしてハイラ
+イト表示される。挿入モードでは、このハイライト表示は自動的に無効になる。このハ
+イライト表示を完全に無効にするには、|vimrc| に以下の行を追加する: >
+
+	let g:hare_space_error = 0
+
+
+☆Haredoc ファイルタイプ				*ft-haredoc-plugin*
+
+このプラグインは、ディレクトリの再帰検索を使用して、Hare モジュール内の README
+ファイルを自動検出し、"haredoc" ファイルタイプを付与する。これは非常に一般的な
+ファイル名であるため、このプラグインはデフォルトで同じディレクトリ内の Hare
+ソースファイルのみを検索する。
+
+							*g:filetype_haredoc*
+|g:filetype_haredoc| 変数を使用すると、この検索の深さを微調整したり、Hare ド
+キュメントファイルの検出を完全にバイパスしたりできる:
+
 	値		効果~
-	0		カレントディレクトリのみ検索。
-	1		カレントディレクトリと直下のサブディレクトリを検索。
-	2		カレントディレクトリと 2 階層のサブディレクトリを検索。
+	0		自動検出なし
+	1		カレントディレクトリのみを検索 (これがデフォルト)
+	2		サブディレクトリの 1 階層を検索
+	3		サブディレクトリの 2 階層を検索
+
+検索の深さは任意の正の整数にすることができるが、ほとんどの場合、 `2` より大き
+い値では目に見える利点が得られない可能性がある。
+
+
+☆インデント設定					*ft-hare-indent*
+
+このプラグインの他のほとんどの設定とは異なり、インデント設定はバッファごとに設
+定でき、既存のグローバル設定を上書きできる。これを行うには、変数の先頭に |g:|
+ではなく |b:| を付ける。
+
+						*g:hare_indent_match_switch*
+デフォルトでは、"match" および "switch" 条件の継続行は 1 レベルだけインデント
+される: >hare
+
+	const file = match (os::create(path, 0o644,
+		flag::WRONLY | flag::TRUNC)) {
+	case let file: io::file =>
+		yield file;
+	// ...
+
+代わりに 2 レベルインデントして、"if" 条件と "for" 条件に近づけたい場合
+は、|vimrc| に次の行を追加する: >
+
+	let g:hare_indent_match_switch = 2
+<
+							*g:hare_indent_case*
+デフォルトでは、"match" 式と "switch" 式の場合の継続行は 2 レベルインデントさ
+れ、case 本体と視覚的に区別される: >hare
+
+	case ltok::I8, ltok::I16, ltok::I32,
+			ltok::I64, ltok::INT =>
+		// ...
+
+インデント量を変更したい場合は、|g:hare_indent_case| を使って調整できる。有効
+な値は `0`、`1`、`2` である。
+
+
+☆コンパイラサポート					*compiler-hare*
+
+このプラグインは、カレントディレクトリに Makefile が存在することを検出した場
+合、ビルドシステムに `make` を使用することを想定し、'makeprg' はそのまま残す。
+それ以外の場合は、`hare build` が使用される。
+
+							*g:hare_makeprg_params*
+`hare build` を使用する場合、|g:hare_makeprg_params| 変数を使って 'makeprg' に
+追加のコンパイラオプションを指定できる。また、バッファごとに設定することも可能
+である (|g:| の代わりに |b:| を使用)。その場合、既存のグローバル設定は上書きさ
+れる。例: >
+
+	let b:hare_makeprg_params = '-lc -t o'
 
-最大検索深度は任意の整数に設定できるが、2 より大きい値を使用することは推奨され
-ず、ほとんどの状況で具体的なメリットは得られないだろう。
+グローバルのデフォルトは "-q" で、ビルド中に標準出力への書き込みを抑制する。
 
 ==============================================================================
  vim:tw=78:ts=8:noet:ft=help:norl:

en/ft_hare.txt

@@ -1,77 +1,134 @@
 *ft_hare.txt*	Support for the Hare programming language
 
 ==============================================================================
-CONTENTS								*hare*
+CONTENTS						*hare* *hare.vim*
 
-1. Introduction							  |hare-intro|
-2. Filetype plugin						 |hare-plugin|
-3. Settings						       |hare-settings|
+1. Introduction			|ft-hare-intro|
+2. Filetype plugin		|ft-hare-plugin|
+3. Haredoc filetype		|ft-haredoc-plugin|
+4. Indentation settings		|ft-hare-indent|
+5. Compiler support		|compiler-hare|
 
 ==============================================================================
-INTRODUCTION							  *hare-intro*
+INTRODUCTION						*ft-hare-intro*
 
-This plugin provides syntax highlighting, indentation, and other functionality
-for the Hare programming language. Support is also provided for README files
-inside Hare modules, but this must be enabled by setting |g:filetype_haredoc|.
+This plugin provides syntax highlighting, indentation, and other supporting
+functionality for the Hare programming language.
 
-==============================================================================
-FILETYPE PLUGIN							 *hare-plugin*
 
-This plugin automatically sets the value of 'path' to include the contents of
-the HAREPATH environment variable, allowing commands such as |gf| to directly
-open standard library or third-party modules. If HAREPATH is not set, it
-defaults to the recommended paths for most Unix-like filesystems, namely
-/usr/src/hare/stdlib and /usr/src/hare/third-party.
+FILETYPE PLUGIN						*ft-hare-plugin*
 
-==============================================================================
-SETTINGS						       *hare-settings*
+This plugin has a few different variables that can be defined inside your
+|vimrc| to tweak its behavior.
 
-This plugin provides a small number of variables that you can define in your
-vimrc to configure its behavior.
+Additionally, support is provided for folding `{ }` blocks.  To enable folding,
+add the following to a file inside your |after-directory| (e.g.
+~/.vim/after/ftplugin/hare.vim): >
 
-							  *g:filetype_haredoc*
-This plugin is able to automatically detect Hare modules and set the "haredoc"
-filetype for any README files. As the recursive directory search used as a
-heuristic has a minor performance impact, this feature is disabled by default
-and must be specifically opted into: >
-	let g:filetype_haredoc = 1
-<
-See |g:haredoc_search_depth| for ways to tweak the searching behavior.
+	setlocal foldmethod=syntax
 
-						    *g:hare_recommended_style*
-The following options are set by default, in accordance with the official Hare
+Because block-based folding tends to create many small folds, consider setting
+a few related options, such as 'foldminlines' and 'foldnestmax'.
+
+						*g:hare_recommended_style*
+The following options are set by default, in accordance with Hare's official
 style guide: >
+
 	setlocal noexpandtab
 	setlocal shiftwidth=0
 	setlocal softtabstop=0
 	setlocal tabstop=8
 	setlocal textwidth=80
-<
-To disable this behavior: >
+
+To disable this behavior, add the following to your |vimrc|: >
+
 	let g:hare_recommended_style = 0
 <
-							  *g:hare_space_error*
-By default, trailing whitespace and tabs preceded by space characters are
-highlighted as errors. This is automatically turned off when in insert mode.
-To disable this highlighting completely: >
-	let g:hare_space_error = 0
-<
-						      *g:haredoc_search_depth*
-By default, when |g:filetype_haredoc| is enabled, only the current directory
-and its immediate subdirectories are searched for Hare files. The maximum
-search depth may be adjusted with: >
-	let g:haredoc_search_depth = 2
+						*g:hare_symbol_operators*
+By default, symbolic operators do not receive any special highlighting (with
+`!`, `?`, and `::` being the only exceptions).  To enable syntax highlighting
+for most other operators, add the following to your |vimrc|: >
+
+	let g:hare_symbol_operators = 1
 <
+							*g:hare_space_error*
+By default, trailing whitespace and spaces followed by <Tab> characters will
+be highlighted as errors.  This is automatically disabled in Insert mode.  To
+turn off this highlighting completely, add the following to your |vimrc|: >
+
+	let g:hare_space_error = 0
+
+
+HAREDOC FILETYPE					*ft-haredoc-plugin*
+
+This plugin will automatically detect README files inside Hare modules, using
+a recursive directory search, and give them the "haredoc" filetype.  Because
+this is such a common filename, this plugin only searches for Hare source
+files within the same directory by default.
+
+							*g:filetype_haredoc*
+The |g:filetype_haredoc| variable can be used to tweak the depth of this
+search, or bypass the detection of Hare documentation files altogether:
+
 	Value		Effect~
-	0		Only search the current directory.
-	1		Search the current directory and immediate
-			subdirectories.
-	2		Search the current directory and two levels of
-			subdirectories.
-
-The maximum search depth can be set to any integer, but using values higher
-than 2 is not recommended, and will likely provide no tangible benefit in most
-situations.
+	0		No automatic detection
+	1		Search current directory only (this is the default)
+	2		Search one level of subdirectories
+	3		Search two levels of subdirectories
+
+The search depth may be any positive integer, but values higher than `2` are
+unlikely to provide a tangible benefit in most situations.
+
+
+INDENTATION SETTINGS					*ft-hare-indent*
+
+Unlike most other settings for this plugin, the indentation settings may also
+be set per-buffer, overriding any global configuration that exists.  To do
+this, simply prefix the variable with |b:| instead of |g:|.
+
+						*g:hare_indent_match_switch*
+By default, continuation lines for "match" and "switch" conditions are
+indented only one level: >hare
+
+	const file = match (os::create(path, 0o644,
+		flag::WRONLY | flag::TRUNC)) {
+	case let file: io::file =>
+		yield file;
+	// ...
+
+If you instead prefer indenting them two levels, to more closely resemble "if"
+and "for" conditions, add the following line to your |vimrc|: >
+
+	let g:hare_indent_match_switch = 2
+<
+							*g:hare_indent_case*
+By default, continuation lines for cases in "match" and "switch" expressions
+are indented two levels, to visually distinguish them from the body of the
+case: >hare
+
+	case ltok::I8, ltok::I16, ltok::I32,
+			ltok::I64, ltok::INT =>
+		// ...
+
+If you prefer a different amount of indentation, you can adjust it using
+|g:hare_indent_case|.  Valid values include `0`, `1`, and `2`.
+
+
+COMPILER SUPPORT					*compiler-hare*
+
+If this plugin detects a Makefile in the current directory, it will assume you
+wish to use `make` for your build system, and will leave 'makeprg' untouched.
+Otherwise, `hare build` will be used.
+
+							*g:hare_makeprg_params*
+When `hare build` is used, additional compiler options may be appended to
+'makeprg' with the |g:hare_makeprg_params| variable.  It may also be set on a
+per-buffer basis (using |b:| instead of |g:|), overriding any global
+configuration that exists.  For example: >
+
+	let b:hare_makeprg_params = '-lc -t o'
+
+The global default is "-q", to suppress writing to stdout while building.
 
 ==============================================================================
  vim:tw=78:ts=8:noet:ft=help:norl: