Commit Graph

143 Commits

Author SHA1 Message Date
Fabian Boehm
78cc872904 Remove dangling footnote reference 2023-01-16 17:42:00 +01:00
Fabian Boehm
dc51a12b4f docs: Mention env
Fixes #9482
2023-01-16 17:09:33 +01:00
Fabian Boehm
a4dc6dcb74 docs: Add some more mentions
We should have more cross-linking and mentions of our builtins and
functions, so people can find the dang things.
2022-10-20 19:33:57 +02:00
Fabian Boehm
38b24c2325 docs: Use :doc: role when linking to commands
This makes it so we link to the very top of the document instead of a
special anchor we manually include.

So clicking e.g. :doc:`string <cmds/string>` will link you to
cmds/string.html instead of cmds/string.html#cmd-string.

I would love to have a way to say "this document from the root of the
document path", but that doesn't appear to work, I tried
`/cmds/string`.

So we'll just have to use cmds/string in normal documents and plain
`string` from other commands.
2022-09-24 10:56:43 +02:00
David Adam
71a6f979a5 docs/index: reword default shell section 2022-03-29 13:33:06 +08:00
Fabian Homborg
9575f0eb4f docs: Readd link to full configuration section to index 2022-03-11 19:13:50 +01:00
Fabian Homborg
5af1e64441 Explain the issues of setting fish as login shell
Also stop explaining this in three places. In particular this removes
an FAQ entry.

Fixes #8078
2022-02-18 15:30:57 +01:00
Fabian Homborg
9eb1b7a9ae Revert "index.rst: don't mention current page under "Other help pages""
Unfortunately this removes the index also from the sidebar in other pages. This makes it basically inaccessible.

Maybe there is a way to not show it in the list at the bottom, but this isn't it. Maybe a manual list of pages instead of reusing the TOC?

This reverts commit b5a95317f0.
2022-01-12 21:42:16 +01:00
Johannes Altmanninger
b5a95317f0 index.rst: don't mention current page under "Other help pages"
This is the list of pages at the end of the introduction; no need to
link to the introduction, we're already there.
2022-01-02 12:23:39 +01:00
Johannes Altmanninger
0d3d84a39c Fix typos in documentation 2021-11-18 15:06:12 +01:00
Aaron Gyes
b550b38859 index.rst: copy-edit
Try to improve the quality of this writing.

Evict a paragraph about running Bash from our documentation front
page.
2021-11-05 16:50:19 -07:00
Aaron Gyes
0803a8fc3e Remove Copyright sectionf from doc pages, and a couple missing bits
... from fish.rst
2021-11-04 13:27:52 -07:00
Fabian Homborg
4b46717a91 docs: Move configuration section to language
Instead leave a simple "use config.fish" bit in-place.

Also some minor rewording.
2021-10-23 17:13:36 +02:00
Fabian Homborg
152097ca34 doc: Some more rewordings
I'm struggling to avoid this massive list of files and directories.

Maybe a second section for integrators?
2021-07-23 18:00:57 +02:00
Fabian Homborg
4be6021131 docs: Some de-alienizing of the configuration section
Still not happy with this, it's overwhelming!

Might have to split this into two - one with simple paths and rough
descriptions, and one with the full scoop for experts?
2021-07-20 21:03:55 +02:00
Fabian Homborg
01b0b04cbf docs: Remove lAtEx thing again
Now it's screaming in the man builder.

Honestly, some parts of sphinx aren't very well thought out.
2021-07-14 17:03:41 +02:00
Fabian Homborg
6640f45913 docs: Use a separate top-level document for lAtEx
This screams about duplicate labels even *if this part isn't built!*

So we use another document that we ignore in other builders.

Blergh
2021-07-14 16:42:04 +02:00
Fabian Homborg
36d9e7b6d6 docs: In latex build, just concatenate the important docs
Instead of having a toctree after the "index", just append the
important documents directly. Having one pdf file with different
chapters and sections and such feels better.
2021-07-13 23:06:01 +02:00
Fabian Homborg
21f5032a55 docs: Don't speak of "initialization files"
The file is called "config.fish", not "init.fish". We'll call it
"configuration" now.

"Initialization" might be slightly more precise, but in an irritating
way.

Also some wording improvements to the section. In particular we now
mention config.fish *early*, before the whole shebang.
2021-05-28 20:49:57 +02:00
Fabian Homborg
0e771590e6 docs: Remove stray mention of the IRC channel
This was apparently missed in 1f976a5041.
2021-05-27 21:41:52 +02:00
Fabian Homborg
d5a30ed103 docs: Split off links to other pages into its own section
This is an attempt to make these more visible - the intro section
explains what this is, and then we mention where to go, and after that
we go into installation and stuff.

I don't think putting "where to go" *after* the installation
instruction is correct, but maybe it is? For the time being, we keep
the order as it is.
2021-05-18 22:53:13 +02:00
Fabian Homborg
c38f4980f9 docs: Some tweaks on initialization 2021-05-16 21:27:00 +02:00
Fabian Homborg
d5f9fc84dc docs: Remove "note that"
It's one of my verbal tics, and I don't want it.
2021-05-03 18:39:54 +02:00
Fabian Homborg
d9b212f60b docs: Move some more sections from index to language
These aren't a 100% *exact* fit, but they're mostly language features.
2021-04-16 18:06:33 +02:00
Fabian Homborg
f1d3e7a0db docs: Reorder ToC
Roughly the order I expect these to be used in.
2021-03-31 17:21:46 +02:00
Fabian Homborg
93eaa61294 Split up documentation
This breaks apart the massive "index" document into

1. An "index" document that explains how to install and set up fish
and links to the other documents
2. A "fish-language" document that describes the syntax and semantics
of the language
3. A "fish-interactive" document that describes how to use fish
interactively

No change to the content has been made, only the parts have been moved
from index and some of the formatting (links and header levels) were
fixed.

See #7348.
2021-03-27 15:44:17 +01:00
Fabian Homborg
58177ba091 docs: Replace all internal links with :ref:s
Unlike links, these are checked by sphinx and it complains if they
don't match.

Also they have a better chance of doing something useful in outputs
other than html.
2021-03-26 19:32:14 +01:00
Fabian Homborg
8e6cfa1311 docs: Explicity link a few more sections
This makes it easier to move them around.
2021-03-26 19:32:14 +01:00
Fabian Homborg
c96a07dc96 Revert "Prevent redirecting internal processes to file descriptors above 2"
FDs are inherited, and redirecting those is harmless, and forbidding
that is worse than allowing all.

Fixes #7769.

This reverts commit 11a373f121.
2021-03-03 22:26:33 +01:00
David Adam
39230978b3 docs: call the CHANGELOG "release notes" 2021-02-25 22:46:24 +08:00
ridiculousfish
11a373f121 Prevent redirecting internal processes to file descriptors above 2
The user may write for example:

    echo foo >&5

and fish would try to output to file descriptor 5, within the fish process
itself. This has unpredictable effects and isn't useful. Make this an
error.

Note that the reverse is "allowed" but ignored:

    echo foo 5>&1

this conceptually dup2s stdout to fd 5, but since no builtin writes to fd
5 we ignore it.
2021-02-20 16:16:45 -08:00
Fabian Homborg
b3626d48e7 Highlight keywords differently
This introduces a new variable $fish_color_keyword that will be used
to highlight keywords. If it's not defined, we fall back on
$fish_color_command as before.

An issue here is that most of our keywords have this weird duality of
also being builtins *if* executed without an argument or with
`--help`.

This means that e.g.

    if

is highlighted as a command until you start typing

    if t

and then it turns keyword.
2021-02-07 21:18:51 +01:00
Fabian Homborg
2faf814da4 docs: Point away from set -x
This is a common anti-pattern, we should try to get people to do `set -gx`.
2021-02-01 18:12:24 +01:00
Fabian Homborg
6442dc96d6 docs: Add a loops section to index
This was only in the tutorial - we really should improve the split here.
2021-01-31 13:15:03 +01:00
Fabian Homborg
7eb616b787 docs: Make some things subsections
E.g. autoloading and aliases are both about functions, variable scope
and overrides are both about variables.

It makes sense to group these together, and this might allow us to
collapse some of the TOC later.
2021-01-31 12:34:47 +01:00
Fabian Homborg
02c11e1db5 docs: Put variable expansion before command substitution
That's the order the parent section lists it in.
2021-01-31 12:30:20 +01:00
Fabian Homborg
892330b904 docs: Drop "Other features" header
This has two features now, there's no need to group it.
2021-01-31 11:59:43 +01:00
Fabian Homborg
00fc56f3e1 docs: Drop weird local table of contents from "Installation" section
This is about a page long, it doesn't need links.
2021-01-31 11:57:51 +01:00
Fabian Homborg
ad560e2b80 docs: Expand a bit on the alias/abbr thing
Also move abbr explanation to interactive use (as abbrs are purely an
interactive concept)

(also add an example to tilde expansion, not making a separate commit
for that)
2021-01-31 11:56:19 +01:00
Fabian Homborg
8e8349d714 docs: Unify job control
Remove the redundant "running multiple programs" section and merge the
"job control" and "background" sections.
2021-01-31 11:49:54 +01:00
Fabian Homborg
9fead046b5 docs: Explain the man/help split in the help section 2021-01-31 11:41:46 +01:00
Fabian Homborg
cf800db10a docs: Move things from "Other features" to "Interactive use"
These are interactive features, after all
2021-01-29 20:08:37 +01:00
Fabian Homborg
711fa31871 docs: Remove broken footnote
Oops!
2021-01-27 18:25:46 +01:00
Fabian Homborg
dd64035d23 docs: Some adjustments
Rewordings, :ref: links, typos
2021-01-27 17:39:09 +01:00
Fabian Homborg
cbc9de3663 docs: Make the lines in the code examples shorter
We should typically avoid scrolling even at max-width.

An exception here is the output of `functions` - this prints one very
long line, but it's really not important what's in there specifically,
it's just to illustrate the kind of output you'd get.
2021-01-26 09:29:58 +01:00
Fabian Homborg
b59cad3c5b
Merge pull request #7654 from mattdutson/intro-doc
More improvements to clarity and grammar of Introduction doc page
2021-01-25 19:08:19 +01:00
Fabian Homborg
5f93df240e Fish for bash users: Fix missing word and link it from index 2021-01-22 16:23:09 +01:00
Fabian Homborg
1285957703 docs: Add glob example to variable overrides
And clarify that it'll still run the same things
2021-01-17 10:31:23 +01:00
Fabian Homborg
e192066e98 Add $fish_handle_reflow to disable winch handler
Overriding event handlers is annoying.
2021-01-15 18:37:06 +01:00
Matthew Dutson
d079026ecc Merge branch 'master' into intro-doc 2021-01-12 17:37:16 -06:00