Make fish --help without docs installed better

[mqudsi]

If the fish man files are not both installed and found, fish --help does nothing.

[faho]

Yes, this uses __fish_print_help.

The workaround is to just use help, which will fall back on
the online documentation and gives nicer formatting to boot.

The alternative would probably involve embedding the text in the binary, which I'm not a massive fan of, so I'd be grateful for any better ideas.

[mqudsi]

That's one option, although personally I don't think - at least for the main entry point of the entire shell - falling back to the online documentation is a good alternative. I think it's OK for the various builtins because they'd be executed within a fish environment, but fish itself should be discoverable even on headless systems when built from source w/ or w/o the documentation.

[faho]

But the fish(1) man page (what fish --help shows) isn't the main entry point of the docs.

In fact it's one of the less useful man pages, listing some of the commandline options for calling fish.

And the actual main page of the docs, fish-doc, is available as a man page and online.

but fish itself should be discoverable even on headless systems when built from source w/ or w/o the documentation.

When is that the case? The release tarballs ship with prebuilt documentation, so if you didn't install them you must have specifically decided against it.

[mqudsi]

Not the entry point of the docs, the entry point of the shell.

You don’t have to decide not to install them if you clone and build if Sphinx isn’t installed.

[faho]

Not the entry point of the docs, the entry point of the shell.

Yes, but the page isn't super helpful! Saying "at least for the main entry point of the entire shell" makes it sound like it's an important page when it's very much not.

If you need help with fish, chances are you need help with the scripting language or some builtin over... "--profile" or something.

And those other things are already only available as man pages or html (on- and offline).

You don’t have to decide not to install them if you clone and build if Sphinx isn’t installed.

Sure. But at that point, you can read the README and install sphinx.

Or just read the rst in your clone.

[faho]

Alright,

• we now print a special error when you try fish --help without the documentation installed that tells you to either install the docs or look it up online
• the other, much more important and helpful, pages are already only available as built documentation (html, man pages, pdf, whatever you built)
• the case of not having documentation installed should be rare (this is a case for keeping pre-built docs in the tarballs)
• if we wanted to bake the text into the binary we would have to have sphinx to build it, in which case we could also just build the documentation directly

so I am closing this. If anyone comes up with a good solution for having our cake (the help text) and eating it (not having to have the user build documentation), speak up and we'll reopen.

[mqudsi]

Thanks. Sounds good to me.