man.vim: Recognise hyphenated-at-eol cross-references (#12609)

Manual pages requested for output may undergo formatting
arranged by some roff-descendant program. Lines longer
than MANWIDTH or COLUMNS or real-estate width of a device
(with support for horizontal scrolling considered) can be
divided at either blank characters and/or at groups of word
characters (syllables) according to supported hyphenation
rules (although page authors are free to disable hyphenation
or prevent particular words from being hyphenated).

Groff‘s manual describes it as follows:

    5.1.2 Hyphenation

    Since the odds are not great for finding a set of words, for
    every output line, which fit nicely on a line without
    inserting excessive amounts of space between words, gtroff
    hyphenates words so that it can justify lines without
    inserting too much space between words. It uses an internal
    hyphenation algorithm (a simplified version of the algorithm
    used within TeX) to indicate which words can be hyphenated
    and how to do so. When a word is hyphenated, the first part
    of the word is added to the current filled line being output
    (with an attached hyphen), and the other portion is added to
    the next line to be filled.

It would be expedient for autoload/dist/man.vim (along with
syntax/man.vim‘s highlighting and ftplugin/man.vim‘s Ctrl-],
\K mappings) to allow for hyphenation of cross-references
to manual pages.

For example,

  # Launch Vim [v9.0; patched: 1-1378, 1499] as follows:
  MANWIDTH=80 vim --not-a-term +MANPAGER '+Man man' '+/conv(1)' '+norm B'

  # Press Ctrl-] with cursor on _m_: "... use man‐
  # conv(1) directly."_______________________[^]
  #
  # (Man v2.11.2)

  # Launch Vim as follows:
  MANWIDTH=80 vim --not-a-term +MANPAGER '+Man git' '+/config(1)' '+norm B'

  # Press Ctrl-] with cursor on _g_: "... in git-
  # config(1) for a more ..."_______________[^]
  #
  # (Git v2.39.2)

Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>

2 files changed, 58 insertions, 20 deletions

diff --git a/runtime/autoload/dist/man.vim b/runtime/autoload/dist/man.vim
index 6ef47f8b78..5b8b4456db 100644
--- a/runtime/autoload/dist/man.vim
+++ b/runtime/autoload/dist/man.vim
@@ -21,31 +21,65 @@ catch /E145:/
   " Ignore the error in restricted mode
 endtry
 
+func s:ParseIntoPageAndSection()
+  " Accommodate a reference that terminates in a hyphen.
+  "
+  " See init_charset_table() at
+  " https://git.savannah.gnu.org/cgit/groff.git/tree/src/roff/troff/input.cpp?h=1.22.4#n6794
+  "
+  " See can_break_after() at
+  " https://git.savannah.gnu.org/cgit/groff.git/tree/src/roff/troff/charinfo.h?h=1.22.4#n140
+  "
+  " Assumptions and limitations:
+  " 1) Manual-page references (in consequence of command-related filenames)
+  "    do not contain non-ASCII HYPHENs (0x2010), any terminating HYPHEN
+  "    must have been introduced to mark division of a word at the end of
+  "    a line and can be discarded; whereas similar references may contain
+  "    ASCII HYPHEN-MINUSes (0x002d) and any terminating HYPHEN-MINUS forms
+  "    a compound word in addition to marking word division.
+  " 2) Well-formed manual-page references always have a section suffix, e.g.
+  "    "git-commit(1)", therefore suspended hyphenated compounds are not
+  "    determined, e.g.     [V] (With cursor at _git-merge-_ below...)
+  "    ".................... git-merge- and git-merge-base. (See git-cherry-
+  "    pick(1) and git-cherry(1).)" (... look up "git-merge-pick(1)".)
+  "
+  " Note that EM DASH (0x2014), a third stooge from init_charset_table(),
+  " neither connects nor divides parts of a word.
+  let str = expand("<cWORD>")
+
+  if str =~ '\%u2010$'	" HYPHEN (-1).
+    let str = strpart(str, 0, strridx(str, "\u2010"))
+
+    " Append the leftmost WORD (or an empty string) from the line below.
+    let str .= get(split(get(getbufline(bufnr('%'), line('.') + 1), 0, '')), 0, '')
+  elseif str =~ '-$'	" HYPHEN-MINUS.
+    " Append the leftmost WORD (or an empty string) from the line below.
+    let str .= get(split(get(getbufline(bufnr('%'), line('.') + 1), 0, '')), 0, '')
+  endif
+
+  " According to man(1), section name formats vary (MANSECT):
+  " 1 n l 8 3 2 3posix 3pm 3perl 3am 5 4 9 6 7
+  let parts = matchlist(str, '\(\k\+\)(\(\k\+\))')
+  return (len(parts) > 2)
+	  \ ? {'page': parts[1], 'section': parts[2]}
+	  \ : {'page': matchstr(str, '\k\+'), 'section': ''}
+endfunc
+
 func dist#man#PreGetPage(cnt)
   if a:cnt == 0
-    let old_isk = &iskeyword
-    if &ft == 'man'
-      setl iskeyword+=(,)
-    endif
-    let str = expand("<cword>")
-    let &l:iskeyword = old_isk
-    let page = substitute(str, '(*\(\k\+\).*', '\1', '')
-    let sect = substitute(str, '\(\k\+\)(\([^()]*\)).*', '\2', '')
-    if match(sect, '^[0-9 ]\+$') == -1
-      let sect = ""
-    endif
-    if sect == page
-      let sect = ""
-    endif
+    let what = s:ParseIntoPageAndSection()
+    let sect = what.section
+    let page = what.page
   else
+    let what = s:ParseIntoPageAndSection()
     let sect = a:cnt
-    let page = expand("<cword>")
+    let page = what.page
   endif
+
   call dist#man#GetPage('', sect, page)
 endfunc
 
 func s:GetCmdArg(sect, page)
-
   if empty(a:sect)
     return shellescape(a:page)
   endif
@@ -75,9 +109,11 @@ func dist#man#GetPage(cmdmods, ...)
     return
   endif
 
-  " To support:	    nmap K :Man <cword>
-  if page == '<cword>'
-    let page = expand('<cword>')
+  " To support:	    nmap K :Man <cWORD><CR>
+  if page ==? '<cword>'
+    let what = s:ParseIntoPageAndSection()
+    let sect = what.section
+    let page = what.page
   endif
 
   if !exists('g:ft_man_no_sect_fallback') || (g:ft_man_no_sect_fallback == 0)
diff --git a/runtime/syntax/man.vim b/runtime/syntax/man.vim
index 4e08cd7342..dfbb35a700 100644
--- a/runtime/syntax/man.vim
+++ b/runtime/syntax/man.vim
@@ -20,7 +20,9 @@ runtime! syntax/ctrlh.vim
 
 syn case ignore
 
-syn match  manReference       "\f\+([1-9][a-z]\=)"
+" See notes about hyphenation in s:ParseIntoPageAndSection of
+" autoload/dist/man.vim.
+syn match  manReference       "\%(\f\+[\u2010-]\%(\n\|\r\n\=\)\s\+\)\=\f\+([1-9]\l*)"
 syn match  manSectionHeading  "^\a.*$"
 syn match  manSubHeading      "^\s\{3\}\a.*$"
 syn match  manOptionDesc      "^\s*[+-][a-z0-9]\S*"