This corrects what looks like wrong alignment of some synopsis lines.
(I think the alignment is not a bad idea but it makes us do more
manual work, maybe we can automate that in future. We still need to
figure out how to translate it to HTML.)
"man -l build/user_doc/man/man1/history.1" before:
string match [-a | --all] [-e | --entire] [-i | --ignore-case]
[-r | --regex] [-n | --index] [-q | --quiet] [-v | --invert]
PATTERN [STRING…]
and after:
string match [-a | --all] [-e | --entire] [-i | --ignore-case]
[-r | --regex] [-n | --index] [-q | --quiet] [-v | --invert]
PATTERN [STRING…]
Also make the lines align the same way in the RST source by carefully
choosing the position of the backslash. I'm not sure why we used
two backslashes per line. Use only one; this gives us no choice
of where to put it so both source and man page output are aligned.
Change tabs to spaces to make the alignment in the source work.
The ellipsis is a grammar metacharacter, just like the []()|.
Write *FOO*… instead of *FOO…*, so the ellipsis is not underlined
in the man page. Not super sure about this one.
This matches the style in man(1) (except that we use the … ligature).
A previous iteration did the reverse (never use a space before the
ellipsis). That would be a smaller change.
We use plural "*OPTIONS*" more often than "*OPTION*...", so let's do
that everywhere.
In some other places where we do have an ellipsis, make sure to use
singular, since the ellipsis already means repetition. This change
is incomplete, and I'm not sure if this is worth it, since it's
subjective, so I might drop it.
Correct the grammar by moving the options after the command argument.
Also group the -c/--command and -p/--path pairs, to convey that the
short and long variants are equivalent.
While at it, consolidate the -C/--do-complete forms, like we usually
do.
One synopsis misrenders as
set [options] VARIABLE*[*INDICES]… VALUES…
Add a missing backslash to fix that. Also go back to uppercase
because I'm not sure why this was changed to lowercase.
Finally, remove the spurious ellipsis after VARIABLE[INDICES].
This element cannot be repeated. Multiple index values and ranges
can be specified but that's already implied by the plural INDICES.
For alteration we usually use "(a | b)", not "{a | b}".
While at it, instead of writing 4/6 subcommands in one line, write them
on separate lines, so it's very obvious that all these are separate
subcommands. We mainly use the (a | b) syntax for long/short options.
The -- is not special here and we don't mention it in other synopses.
It was originally added for a good reason in 98449fec5 (fix `math`
regression, 2017-07-14), along this addition to math.rst:
> You should always place a `--` flag separator before the expression. [...]
However, since 56d913453 (Cache math expressions, 2017-08-24) that
line was changed to
> You don't need to use `--` before the expression even if it begins with a minus sign [...]
Previously, when we got an unknown option with --ignore-unknown, we
would increment woptind but still try to read the same contents.
This means in e.g.
```
argparse -i h -- -ooo -h
```
The `-h` would also be skipped as an option, because after the first
`-o` getopt reads the other two `-o` and skips that many options.
This could be handled more extensively in wgetopt, but the simpler fix
is to just skip to the next argv entry once we have an unknown option
- there's nothing more we can do with it anyway!
Additionally, document this and clearly explain that we currently
don't transform the option.
Fixes#8637
Unfortunately the normal font families like "sans-serif" and
"monospace" are basically broken because the browser defaults are
decades old.
TODO: Inline code is barely distinguishable.
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.
Use the remaining_to_disclose count to determine if all completions
are shown (allows consistent behavior between short and long completion
lists).
Closes#8485
Currently,
set -q --unpath PATH
simply ignores the "--unpath" bit (and same for "--path").
This changes it, so just like exportedness you can check pathness.
Unless we use "complete --require-parameter", we must say "-w32",
not "-w 32", because the second "32" is a positional argument.
Notably, old options do not have this behavior, which is a bit weird,
see #8465
Taken from a discussion in #8459
* fish_key_reader: Simplify default output
It now only prints the bind statement. Timing information and such is
relegated to a separate "verbose" mode.
* Adjust fish_key_reader docs
* Adjust tests
Unlike in other shells, for-loops do not set $status if
1. the loop count is zero, or if
2. the loop body consists of only commands like "set" that don't
set $status.
POSIX for-loops always set an exit status (they set 0 if no loop
iterations). Following that would be awkward because it would add a
lot of complexity in combination with the 2 special cases above.
Document that "for" behaves the same as "set": it will pass through
existing $status, and also the last child's $status.
See the discussion in #8409
Adding the underline in the list of sections makes them bleed
together, making it hard to discern where one ends and the other
begins.
In the body of the text we don't have that issue - multiple links are
rarely next to each other.
Fixes#8439
Unfortunately, currently :program: doesn't link to the program's page.
So we use the old-school :ref: again where we should link, i.e. for
everything that's not the program the current page is about.
Fixes#8438
Documents like fish-tutorial don't need the NAME portion below.
(they also shoudln't be in section 1! These should be section 7,
they aren't for programs.)
the manpage writer will skip NAME if given an empty sstring as
the description.
--
FISH-TUTORIAL(1) fish-shell FISH-TUTORIAL(1)
NAME
fish-tutorial - fish-shell tutorial
This fixes the indentation problem for the SYNOPSIS section by not
inserting the :: literal block. Format it the same way Sphinx does
their own manpages for commands.
Use more semantic markup, like :command:, so that commands are
highlighted in the man pages.
Split by sentence to give `man` a chance to ascertain lines.
Long-term, it should be possible to teach Sphinx to turn :command:s
into references and get us automatic links to articles for matching
cmds/*.
