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.
If a code block includes a line starting with ">", we assume it shows
an interactive session, all lines starting with ">" are commands and
the rest is output.
Unfortunately, in something like:
```
> for val in $PATh
echo "entry: $val"
end
entry: /usr/bin
```
this won't highlight the dangling lines. We could also prefix them
with `>`, but that require us to parse them in blocks or the `end`
would be an error.
So, for now, simply don't give these as a prompt but as a script with
cheesy comments describing the output.
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.
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.
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.
This came up online - here we exclaim that fish has no aliases (which
is true), but then in the main docs we explain that you can use
`alias` to make something (which is also true).
Add a foot note explaining the apparent contradiction.
For the few weird code blocks where default highlighting does not work,
we must add the 'highlight' class manually to get matching backgrounds.
This reuses the background color defined in pygments.css.
There are a few code blocks where the default highlighting does not
work and the documentation looks bad as a result. Usually this happens
when we are demonstrating an important interactive feature, such as
autosuggestions, syntax highlighting, or tab completion.
The pygments highlighter was not designed for code samples like these.
But it is important to show the behavior clearly in the docs. I am
attempting to make these weird examples look as much like the "normal"
code blocks as possible.
https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal
- add missing links for some commands (control flow section)
- fix broken links that use the old syntax (#tut_ links)
- miscellaneous fixing of backticks/emphasis
At least on some versions/systems, pkg-config outputs a trailing
space. Since the usually-desired behavior isn't to have a blank argument,
recommend using `string split -n` instead of `string split`.
Fixes#6836.
[ci skip]
When we say "the XYZ command/builtin", we should typically include a
link. The exceptions are
- In the documentation for that command - no need to link to ulimit in
the ulimit page
- When we've already linked before - not every thing needs to be
clickable, or clicking it will cause the browser to mark fifty words
as visited. This is roughly what wikipedia does for crosslinks.
[ci skip]
This used to use doxygen's html blocks, which don't have a *direct*
equivalent in sphinx in code blocks.
Instead of adding this to the pygments highlighter, let's just use
some roles.
It's a teensy bit awkward as we then use block styling, but we want to
add more of our own styling anyway, so we can presumably get this
somehow, and these html tags look awkward and confuse people.
Fix#6640
[ci skip]
