Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fish shell man page #5521

Closed
stellarhoof opened this issue Jan 12, 2019 · 5 comments
Closed

Fish shell man page #5521

stellarhoof opened this issue Jan 12, 2019 · 5 comments
Labels
docs enhancement
Milestone

Comments

@stellarhoof
Copy link

@stellarhoof stellarhoof commented Jan 12, 2019

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
Copy link
Member

@faho faho commented Jan 18, 2019

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.

@faho faho added enhancement docs labels Jan 18, 2019
@faho faho added this to the fish-future milestone Jan 18, 2019
@ridiculousfish
Copy link
Member

@ridiculousfish ridiculousfish commented Jan 20, 2019

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
Copy link
Contributor

@cben cben commented May 26, 2019

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
Copy link

@wwared wwared commented Jun 21, 2019

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

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.

faho added a commit that referenced this issue Jun 23, 2019
This was clearly intended for index, but because it was called "fish"
it was overwritten by the "fish" command man page.

I also added the tutorial and faq. Both of those might not be *ideal*
as man pages (the tutorial makes references to colors that won't show
up), but it's better to provide them than not.

Hat-tip to @wwared

See #5521.

[ci skip]
@zanchey
Copy link
Member

@zanchey zanchey commented Sep 25, 2019

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.

@zanchey zanchey removed this from the fish-future milestone Dec 12, 2019
@zanchey zanchey added this to the fish 3.1.0 milestone Dec 12, 2019
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Apr 16, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
docs enhancement
Projects
None yet
Development

No branches or pull requests

6 participants