Commit Graph

16 Commits

Author SHA1 Message Date
Johannes Altmanninger
414d9a1eb1 Reference more non-fish shell builtins that have relevant differences
When writing scripts for other shells, it can be confusing and annoying
that our `man` function shadows other manual pages, for example `exec(1p)`
from [Linux man-pages]. I almost never want to see the fish variant for such
contended cases (which obviuosly don't include fish-specific commands like
`string`, only widely-known shell builtins).

For the contented cases like `exec`, the POSIX documentation is more
substantial and useful, since it describes a (sub)set of languages widely
used for scripting.

Because of this I think we should stop overriding the system's man pages.
Nowadays we offer `exec -h` as intuitive way to show the documentation for
the fish-specific command (note that `help` is not a good replacement because
it uses a web browser).

Looking through the contended commands, it seems like for most of them,
the fish version is not substantially different from the system version.
A notable exception is `read` but I don't think it's a very important one.

So I think we should can sacrifice a bit of the native fish-scripting
experience in exchange for playing nicer with other shells. I think the
latter is more important because scripting is not our focus, the way I see it.
So maybe put our manpath at the end.

In lieu of that, let's at least have `exec.rst` reference the system variant.

[Linux man-pages]: https://www.kernel.org/doc/man-pages/

Closes 
2024-04-20 13:34:08 +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
tocic
ade61fd50f docs: Fix typos 2022-09-17 21:31:06 +08:00
David Adam
3a23fdf359 docs: omnibus cleanup
Includes harmonizing the display of options and arguments, standardising
terminology, using the envvar directive more broadly, adding help options to all
commands that support them, simplifying some language, and tidying up multiple
formatting issues.

string documentation is not changed.
2022-03-12 00:21:13 +08:00
David Adam
e23e52a8e9 docs: standardise on definition lists for options
Harmonizes the option listing including formatting in a similar manner to the
synopsis of each entry.
2022-03-12 00:21:12 +08:00
Johannes Altmanninger
2a98b7a593 docs synopsis: make all placeholder arguments uppercase
man(1) uses lowercase placeholders but we usually don't.  Additionally,
the new synopsis autoformatting only recognizes placeholders if they
are uppercase. Use uppercase for all placeholders.
2022-01-19 22:56:41 +08:00
Johannes Altmanninger
c0d1e41313 docs synopsis: add HTML highlighing and automate manpage markup
Recent synopsis changes move from literal code blocks to
[RST line blocks].  This does not translate well to HTML: it's not
rendered in monospace, so aligment is lost.  Additionally, we don't
get syntax highlighting in HTML, which adds differences to our code
samples which are highlighted.

We hard-wrap synopsis lines (like code blocks). To align continuation
lines in manpages we need [backslashes in weird places]. Combined with
the **, *, and `` markup, it's a bit hard to get the alignment right.

Fix these by moving synopsis sources back to code blocks and compute
HTML syntax highlighting and manpage markup with a custom Sphinx
extension.

The new Pygments lexer can tokenize a synopsis and assign the various
highlighting roles, which closely matches fish's syntax highlighing:
- command/keyword (dark blue)
- parameter (light blue)
- operator like and/or/not/&&/|| (cyan)
- grammar metacharacter (black)

For manpage output, we don't project the fish syntax highlighting
but follow the markup convention in GNU's man(1):

	bold text          type exactly as shown.
	italic text        replace with appropriate argument.

To make it easy to separate these two automatically, formalize that
(italic) placeholders must be uppercase; while all lowercase text is
interpreted literally (so rendered bold).
This makes manpages more consistent, see string-join(1) and and(1).

Implementation notes:
Since we want manpage formatting but Sphinx's Pygments highlighing
plugin does not support manpage output, add our custom "synopsis"
directive.  This directive parses differently when manpage output is
specified. This means that the HTML and manpage build processes must
not share a cache, because the parsed doctrees are cached.  Work around
this by using separate cache locations for build targets "sphinx-docs"
(which creates HTML) and "sphinx-manpages".  A better solution would
be to only override Sphinx's ManualPageBuilder but that would take a
bit more code (ideally we could override ManualPageWriter but Sphinx
4.3.2 doesn't really support that).

---

Alternative solution: stick with line blocks but use roles like
:command: or :option: (or custom ones). While this would make it
possible to produce HTML that is consistent with code blocks (by adding
a bit of CSS), the source would look uglier and is harder to maintain.
(Let's say we want to add custom formatting to the [|] metacharacters
in HTML.  This is much easier with the proposed patch.)

---

[RST line blocks]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks
[backslashes in weird places]: https://github.com/fish-shell/fish-shell/pull/8626#discussion_r782837750
2022-01-19 22:56:41 +08:00
Fabian Homborg
57eccb7e1e docs: Readd note about the command to realpath 2021-11-12 18:28:35 +01:00
Fabian Homborg
edc09c8419 Docs: Switch back to vanilla :ref: for commands that should be linked
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 
2021-11-12 18:02:56 +01:00
Aaron Gyes
e6eb049aeb Remove imperialist sabotage to previous commit
Juche!
2021-11-12 04:39:11 -08:00
Aaron Gyes
ac1df310c8 Long march towards more structured text 2021-11-12 04:22:35 -08:00
Fabian Homborg
801d7e3e11 docs: Document that the man pages are for our builtins
For builtins that have the same name as common commands, it might not
be entirely obvious that there is another page.

So, for those builtins, we add a note, but only in the man pages.

(exception is true and false because the note would be longer than the
page, and it's fridging true and false)

Fixes .
2021-07-16 18:21:41 +02:00
Fabian Homborg
0072367512 fish_add_path: Don't resolve symlinks
The case for symlinked directories being duplicated a lot isn't there,
but there *is* a usecase for adding the symlink rather than the
target, and that's homebrew.

E.g. homebrew installs ruby into /usr/local/Cellar/ruby/2.7.1_2/bin,
and links to it from /usr/local/opt/ruby/bin. If we add the target, we
would miss updates.

Having path entries that point to the same location isn't a big
problem - it's a path lookup, so it takes a teensy bit longer. The
canonicalization is mainly so paths don't end up duplicated via weird
spelling and so relative paths can be used.
2020-09-12 19:28:01 +02:00
Fabian Homborg
568f9031aa builtin realpath: Add --no-symlinks option
Taken from GNU realpath, this one makes realpath not resolve symlinks.

It still makes paths absolute and handles duplicate and trailing
slashes.

(useful in fish_add_path)
2020-09-12 19:26:04 +02:00
Delapouite
b8281f1284 doc: homogenize commands titles 2020-04-04 10:44:53 +02:00
Aaron Gyes
85a0ca66e0 We no longer have two doc systems, move sphinx_doc_src back to doc_src 2020-02-19 17:00:35 -08:00