feat: improve search UX with smart std:: prefix and interactive menu

- Implement hybrid search strategy that tries std:: prefix first
  - Searches for std::<pattern> before falling back to original pattern
  - Returns std:: results early if >= 5 matches found
  - Combines both result sets if std:: results are sparse

- Change default behavior to show first match directly
  - Reverts selection menu from default cppman <page> behavior
  - Provides faster access to most common use case

- Move interactive selection menu to -f flag
  - cppman -f <keyword> now shows paginated selection menu
  - Menu displays 20 results per page
  - Navigation: 'n'/'next' for next page, 'p'/'prev' for previous
  - Enter number to select, Enter alone to cancel

- Update documentation
  - Updated program help text to explain new behavior
  - Updated man page with smart search and pagination details
  - Added -n/--max-results option documentation

This improves UX by reducing noise (e.g., 'cppman map' shows std::map
directly) while still providing comprehensive search via -f flag.

Author: aitjcize

bin/cppman

@@ -70,7 +70,7 @@ def main():
                     help='Clear all cached files.'),
         make_option('-f', '--find-page', action='store', type='string',
                     dest='keyword', default=None,
-                    help='Find man page.'),
+                    help='Find man page and show selection menu if multiple matches.'),
         make_option('-o', '--force-update', action='store_true',
                     dest='force', default=False,
                     help="Force cppman to update existing cache when "
@@ -97,7 +97,10 @@ def main():
     ]
 
     parser = OptionParser(
-        usage='Usage: cppman [OPTION...] PAGE...', option_list=option_list)
+        usage='Usage: cppman [OPTION...] PAGE...\n\n'
+              'When PAGE is specified without -f, cppman shows the first match directly.\n'
+              'Search automatically tries std:: prefix first for better results.',
+        option_list=option_list)
 
     options, args = parser.parse_args()
 
@@ -118,7 +121,11 @@ def main():
 
     if options.keyword:
         try:
-            cm.find(options.keyword)
+            keyword = cm.fuzzy_find(options.keyword, options.max_results, show_menu=True)
+            if not keyword:
+                sys.exit(1)
+            pid = cm.man(keyword)
+            os.waitpid(pid, 0)
             sys.exit(0)
         except RuntimeError as e:
             print(e, file=sys.stderr)
@@ -161,7 +168,7 @@ def main():
         sys.exit(1)
 
     try:
-        keyword = cm.fuzzy_find(args[0], options.max_results)
+        keyword = cm.fuzzy_find(args[0], options.max_results, show_menu=False)
         if not keyword:
             sys.exit(1)
 

cppman/main.py

@@ -537,6 +537,21 @@ def _search_keyword(self, pattern):
         self.source = environ.source
 
         self.cursor.execute('PRAGMA case_sensitive_like=ON')
+
+        std_results = []
+        if not pattern.startswith('std::'):
+            std_pattern = 'std::' + pattern
+            std_results = self._fetch_page_by_keyword("%s" % std_pattern)
+            std_results.extend(self._fetch_page_by_keyword("%s %%" % std_pattern))
+            std_results.extend(self._fetch_page_by_keyword("%% %s" % std_pattern))
+            std_results.extend(self._fetch_page_by_keyword("%% %s %%" % std_pattern))
+            std_results.extend(self._fetch_page_by_keyword("%s%%" % std_pattern))
+            std_results = list(set(std_results))
+
+            if len(std_results) >= 5:
+                conn.close()
+                return sorted(std_results, key=lambda e: _sort_search(e, std_pattern))
+
         results = self._fetch_page_by_keyword("%s" % pattern)
         results.extend(self._fetch_page_by_keyword("%s %%" % pattern))
         results.extend(self._fetch_page_by_keyword("%% %s" % pattern))
@@ -546,6 +561,8 @@ def _search_keyword(self, pattern):
         if len(results) == 0:
             results = self._fetch_page_by_keyword("%%%s%%" % pattern)
 
+        results.extend(std_results)
+
         conn.close()
         return sorted(list(set(results)), key=lambda e: _sort_search(e, pattern))
 
@@ -596,8 +613,8 @@ def find(self, pattern):
         else:
             raise RuntimeError('%s: nothing appropriate.' % pattern)
 
-    def fuzzy_find(self, pattern, max_results):
-        """Find pages in database and present an interactive selection menu."""
+    def fuzzy_find(self, pattern, max_results, show_menu=False):
+        """Find pages in database and optionally present an interactive selection menu."""
         results = self._search_keyword(pattern)
         if max_results >= 1:
             results = results[:max_results]
@@ -608,21 +625,48 @@ def fuzzy_find(self, pattern, max_results):
         if len(results) == 1:
             return results[0][1]
 
-        for i, (name, keyword, url) in enumerate(results, 1):
-            print(f"{i}. {keyword} - {name}")
+        if not show_menu:
+            return results[0][1]
+
+        page_size = 20
+        current_page = 0
+        total_pages = (len(results) + page_size - 1) // page_size
 
         while True:
+            start_idx = current_page * page_size
+            end_idx = min(start_idx + page_size, len(results))
+
+            print(f"\n--- Page {current_page + 1}/{total_pages} ---")
+            for i in range(start_idx, end_idx):
+                name, keyword, url = results[i]
+                print(f"{i + 1}. {keyword} - {name}")
+
+            if total_pages > 1:
+                nav_help = []
+                if current_page > 0:
+                    nav_help.append("'p' for previous")
+                if current_page < total_pages - 1:
+                    nav_help.append("'n' for next")
+                print(f"\nEnter number to select, {', '.join(nav_help)}, or press Enter to cancel")
+
             try:
-                selection = input("\nPlease enter the selection: ")
+                selection = input("\nPlease enter the selection: ").strip().lower()
                 if not selection:
                     return None
 
+                if selection in ('n', 'next') and current_page < total_pages - 1:
+                    current_page += 1
+                    continue
+                elif selection in ('p', 'prev', 'previous') and current_page > 0:
+                    current_page -= 1
+                    continue
+
                 idx = int(selection) - 1
                 if 0 <= idx < len(results):
                     return results[idx][1]
                 print("Invalid selection. Please try again.")
             except ValueError:
-                print("Please enter a valid number.")
+                print("Please enter a valid number or navigation command.")
             except KeyboardInterrupt:
                 print("\nOperation cancelled.")
                 return None

misc/cppman.1

@@ -6,9 +6,11 @@ cppman - C++ manual page viewer / fetcher
 .I OPTIONS...
 .B ] PAGE...
 .SH DESCRIPTION
-cppman generates C++ manual pages from cplusplus.com and provide a man\-like interface to view man pages.
+cppman generates C++ manual pages from cplusplus.com and cppreference.com and provides a man\-like interface to view man pages.
 .sp
 By default, cppman fetches man pages on-the-fly, by running the command 'cppman \-c', all available manpages are cached, making offline browsing possible. This is also required if you want to use the system 'man' command.
+.sp
+When searching for a page (e.g., 'cppman map'), cppman automatically tries the std:: prefix first (std::map) for better results. If a page name is specified without the \-f option, cppman displays the first match directly. Use \-f to show an interactive selection menu with pagination support (20 items per page).
 .SS Browsing man pages
 cppman uses Vi Improved as a pager.
 .br
@@ -24,7 +26,7 @@ cache all available man pages from cplusplus.com to enable offline browsing
 .IP "\-C, \-\-clear\-cache"
 clear all cached files
 .IP "\-f KEYWORD, \-\-find\-page=KEYWORD"
-find man page
+find man page and show interactive selection menu if multiple matches are found. The menu displays up to 20 results per page. Use 'n' or 'next' to go to the next page, 'p' or 'prev' to go to the previous page, or enter a number to select a specific page.
 .IP "\-o, \-\-force\-update"
 force cppman to update existing cache when '\-\-cache\-all' or browsing man pages that were already cached
 .IP "\-m MANDB, \-\-use\-mandb=MANDB"
@@ -33,7 +35,9 @@ Accepts 'true' or 'false'. If true, cppman adds manpage path to mandb so that yo
 Select pager to use, accepts 'vim', 'nvim' or 'less'. The default value is 'vim'.
 If 'nvim' is selected, but not available, 'vim' is used as a fallback and vice versa. If either is selected, but neither is available, 'less' is used as a fallback.
 .IP "\-r, \-\-rebuild\-index"
-rebuild index database from cplusplus.com
+rebuild index database from cplusplus.com and cppreference.com
+.IP "\-n NUM, \-\-max\-results=NUM"
+maximum number of search results to show in the selection menu
 .IP "\-v, \-\-version"
 show version information
 .IP "\-h, \-\-help"