Merge pull request #1891 from h-east/update-helphelp

Update helphelp.{txt,jax}

doc/helphelp.jax

@@ -1,4 +1,4 @@
-*helphelp.txt*	For Vim バージョン 9.1.  Last change: 2024 Dec 15
+*helphelp.txt*	For Vim バージョン 9.1.  Last change: 2024 Dec 26
 
 
 		  VIMリファレンスマニュアル    by Bram Moolenaar
@@ -426,17 +426,30 @@ Ex コマンドのブロックを例示するときは、大なり記号 (>) を
 末に書き、小なり記号 (<) をその後ろのブロックの前の最初の非空白文字として書き
 ます。テキストが 1 列目から始まっている行があると、Ex コマンドのブロックはその
 直前で暗黙的に終了となります。例: >
-    function Example_Func()
-	echo "Example"
-    endfunction
+	function Example_Func()
+	  echo "Example"
+	endfunction
 <
-コード例に Vim 構文ハイライトサポートを追加することができます。これは、大なり
-記号 (>) の後に "vim" を追加することで可能です (">vim")。
-例: >vim
-    function Example_Func()
-	echo "Example"
-    endfunction
+コードブロックの構文ハイライトを有効にするには、大なり記号 (>) の後に言語名の
+注釈 (例: "vim") を配置します。例: >vim
+	function Example_Func()
+	  echo "Example"
+	endfunction
 <
+						*g:help_example_languages*
+デフォルトでは、ヘルプファイルは Vim script のハイライトのみをサポートします。
+他の言語の構文ハイライトが必要な場合は、|vimrc| に以下を追加してください: >
+	:let g:help_example_languages = { "vim": "vim", "sh": "bash" }
+キーは注釈マーカー名を表し、値は 'syntax' 名です。
+
+Note: "g:help_example_languages" に "vim" を含めない場合、"vim" の構文ハイライ
+トは有効になりません。"g:help_example_languages" を空の値に設定すると、埋め込
+み言語の構文ハイライトは無効になります。
+
+さらに note: 含まれている 'syntax' スクリプトがそのような趣旨を考慮していない
+場合、ヘルプファイルに任意の構文言語を含めることは必ずしも完璧に機能するとは限
+りません。
+						*help-notation*
 Vim ヘルプファイルでは以下のものがそれぞれハイライトされます:
   - 特殊キーの名前。<PageDown> のような <> 表記で書かれたものと、CTRL-X のよう
     に書かれた制御文字。

en/helphelp.txt

@@ -1,4 +1,4 @@
-*helphelp.txt*	For Vim version 9.1.  Last change: 2024 Dec 15
+*helphelp.txt*	For Vim version 9.1.  Last change: 2024 Dec 26
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -433,17 +433,31 @@ To quote a block of ex-commands verbatim, place a greater than (>) character
 at the end of the line before the block and a less than (<) character as the
 first non-blank on a line following the block.  Any line starting in column 1
 also implicitly stops the block of ex-commands before it.  E.g. >
-    function Example_Func()
-	echo "Example"
-    endfunction
+	function Example_Func()
+	  echo "Example"
+	endfunction
 <
-It's possible to add Vim syntax highlighting support to code examples.  This
-can be done by adding "vim" after the greater than (>) character (">vim").
-E.g: >vim
-    function Example_Func()
-	echo "Example"
-    endfunction
+To enable syntax highlighting for a block of code, place a language name
+annotation (e.g. "vim") after a greater than (>) character.  E.g. >vim
+	function Example_Func()
+	  echo "Example"
+	endfunction
 <
+						*g:help_example_languages*
+By default, help files only support Vim script highlighting.  If you need
+syntax highlighting for other languages, add to your |vimrc|: >
+	:let g:help_example_languages = { "vim": "vim", "sh": "bash" }
+The key represents the annotation marker name, and the value is the 'syntax'
+name.
+
+Note: If you do not include "vim" in "g:help_example_languages", its syntax
+highlighting will not be enabled.  If you set "g:help_example_languages" to an
+empty value, syntax highlighting for embedded languages will be disabled.
+
+Further note: Including arbitrary syntax languages into help files may not
+always work perfectly, if the included 'syntax' script does not account for
+such an import.
+						*help-notation*
 The following are highlighted differently in a Vim help file:
   - a special key name expressed either in <> notation as in <PageDown>, or
     as a Ctrl character as in CTRL-X
@@ -460,15 +474,15 @@ You can find the details in $VIMRUNTIME/syntax/help.vim
 GENDER NEUTRAL LANGUAGE
 
 						*gender-neutral* *inclusion*
-Vim is for everybody, no matter race, gender or anything. For new or updated
-help text, gender neutral language is recommended. Some of the help text is
-many years old and there is no need to change it. We do not make any
+Vim is for everybody, no matter race, gender or anything.  For new or updated
+help text, gender neutral language is recommended.  Some of the help text is
+many years old and there is no need to change it.  We do not make any
 assumptions about the gender of the user, no matter how the text is phrased.
 The goal is that the reader understands how Vim works, the exact wording is
 secondary.
 
 Many online technical style guides include sections about gender neutral
-language. Here are a few: >
+language.  Here are a few: >
 
 	https://developers.google.com/style/pronouns
 	https://techwhirl.com/gender-neutral-technical-writing/