github #68: support section suffix completion for man pages

Support prepend and suffix values for insert-sections
Add values for insert-sections for zstyle completion

4 files changed, 31 insertions, 11 deletions

diff --git a/ChangeLog b/ChangeLog
index 20f7eccf3..8a2161a81 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2021-02-13  Oliver Kiddle  <opk@zsh.org>
 
+	* github #68: taiyu.len: Completion/Unix/Command/_man,
+	Completion/Zsh/Command/_zstyle, Doc/Zsh/compsys.yo:
+	support section suffix completion for man pages
+
 	* 47905: Joshua Krusell: Src/Modules/zutil.c,
 	Test/V12zparseopts.ztst: Add leading '-' to zparseopts option
 	parsing errors
diff --git a/Completion/Unix/Command/_man b/Completion/Unix/Command/_man
index 7d55201e3..dba1d13dc 100644
--- a/Completion/Unix/Command/_man
+++ b/Completion/Unix/Command/_man
@@ -6,7 +6,6 @@
 # - We assume that Linux distributions are using either man-db or mandoc
 # - @todo Would be nice to support completing the initial operand as a section
 #   name (on non-Solaris systems)
-# - @todo We don't support the man-db syntax <name>.<section> (e.g., `ls.1`)
 # - @todo We don't support the man-db feature of 'sub-pages' — that is, treating
 #   pairs of operands like `git diff` as `git-diff`
 # - @todo Option exclusivity isn't super accurate
@@ -415,7 +414,7 @@ _man() {
 }
 
 _man_pages() {
-  local pages sopt
+  local pages sopt tmp
 
   # What files corresponding to manual pages can end in.
   local suf='.((?|<->*|ntcl)(|.gz|.bz2|.z|.Z|.lzma))'
@@ -444,13 +443,20 @@ _man_pages() {
   # `POSIX.1.5'.
 
   [[ $variant = solaris* ]] && sopt='-s '
-  if ((CURRENT > 1 || noinsert)) ||
-      ! zstyle -t ":completion:${curcontext}:manuals.$sect_dirname" insert-sections
-  then
-    compadd "$@" - ${pages%$~suf}
-  else
-    compadd "$@" -P "$sopt$sect_dirname " - ${pages%$~suf}
+  if ! ((CURRENT > 1 || noinsert)); then
+    zstyle -s ":completion:${curcontext}:manuals.$sect_dirname" insert-sections tmp
   fi
+  case "$tmp" in
+    prepend|true|on|yes|1)
+      compadd "$@" -P "$sopt$sect_dirname " - ${pages%$~suf}
+    ;;
+    suffix)
+      compadd "$@" -s ".$sect_dirname" - ${pages%$~suf}
+    ;;
+    *)
+      compadd "$@" - ${pages%$~suf}
+    ;;
+  esac
 }
 
 _man "$@"
diff --git a/Completion/Zsh/Command/_zstyle b/Completion/Zsh/Command/_zstyle
index bb0e1f5bc..0473dd0fe 100644
--- a/Completion/Zsh/Command/_zstyle
+++ b/Completion/Zsh/Command/_zstyle
@@ -62,6 +62,7 @@ styles=(
   ignore-parents         c:ignorepar
   ignored-patterns	 c:
   insert-ids             c:insert-ids
+  insert-sections	 c:insert-sections
   insert-tab             c:bool
   insert-unambiguous	 c:insunambig
   keep-prefix		 c:keep-prefix
@@ -524,6 +525,11 @@ while (( $#state )); do
           compadd - menu single longer
       ;;
 
+    (insert-sections)
+      _wanted values expl 'where to insert man page section' \
+          compadd - true false prepend suffix
+      ;;
+
     (fake-files)
       _message -e fakes 'prefix and names'
       ;;
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 5f717d522..729b4e5d3 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -1838,14 +1838,18 @@ user is longer than the common prefix to the corresponding IDs.
 kindex(insert-sections, completion style)
 item(tt(insert-sections))(
 This style is used with tags of the form `tt(manuals.)var(X)' when
-completing names of manual pages. If set to `true' and the var(X) in the
-tag name matches the section number of the page being completed, the
-section number is inserted along with the page name. For example, given
+completing names of manual pages. If set and the var(X) in the tag name matches
+the section number of the page being completed, the section number is inserted
+along with the page name. For example, given
 
 example(zstyle ':completion:*:manuals.*' insert-sections true)
 
 tt(man ssh_<TAB>) may be completed to tt(man 5 ssh_config).
 
+The value may also be set to one of `tt(prepend)', or `tt(suffix)'.
+`tt(prepend)' behaves the same as `true' as in the above example, while
+`tt(suffix)' would complete tt(man ssh_<TAB>) as tt(man ssh_config.5).
+
 This is especially useful in conjunction with tt(separate-sections), as
 it ensures that the page requested of tt(man) corresponds to the one
 displayed in the completion listing when there are multiple pages with the