Fish's "built-in" `man` viewer does not respect `man` environment variables

[Valloric]

Repro steps:

$ sh -c 'env HOME=$(mktemp -d) XDG_CONFIG_HOME= XDG_DATA_DIRS= fish'
$ set -x MANWIDTH 30 # set comically narrow man width for easy repro 
$ man man # so tiny!
$ set -h # as wide as the terminal window

I actually set MANWIDTH dynamically, along with a bunch of other man options with MANOPT. None of this is respected by the built-in man viewer.

Please take into account that people need to configure man for accessibility reasons; it's hard for me to read the default man output. Yes, I am aware of the web docs. We grognards like our terminals.

It took quite a while to track this down because I could see with /proc/$ID/environ that the terminal and fish itself were receiving the right env vars. And if I call man directly, fish passes them along and everything works.

$ fish --version
fish, version 4.0.2
$ uname -a
Linux oak 6.12.43+deb13-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.12.43-1 (2025-08-27) x86_64 GNU/Linux

[krobelus]

thanks yeah, IMO set --help should do exactly the same thing as man set, and MANWIDTH is an explicit reason.
set -h should either do the same, or give a condensed version without details or example/copyright sections.
Similar to git foo -h versus git foo --help
But for the time being we don't have a condensed version, so the full version it is.
I'll commit something like this

    __fish_print_help: use man directly

    Since 0fea1dae8c5 (__fish_print_help: Make formatting more man-like,
    2024-10-03), there is barely any difference left between "man abbr"
    and "abbr -h".

    As suggested in
    https://github.com/fish-shell/fish-shell/issues/10625#issuecomment-2567232677

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 3e923ff8e9..b128a394db 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -104,10 +104,11 @@
 
 For distributors
 ----------------
+- builtin comamnds that support the ``--help`` option now require ``man``, removing a direct dependency on ``mandoc`` or ``nroff``.
 - ``fish_indent`` and ``fish_key_reader`` are still built as separate binaries for now, but can also be replaced with a symlink if you want to save disk space (:issue:`10876`).
 - The CMake system was simplified and no longer second-guesses rustup. It will run rustc and cargo via $PATH or in ~/.cargo/bin/.
   If that doesn't match your setup, set the Rust_COMPILER and Rust_CARGO cmake variables (:issue:`11328`).
-- Cygwin support has been reintroduced, since rust gained a Cygwin target (https://github.com/rust-lang/rust/pull/134999, :issue:`11238`).
+- Cygwin support has been reintroduced, since Rust gained a Cygwin target (https://github.com/rust-lang/rust/pull/134999, :issue:`11238`).
 
 --------------
 
diff --git a/share/functions/__fish_print_help.fish b/share/functions/__fish_print_help.fish
index 9b891f78fc..ae718abbda 100644
--- a/share/functions/__fish_print_help.fish
+++ b/share/functions/__fish_print_help.fish
@@ -10,142 +10,19 @@
             set item test
     end
 
-    # Do nothing if the file does not exist
-    if not path is -- $__fish_data_dir/man/man1/$item.1 $__fish_data_dir/man/man1/$item.1.gz; and not status get-file man/man1/$item.1 >/dev/null
-        return 2
-    end
-
-    # Render help output, save output into the variable 'help'
-    set -l help
-    set -l format
-    set -l cols
-    if test -n "$COLUMNS"
-        set cols (math $COLUMNS - 4) # leave a bit of space on the right
-    end
-
-    # Pick which command we are using to render output or fail if none
-    # We prefer mandoc because that doesn't break with unicode input.
-    if command -qs mandoc
-        set format mandoc -c
-        if test -n "$cols"
-            set -a format -O width=$cols
-        end
-    else if command -qs nroff
-        set format nroff -c -man -t
-        if path is -- $__fish_data_dir/groff/fish.tmac
-            set -a format -M$__fish_data_dir/groff -mfish
-        end
-        if test -n "$cols"
-            set -a format -rLL={$cols}n
-        end
-    else
-        echo fish: (_ "Cannot format help; no parser found") >&2
-        return 1
-    end
-
-    if path is -- $__fish_data_dir/man/man1/$item.1
-        # Some nroff versions screw up non-ascii characters.
-        # (even with the locale set correctly!)
-        # Work around that by running preconv first.
-        if command -sq preconv; and test "$format[1]" = nroff
-            set help (preconv -e UTF-8 "$__fish_data_dir/man/man1/$item.1" | $format 2>/dev/null)
-        else
-            set help ($format "$__fish_data_dir/man/man1/$item.1" 2>/dev/null)
-        end
-    else if path is -- $__fish_data_dir/man/man1/$item.1.gz
-        if command -sq preconv; and test "$format[1]" = nroff
-            set help (gunzip -c "$__fish_data_dir/man/man1/$item.1.gz" 2>/dev/null | preconv -e UTF-8 | $format 2>/dev/null)
-        else
-            set help (gunzip -c "$__fish_data_dir/man/man1/$item.1.gz" 2>/dev/null | $format 2>/dev/null)
-        end
-    else
-        set help (status get-file man/man1/$item.1 | $format 2>/dev/null)
-    end
-
-    # The original implementation trimmed off the top 5 lines and bottom 3 lines
-    # from the nroff output. Perhaps that's reliable, but the magic numbers make
-    # me extremely nervous. Instead, let's just strip out any lines that start
-    # in the first column. "normal" manpages put all section headers in the first
-    # column, but fish manpages only leave NAME like that, which we want to trim
-    # away anyway.
-    #
-    # While we're at it, let's compress sequences of blank lines down to a single
-    # blank line, to duplicate the default behavior of `man`, or more accurately,
-    # the `-s` flag to `less` that `man` passes.
-    set -l state blank
-    set -l have_name
-    begin
-        string join \n $error_message
-        for line in $help
-            # categorize the line
-            set -l line_type
-            switch $line
-                case ' *' \t\*
-                    # starts with whitespace, check if it has non-whitespace
-                    printf "%s\n" $line | read -l word __
-                    if test -n $word
-                        set line_type normal
-                    else
-                        # lines with just spaces probably shouldn't happen
-                        # but let's consider them to be blank
-                        set line_type blank
-                    end
-                case ''
-                    set line_type blank
-                case '*'
-                    # Remove man's bolding
-                    set -l name (string replace -ra '(.)'\b'.' '$1' -- $line)
-                    # We start after we have the name
-                    contains -- $name NAME; and set have_name 1
-                    # Everything after COPYRIGHT is useless
-                    contains -- $name COPYRIGHT; and break
-
-                    # not leading space, and not empty, so must contain a non-space
-                    # in the first column. That makes it a header/footer.
-                    set line_type meta
-            end
-
-            set -q have_name[1]; or continue
-            switch $state
-                case normal
-                    switch $line_type
-                        case normal meta
-                            printf "%s\n" $line
-                        case blank
-                            set state blank
-                    end
-                case blank
-                    switch $line_type
-                        case normal meta
-                            echo # print the blank line
-                            printf "%s\n" $line
-                            set state normal
-                        case blank meta
-                            # skip it
-                    end
-            end
-        end
-    end | begin
-        set -l pager (__fish_anypager --with-manpager)
-        and isatty stdout
-        or set pager cat # cannot use a builtin here
-
-        # similar to man, but add -F to quit paging when the help output is brief (#6227)
-        # Also set -X for less < v530, see #8157.
-        set -l lessopts isRF
-        if type -q less; and test (less --version | string match -r 'less (\d+)')[2] -lt 530 2>/dev/null
-            set lessopts "$lessopts"X
-        end
-
-        not set -qx LESS
-        and set -xl LESS $lessopts
-
-        # less options:
-        # -i (--ignore-case) search case-insensitively, like man
-        # -s (--squeeze-blank-lines) not strictly necessary since we already do that above
-        # -R (--RAW-CONTROL-CHARS) to display colors and such
-        # -F (--quit-if-one-screen) to maintain the non-paging behavior for small outputs
-        # -X (--no-init) do not clear the screen, necessary for less < v530 or else short output is dropped
-        $pager
+    set -l tmpfile
+    set -l file (path filter -- \
+                    $__fish_data_dir/man/man1/$item.1 \
+                    $__fish_data_dir/man/man1/$item.1.gz)
+    or begin
+        set -l contents "$(status get-file man/man1/$item.1)"
+        or return 2
+        set tmpfile (__fish_mktemp_relative fish-print-help)
+        set file $tmpfile
+        printf %s\n $contents >$tmpfile
+    end
+    command man $file[1]
+    if set -q tmpfile[1]
+        rm $tmpfile
     end
 end
diff --git a/tests/checks/print-help.fish b/tests/checks/print-help.fish
index b5bf1172d9..ca8d542239 100644
--- a/tests/checks/print-help.fish
+++ b/tests/checks/print-help.fish
@@ -1,6 +1,6 @@
 # RUN: %fish %s
 # Test redirecting builtin help with a pipe
-# REQUIRES: command -v mandoc || command -v nroff
+# REQUIRES: command -v man
 
 set -lx __fish_data_dir (mktemp -d)
 mkdir -p $__fish_data_dir/man/man1

[Valloric]

Thank you for such a quick turnaround! :)

[krobelus]

The only difference to man is that __fish_print_help can receive a contextual error.
We simply prepend it to the man page (ideally with proper escaping).
For example break -h will show

break: ‐h: unknown option

BREAK(1)                                 fish-shell                                BREAK(1)

NAME
       break - stop the current inner loop

SYNOPSIS
...

it's a bit ugly but better than not showing the error.
Very few places actually add error context to __fish_print_help,
for example unlike break -h above, break doesn't and merely shows the man page.
Lots of potential for future minor improvements.

The behavioral changes from the proposed patch are

1. the title, footer and copyright lines from the man page are no longer stripped
2. something like break -h now actually invokes a pager (others like abbr -h already did), since man seems to query /dev/tty rather than isatty stdout like our own implementation

Given that the roff escaping is a bit tricky, and the error at the top of the man page may look weird,
I wonder if commands like break -asdf and break should simply show an error recommending the user run break -h (which ought to do the same thing as man break).

[zanchey]

break --help has weird behaviour, because it's handled entirely separately to other keywords

I think it's fine to just shell out to man for --help, and maybe to help if man isn't installed.