Fish shell man page

[stellarhoof]

Currently, man fish is very sparse, listing only command line options to the fish command itself. One can get information about fish itself through help. Then one could also get information about fish commands, etc... through man. However, I find it jarring having to help first to then man. Moreover, some commands clash with pretty standard ones like (for example) test from coreutils.

bash is great on this matter, where I can just man bash and forget about clunkly web interfaces. I can even use my text editor as a MANPAGER and not break my workflow (especially in Linux where trackpad support is flimsy). How about getting the full fish manual on man fish? Likewise, if this is not feasible, do you recommend a way of generating the man pages myself?

Thanks

[faho]

Fish's documentation currently is mostly only available as html, with the exception of builtins - those are also available as man pages (e.g. man string will show documentation on our string builtin).

We should probably add the other things as man pages as well.

[ridiculousfish]

I have a branch that migrates the docs to Sphinx which I'm going to PR for 3.1, so let's not invest too much here now (soon it will be a lot easier).

[cben]

To mention other options for consuming docs without leaving the terminal:
(I must say I love the bash behavior of help foo just outputting a short summary to stdout much more than fish's launching a browser)

• set -x BROWSER links; help variables or some other text browser. 👩‍💻

  • Annoyingly, if you want it one-time env BROWSER=links help variables won't work because help is a function. [That's a separate discussion of whether relying on env instead of builtin VAR=value command... syntax in the name of fish's design principles actually harms orthogonality. But well, begin; set -l -x BROWSER links; help variables; end is annoyingly verbose and harder to discover, but does work 🆗]
  • set -x BROWSER links --dump; help variables won't do what I hoped because it dumps the whole huge page, not just the section I asked for. 📜

• For most commands, cd --help etc does exactly what I want — outputs docs for just that command to stdout.

  • This is a neat choice, one I didn't expect being used to help in bash, but melds very well with the unix experience of --helping everything 👍
  • This is even special-cased to work for special syntaxes like begin --help or function --help (runs immediately instead of opening multi-line editing waiting for end)! Violating parser/semantics orthogonality but I guess improving discoverability and friendliness, which I can respect 👍. Though having an understanding how begin etc are special syntaxes I hadn't thought to even try that.
  • This does not work for few syntaxes like and --help ("fish: --help: command not found...") 😞
  • This does not cover non-command sections like help variables — you can't variables --help. ☹️

• man and does work 👏 👍 man begin doesn't work on my system fish but I see begin.1, function.1 the man pages do exist on master 👍 man variables doesn't work though.

---

P.S. xref #2170 just for manpage relation.

[wwared]

There is a small issue preventing Sphinx from generating a better man page for the main fish command:

fish-shell/sphinx_doc_src/conf.py

Lines 180 to 184 in 6c05005

	man_pages = [(master_doc, "fish", "fish-shell Documentation", [author], 1)]
	for path in sorted(glob.glob("cmds/*")):
	docname = strip_ext(path)
	cmd = os.path.basename(docname)
	man_pages.append((docname, cmd, get_command_description(path, cmd), "", 1))

This for loop ends up adding another tuple for cmds/fish.rst, which generates the fish man page with only a bare-bones description of the flags, instead of the intended one described by the initial tuple ((master_doc, "fish", "fish-shell Documentation", [author], 1)).

A simple fix would be to either prevent cmds/fish.rst from being added to the list, or to change the name of the generated man page for master_doc from "fish" to "fish-shell" or something else.

[zanchey]

This is now available as fish-doc (and fish-faq/fish-tutorial), though I'll leave this open as it doesn't yet appear in apropos output or referenced from the fish command manpage.