Update pi_netrw.{txt,jax}

Author: h-east

doc/pi_netrw.jax

@@ -1,4 +1,4 @@
-*pi_netrw.txt*  For Vim バージョン 9.1.  Last change: 2024 Oct 21
+*pi_netrw.txt*  For Vim バージョン 9.1.  Last change: 2024 Oct 27
 
 	    ------------------------------------------------
 	    NETRW REFERENCE MANUAL    by Charles E. Campbell
@@ -8,7 +8,7 @@ Author:  Charles E. Campbell  <[email protected]>
 
 Copyright: Copyright (C) 2017 Charles E Campbell    *netrw-copyright*
 	The VIM LICENSE applies to the files in this package, including
-	netrw.vim, pi_netrw.txt, netrwFileHandlers.vim, netrwSettings.vim, and
+        netrw.vim, pi_netrw.txt, netrwSettings.vim, and
 	syntax/netrw.vim.  Like anything else that's free, netrw.vim and its
 	associated files are provided *as is* and comes with no warranty of
 	any kind, either expressed or implied.  No guarantees of
@@ -1434,42 +1434,92 @@ NETRW CLEAN					*netrw-clean* *:NetrwClean* {{{2
 どちらのコマンドも、本当に削除していいかどうかを確認するダイアログが最初に表示
 されます。ファイルを削除する権限がない場合はエラーメッセージが表示されます。
 
-						*netrw-gx*
+                                                *netrw-gx* *Open* *Launch*
 ☆特殊ハンドラでブラウジングをカスタマイズ	*netrw-x* *netrw-handler* {{{2
 
 html, gif, jpeg, (word/office) doc などのファイルは専用ハンドラ (コンピュータ
 にあらかじめ備わっているようなツール) で処理するのが一番です。Netrw ではそのよ
-うな専用ハンドラの呼び出しをサポートしています: >
+うな専用ハンドラの呼び出しをサポートしています:
+
+	* ファイルパスの上にあるカーソルで gx を押すか、netrw バッファで x を
+	  押す。前者は |g:netrw_nogx| 変数を定義することで無効にできます。
+	* コマンド ラインで、:Open <path> と入力します
+
+ビジュアルモード (|visual-start| を参照) を使用して、特殊ハンドラが使用するテ
+キストを選択することもできます。通常、gx はカーソルの下のテキストを取得するた
+めに近くの URL またはファイル名をチェックします。|expand()| が使用するテキスト
+は、|g:netrw_gx| 変数 (オプションには "<cword>"、"<cWORD>" が含まれます) を介
+して変更できます。Note expand("<cfile>") は、|'isfname'| の設定に依存すること
+に注意してください。または、ビジュアル選択 (|visual-block| を参照) を行ってか
+ら gx を押すことで、gx が使用するテキストを選択することもできます。
+
+選択関数は、関数 Netrw_get_URL_<filetype> を追加することで各ファイルタイプに適
+応できます。<filetype> は &filetype で指定します。
+この関数は、gx が使用する URL またはファイル名を返す必要があり、空の文字列を返
+す場合はデフォルトの動作に戻ります。
+例えば、Markdown と HTML のリンク用の特別なハンドラは、
+>
+" 正確なカーソル位置に関係なく、gx を隠しリンクで動作させる関数 Netrw_get_URL_markdown()
+  " 次のような markdown URL [link text](http://ya.ru 'yandex search')
+  try
+    let save_view = winsaveview()
+    if searchpair('\[.\{-}\](', '', ')\zs', 'cbW', '', line('.')) > 0
+      return matchstr(getline('.')[col('.')-1:], '\[.\{-}\](\zs' .. g:netrw_regex_url .. '\ze\(\s\+.\{-}\)\?)')
+    endif
+  finally
+    call winrestview(save_view)
+    return ''
+  endtry
+endfunction
+
+function Netrw_get_URL_html()
+  " 次のような HTML URL <a href='http://www.python.org'>Python is here</a>
+  "                     <a href="http://www.python.org"/>
+  try
+    let save_view = winsaveview()
+    if searchpair('<a\s\+href=', '', '\%(</a>\|/>\)\zs', 'cbW', '', line('.')) > 0
+      return matchstr(getline('.')[col('.') - 1 : ],
+            \ 'href=["'.."'"..']\?\zs\S\{-}\ze["'.."'"..']\?/\?>')
+    endif
+  finally
+    call winrestview(save_view)
+    return ''
+  endtry
+endfunction
+<
+
+ファイルパス以外に、カーソルの下のテキストが URL である場合もあります。Netrw
+は、デフォルトで次の正規表現を使用して、カーソルの下のテキストが URL であるか
+どうかを判断します。
+>
+	g:netrw_regex_url = '\%(\%(http\|ftp\|irc\)s\?\|file\)://\S\{-}'
+<
 
-	* ファイル一覧表示中に "x" キーを押す
-	* ファイルを開いているときに、ファイル名の上で gx を押す
-<	  (後ろは |g:netrw_nogx| が設定されている場合は使えません)
+Netrw は、次の方法で特殊ハンドラを決定します:
 
-Netrw は次の方法で専用ハンドラを決定します:
+  * |g:netrw_browsex_viewer| が存在する場合、それを使用してファイルを表示しよ
+    うとします。便利な設定の例 (<.vimrc> に配置):
+    使用したいビューアがリモート URL ディレクトリの処理をサポートしていない場
+    合は、|g:netrw_browsex_support_remote| を 0 に設定します。
+  * 上記以外:
 
-  * |g:netrw_browsex_viewer| が設定されているときは、それを使ってファイルを開
-    きます。例えば次のような設定が便利です (<.vimrc>で設定する): >
+    * Windows では			: explorer.exe が使用されます
+    * Mac OS X では			: open が使用されます
+    * Linux では			: xdg-open が使用されます
 
-	:let g:netrw_browsex_viewer= "kfmclient exec"
-<   or >
-	:let g:netrw_browsex_viewer= "xdg-open"
-<
-    もし、使いたいビューアがリモートURLディレクトリの処理をサポートしていない場合は、
-    |g:netrw_browsex_support_remote| を 0 に設定してください。
-  * Windows 32 or 64 では、URL と FileProtocolHandler dll が使われます。
-  * Gnome (with gnome-open): gnome-open が使われます。
-  * KDE (with kfmclient)   : kfmclient が使われます。
-  * Mac OS X               : open が使われます。
-
-gx マッピングはすべてのバッファに適用できます。カーソル位置の単語に "gx" を適
-用すると、それに対し netrw は特別な処置を行います (ちょうど "x" が netrw バッ
-ファに対して行うように)。特別な処置を行うテキストをビジュアルモード
-(|visual-start| 参照) により選択することもできます。通常 gx はカーソル位置のテ
-キストを取得するのに expand("<cfile>") を使用しますが、|g:netrw_gx| 変数で
-|expand()| が使用する引数を変えることができます ("<cword>", "<cWORD>" を含むオ
-プション)。Note: expand("<cfile>") は |'isfname'| の設定に依存します。また、代
-わりに gx で使用するテキストをビジュアル選択を行っておき (|visual-block| 参
-照)、その後 gx を押す方法でもよいです。
+適切なハンドラでファイル <filepath> を開くには、以下を入力します
+
+	:Open <filepath>
+
+シェルでも Vim のコマンドラインでもエスケープは必要ありません。
+
+特定のアプリケーションを起動するには、<app> <args>、多くの場合、<args> は
+<filepath> です。
+
+	:Launch <app> <args>.
+
+<args> は作為的に複雑になる可能性があり、特に多くのファイルパスが含まれる場合、
+エスケープはユーザーに任されます。
 
 関連設定:
 	|g:netrw_gx|	gx がどのようにカーソル位置のテキストを取得するか制御

en/pi_netrw.txt

@@ -1,4 +1,4 @@
-*pi_netrw.txt*  For Vim version 9.1.  Last change: 2024 Oct 21
+*pi_netrw.txt*  For Vim version 9.1.  Last change: 2024 Oct 27
 
 	    ------------------------------------------------
 	    NETRW REFERENCE MANUAL    by Charles E. Campbell
@@ -8,7 +8,7 @@ Author:  Charles E. Campbell  <[email protected]>
 
 Copyright: Copyright (C) 2017 Charles E Campbell    *netrw-copyright*
 	The VIM LICENSE applies to the files in this package, including
-	netrw.vim, pi_netrw.txt, netrwFileHandlers.vim, netrwSettings.vim, and
+        netrw.vim, pi_netrw.txt, netrwSettings.vim, and
 	syntax/netrw.vim.  Like anything else that's free, netrw.vim and its
 	associated files are provided *as is* and comes with no warranty of
 	any kind, either expressed or implied.  No guarantees of
@@ -1469,42 +1469,93 @@ With either form of the command, netrw will first ask for confirmation
 that the removal is in fact what you want to do.  If netrw doesn't have
 permission to remove a file, it will issue an error message.
 
-						*netrw-gx*
+                                                *netrw-gx* *Open* *Launch*
 CUSTOMIZING BROWSING WITH A SPECIAL HANDLER	*netrw-x* *netrw-handler* {{{2
 
 Certain files, such as html, gif, jpeg, (word/office) doc, etc, files, are
 best seen with a special handler (ie. a tool provided with your computer's
-operating system).  Netrw allows one to invoke such special handlers by: >
+operating system).  Netrw allows one to invoke such special handlers by:
 
-	* when Exploring, hit the "x" key
-	* when editing, hit gx with the cursor atop the special filename
-<	  (latter not available if the |g:netrw_nogx| variable exists)
+        * hitting gx with the cursor atop the file path or alternatively x
+          in a netrw buffer; the former can be disabled by defining the
+          |g:netrw_nogx| variable
+        * when in command line, typing :Open <path>
 
-Netrw determines which special handler by the following method:
+One may also use visual mode (see |visual-start|) to select the text that the
+special handler will use.  Normally gx checks for a close-by URL or file name
+to pick up the text under the cursor; one may change what |expand()| uses via the
+|g:netrw_gx| variable (options include "<cword>", "<cWORD>").  Note that
+expand("<cfile>") depends on the |'isfname'| setting.  Alternatively, one may
+select the text to be used by gx by making a visual selection (see
+|visual-block|) and then pressing gx.
 
-  * if |g:netrw_browsex_viewer| exists, then it will be used to attempt to
-    view files.  Examples of useful settings (place into your <.vimrc>): >
+The selection function can be adapted for each filetype by adding a function
+Netrw_get_URL_<filetype>, where <filetype> is given by &filetype.
+The function should return the URL or file name to be used by gx, and will
+fall back to the default behavior if it returns an empty string.
+For example, special handlers for links Markdown and HTML are
+>
+" make gx work on concealed links regardless of exact cursor position
+function Netrw_get_URL_markdown()
+  " markdown URL such as [link text](http://ya.ru 'yandex search')
+  try
+    let save_view = winsaveview()
+    if searchpair('\[.\{-}\](', '', ')\zs', 'cbW', '', line('.')) > 0
+      return matchstr(getline('.')[col('.')-1:], '\[.\{-}\](\zs' .. g:netrw_regex_url .. '\ze\(\s\+.\{-}\)\?)')
+    endif
+  finally
+    call winrestview(save_view)
+    return ''
+  endtry
+endfunction
+
+function Netrw_get_URL_html()
+  " HTML URL such as <a href='http://www.python.org'>Python is here</a>
+  "                  <a href="http://www.python.org"/>
+  try
+    let save_view = winsaveview()
+    if searchpair('<a\s\+href=', '', '\%(</a>\|/>\)\zs', 'cbW', '', line('.')) > 0
+      return matchstr(getline('.')[col('.') - 1 : ],
+            \ 'href=["'.."'"..']\?\zs\S\{-}\ze["'.."'"..']\?/\?>')
+    endif
+  finally
+    call winrestview(save_view)
+    return ''
+  endtry
+endfunction
+<
 
-	:let g:netrw_browsex_viewer= "kfmclient exec"
-<   or >
-	:let g:netrw_browsex_viewer= "xdg-open"
+Other than a file path, the text under the cursor may be a URL.  Netrw uses
+by default the following regular expression to determine if the text under the
+cursor is a URL:
+>
+	g:netrw_regex_url = '\%(\%(http\|ftp\|irc\)s\?\|file\)://\S\{-}'
 <
+
+Netrw determines which special handler by the following method:
+
+  * if |g:netrw_browsex_viewer| exists, then it will be used to attempt to
+    view files.  Examples of useful settings (place into your <.vimrc>):
     If the viewer you wish to use does not support handling of a remote URL
     directory, set |g:netrw_browsex_support_remote| to 0.
-  * for Windows 32 or 64, the URL and FileProtocolHandler dlls are used.
-  * for Gnome (with gnome-open): gnome-open is used.
-  * for KDE (with kfmclient)   : kfmclient is used
-  * for Mac OS X               : open is used.
+  * otherwise:
 
-The gx mapping extends to all buffers; apply "gx" while atop a word and netrw
-will apply a special handler to it (like "x" works when in a netrw buffer).
-One may also use visual mode (see |visual-start|) to select the text that the
-special handler will use.  Normally gx uses expand("<cfile>") to pick up the
-text under the cursor; one may change what |expand()| uses via the
-|g:netrw_gx| variable (options include "<cword>", "<cWORD>").  Note that
-expand("<cfile>") depends on the |'isfname'| setting.  Alternatively, one may
-select the text to be used by gx by making a visual selection (see
-|visual-block|) and then pressing gx.
+    * for Windows			: explorer.exe is used
+    * for Mac OS X			: open is used.
+    * for Linux				: xdg-open is used.
+
+To open a file <filepath> by the appropriate handler, type
+
+	:Open <filepath>
+
+No escaping, neither for the shell, nor for Vim's command-line is needed.
+
+To launch a specific application <app> <args>, often <args> being <filepath>,
+
+	:Launch <app> <args>.
+
+Since <args> can be arbitrarily complex, in particular contain many file
+paths, the escaping is left to the user.
 
 Associated setting variables:
 	|g:netrw_gx|	control how gx picks up the text under the cursor