Commit help_sections data file

The help_sections.rs file was added to the tarball only as a quick hack.
There is a cyclic dependency between docs and fish:

"fish_indent" via "crates/build-man-pages" depends on "doc_src/".
So every "touch doc_src/foo.rst && ninja -Cbuild sphinx-docs"
re-builds fish.

In future "fish_indent" should not depend on "crates/build-man-pages".
Until then, a following commit wants to break this cyclic dependency
in a different way: we won't embed man pages (matching historical
behavior), which means that CMake builds won't need to run
sphinx-build.

But sphinx-build is also used for extracting help sections.

Also, the fix for #12082 will use help sections elsewhere in the code.

Prepare to remove the dependency on doc_src by committing the help
sections (we already do elsewhere).

build_tools/make_tarball.sh

@@ -68,13 +68,12 @@ echo "$VERSION" > version
 cmake -G "$BUILD_GENERATOR" -DCMAKE_BUILD_TYPE=Debug "$wd"
 mkdir $PWD/user_doc/src
 FISH_SPHINX_BUILD_DATE=$tag_creation_date \
-FISH_SPHINX_HELP_SECTIONS_OUTPUT=$PWD/user_doc/src/help_sections.rs \
-    $BUILD_TOOL doc
+$BUILD_TOOL doc
 
 TAR_APPEND="$TAR --append --file=$path --mtime=now --owner=0 --group=0 \
     --mode=g+w,a+rX --transform s/^/$prefix\//"
 $TAR_APPEND --no-recursion user_doc
-$TAR_APPEND user_doc/html user_doc/man user_doc/src/help_sections.rs
+$TAR_APPEND user_doc/html user_doc/man
 $TAR_APPEND version
 
 cd -

crates/build-man-pages/build.rs

@@ -1,36 +1,18 @@
-use fish_build_helper::{env_var, workspace_root};
 use std::path::Path;
 
 fn main() {
     let man_dir = fish_build_helper::fish_build_dir().join("fish-man");
     let sec1_dir = man_dir.join("man1");
-    // Running `cargo clippy` on a clean build directory panics, because when rust-embed tries to
-    // embed a directory which does not exist it will panic.
+    // Running `cargo clippy` on a clean build directory panics, because when rust-embed
+    // tries to embed a directory which does not exist it will panic.
     let _ = std::fs::create_dir_all(&sec1_dir);
-
-    let help_sections_path = Path::new(&env_var("OUT_DIR").unwrap()).join("help_sections.rs");
-
-    if env_var("FISH_USE_PREBUILT_DOCS").is_some_and(|v| v == "TRUE") {
-        std::fs::copy(
-            workspace_root().join("user_doc/src/help_sections.rs"),
-            help_sections_path,
-        )
-        .unwrap();
-        return;
+    if !cfg!(clippy) {
+        build_man(&man_dir, &sec1_dir);
     }
-
-    std::fs::write(
-        help_sections_path.clone(),
-        r#"pub static HELP_SECTIONS: &str = "";"#,
-    )
-    .unwrap();
-
-    #[cfg(not(clippy))]
-    build_man(&man_dir, &sec1_dir, &help_sections_path);
 }
 
-#[cfg(not(clippy))]
-fn build_man(man_dir: &Path, sec1_dir: &Path, help_sections_path: &Path) {
+fn build_man(man_dir: &Path, sec1_dir: &Path) {
+    use fish_build_helper::{env_var, workspace_root};
     use std::{
         ffi::OsStr,
         process::{Command, Stdio},
@@ -45,7 +27,6 @@ fn build_man(man_dir: &Path, sec1_dir: &Path, help_sections_path: &Path) {
         &doc_src_dir,
     ]);
 
-    let help_sections_arg = format!("fish_help_sections_output={}", help_sections_path.display());
     let args: &[&OsStr] = {
         fn as_os_str<S: AsRef<OsStr> + ?Sized>(s: &S) -> &OsStr {
             s.as_ref()
@@ -71,8 +52,6 @@ macro_rules! as_os_strs {
             &man_dir,
             &doc_src_dir,
             &sec1_dir,
-            "-D",
-            &help_sections_arg,
         ])
     };
 

crates/build-man-pages/src/lib.rs

@@ -1 +1 @@
-include!(concat!(env!("OUT_DIR"), "/help_sections.rs"));
+

doc_src/cmds/status.rst

@@ -31,7 +31,6 @@ Synopsis
     status build-info
     status get-file FILE
     status list-files [PATH ...]
-    status help-sections
     status terminal
     status test-terminal-feature FEATURE
 
@@ -124,13 +123,6 @@ The following operations (subcommands) are available:
     This lists the files embedded in the fish binary at compile time. Only files where the path starts with the optional *FILE* argument are shown.
     Returns 0 if something was printed, 1 otherwise.
 
-**help-sections**
-    NOTE: this subcommand is intended for fish's internal use.
-
-    List section arguments for the :doc:`help <help>` command.
-    If you have the latest version of fish, these URL fragments are valid on `<https://fishshell.com/docs/current/>`__.
-    Always returns 0.
-
 .. _status-terminal:
 
 **terminal**

doc_src/conf.py

@@ -74,9 +74,7 @@ def extract_sections(app, env):
             f"Unsupported characters in section path: {section}"
         )
     help_sections = "".join(f"{section}\n" for section in sections)
-    Path(output_file).write_text(
-        f"""pub static HELP_SECTIONS: &str = "{help_sections}";"""
-    )
+    Path(output_file).write_text(help_sections)
 
 
 def remove_fish_indent_lexer(app):
@@ -99,7 +97,7 @@ def setup(app):
     app.add_config_value("issue_url", default=None, rebuild="html")
     app.add_config_value(
         "fish_help_sections_output",
-        default=os.environ.get("FISH_SPHINX_HELP_SECTIONS_OUTPUT", ""),
+        default="",
         rebuild="man",
         types=str,
     )

po/de.po

@@ -2799,9 +2799,6 @@ msgstr ""
 msgid "List embedded files contained in the fish binary"
 msgstr ""
 
-msgid "List section arguments for the 'help' command"
-msgstr ""
-
 msgid "List the names of the functions, but not their definition"
 msgstr ""
 

po/en.po

@@ -2797,9 +2797,6 @@ msgstr ""
 msgid "List embedded files contained in the fish binary"
 msgstr ""
 
-msgid "List section arguments for the 'help' command"
-msgstr ""
-
 msgid "List the names of the functions, but not their definition"
 msgstr ""
 

po/fr.po

@@ -2928,9 +2928,6 @@ msgstr ""
 msgid "List embedded files contained in the fish binary"
 msgstr ""
 
-msgid "List section arguments for the 'help' command"
-msgstr ""
-
 msgid "List the names of the functions, but not their definition"
 msgstr "Lister les noms des fonctions sans leur définition"
 

po/pl.po

@@ -2793,9 +2793,6 @@ msgstr ""
 msgid "List embedded files contained in the fish binary"
 msgstr ""
 
-msgid "List section arguments for the 'help' command"
-msgstr ""
-
 msgid "List the names of the functions, but not their definition"
 msgstr ""
 

po/pt_BR.po

@@ -2798,9 +2798,6 @@ msgstr ""
 msgid "List embedded files contained in the fish binary"
 msgstr ""
 
-msgid "List section arguments for the 'help' command"
-msgstr ""
-
 msgid "List the names of the functions, but not their definition"
 msgstr ""
 

po/sv.po

@@ -2794,9 +2794,6 @@ msgstr ""
 msgid "List embedded files contained in the fish binary"
 msgstr ""
 
-msgid "List section arguments for the 'help' command"
-msgstr ""
-
 msgid "List the names of the functions, but not their definition"
 msgstr ""
 

po/zh_CN.po

@@ -2826,9 +2826,6 @@ msgstr "如果光标下的记号是目录，则列出其内容；否则列出当
 msgid "List embedded files contained in the fish binary"
 msgstr "列出 fish 二进制文件包含的嵌入文件"
 
-msgid "List section arguments for the 'help' command"
-msgstr "列出传给 'help' 命令的段落名称参数"
-
 msgid "List the names of the functions, but not their definition"
 msgstr "列出函数的名称，但不列出其定义"
 

po/zh_TW.po

@@ -2801,9 +2801,6 @@ msgstr "若游標所在的詞元是目錄，則列出其內容，否則列出目
 msgid "List embedded files contained in the fish binary"
 msgstr "列出 fish 二進位檔中嵌入的檔案"
 
-msgid "List section arguments for the 'help' command"
-msgstr "列出傳給「help」命令的段落名稱引數"
-
 msgid "List the names of the functions, but not their definition"
 msgstr "列出函式名稱，不包括其定義"
 

share/completions/help.fish

@@ -1,6 +1,7 @@
 complete -c help -n __fish_is_first_arg -x -a '(
     {
-        status help-sections | string replace -r "^index(#|\$)" introduction\$1
+        __fish_data_with_file help_sections (command -v cat) |
+            string replace -r "^index(#|\$)" introduction\$1
         printf cmds/%s\n ! . : \[ \{
     } |
         while read -l item

share/completions/status.fish

@@ -25,7 +25,6 @@ set -l __fish_status_all_commands \
     job-control \
     line-number \
     list-files \
-    help-sections \
     print-stack-trace \
     stack-trace \
     terminal \
@@ -67,7 +66,6 @@ complete -f -c status -n "__fish_seen_subcommand_from test-feature" -a '(status
 complete -f -c status -n "not __fish_seen_subcommand_from $__fish_status_all_commands" -a fish-path -d "Print the path to the current instance of fish"
 complete -f -c status -n "not __fish_seen_subcommand_from $__fish_status_all_commands" -a get-file -d "Print an embedded file from the fish binary"
 complete -f -c status -n "not __fish_seen_subcommand_from $__fish_status_all_commands" -a list-files -d "List embedded files contained in the fish binary"
-complete -f -c status -n "not __fish_seen_subcommand_from $__fish_status_all_commands" -a help-sections -d "List section arguments for the 'help' command"
 complete -f -c status -n "not __fish_seen_subcommand_from $__fish_status_all_commands" -a fish-path -d "Print the path to the current instance of fish"
 complete -f -c status -n "not __fish_seen_subcommand_from $__fish_status_all_commands" -a terminal -d "Print name and version of the terminal fish is running in"
 complete -f -c status -n "not __fish_seen_subcommand_from $__fish_status_all_commands" -a terminal-os -d "Print the operating system the terminal is running on"

share/functions/help.fish

@@ -140,7 +140,7 @@ chromium-browser
     switch "$fish_help_item"
         case ''
             set fish_help_page index.html
-        case (status help-sections | string replace -r "^index(#|\$)" introduction\$1)
+        case (__fish_data_with_file help_sections (command -v cat) | string replace -r "^index(#|\$)" introduction\$1)
             set fish_help_page (
                 printf %s $fish_help_item |
                     string replace -r '^introduction(#|$)' 'index$1' |

share/help_sections

@@ -0,0 +1,334 @@
+cmds/_
+cmds/abbr
+cmds/alias
+cmds/and
+cmds/argparse
+cmds/begin
+cmds/bg
+cmds/bind
+cmds/block
+cmds/break
+cmds/breakpoint
+cmds/builtin
+cmds/case
+cmds/cd
+cmds/cdh
+cmds/command
+cmds/commandline
+cmds/complete
+cmds/contains
+cmds/continue
+cmds/count
+cmds/dirh
+cmds/dirs
+cmds/disown
+cmds/echo
+cmds/else
+cmds/emit
+cmds/end
+cmds/eval
+cmds/exec
+cmds/exit
+cmds/export
+cmds/false
+cmds/fg
+cmds/fish
+cmds/fish_add_path
+cmds/fish_breakpoint_prompt
+cmds/fish_clipboard_copy
+cmds/fish_clipboard_paste
+cmds/fish_command_not_found
+cmds/fish_config
+cmds/fish_default_key_bindings
+cmds/fish_delta
+cmds/fish_git_prompt
+cmds/fish_greeting
+cmds/fish_hg_prompt
+cmds/fish_indent
+cmds/fish_is_root_user
+cmds/fish_key_reader
+cmds/fish_mode_prompt
+cmds/fish_opt
+cmds/fish_prompt
+cmds/fish_right_prompt
+cmds/fish_should_add_to_history
+cmds/fish_status_to_signal
+cmds/fish_svn_prompt
+cmds/fish_tab_title
+cmds/fish_title
+cmds/fish_title.inc
+cmds/fish_update_completions
+cmds/fish_vcs_prompt
+cmds/fish_vi_key_bindings
+cmds/for
+cmds/funced
+cmds/funcsave
+cmds/function
+cmds/functions
+cmds/help
+cmds/history
+cmds/if
+cmds/isatty
+cmds/jobs
+cmds/math
+cmds/nextd
+cmds/not
+cmds/open
+cmds/or
+cmds/path
+cmds/popd
+cmds/prevd
+cmds/printf
+cmds/prompt_hostname
+cmds/prompt_login
+cmds/prompt_pwd
+cmds/psub
+cmds/pushd
+cmds/pwd
+cmds/random
+cmds/read
+cmds/realpath
+cmds/return
+cmds/set
+cmds/set_color
+cmds/source
+cmds/status
+cmds/string
+cmds/string-collect
+cmds/string-escape
+cmds/string-join
+cmds/string-join0
+cmds/string-length
+cmds/string-lower
+cmds/string-match
+cmds/string-pad
+cmds/string-repeat
+cmds/string-replace
+cmds/string-shorten
+cmds/string-split
+cmds/string-split0
+cmds/string-sub
+cmds/string-trim
+cmds/string-unescape
+cmds/string-upper
+cmds/suspend
+cmds/switch
+cmds/test
+cmds/time
+cmds/trap
+cmds/true
+cmds/type
+cmds/ulimit
+cmds/umask
+cmds/vared
+cmds/wait
+cmds/while
+commands
+commands#helper-commands
+commands#helper-functions
+commands#keywords
+commands#known-functions
+commands#the-full-list
+commands#tools
+completions
+completions#useful-functions-for-writing-completions
+completions#where-to-put-completions
+contributing
+contributing#adding-translations-for-a-new-language
+contributing#code-style
+contributing#configuring-your-editor-for-fish-scripts
+contributing#contributing-completions
+contributing#contributing-documentation
+contributing#contributing-translations
+contributing#editing-po-files
+contributing#fish-script-style-guide
+contributing#github
+contributing#guidelines
+contributing#local-testing
+contributing#mailing-list
+contributing#minimum-supported-rust-version-msrv-policy
+contributing#modifications-to-strings-in-source-files
+contributing#modifying-existing-translations
+contributing#setting-code-up-for-translations
+contributing#testing
+contributing#updating-dependencies
+contributing#versioning
+design
+design#configurability-is-the-root-of-all-evil
+design#the-law-of-discoverability
+design#the-law-of-orthogonality
+design#the-law-of-responsiveness
+design#the-law-of-user-focus
+faq
+faq#fish-does-not-work-in-a-specific-terminal
+faq#how-do-i-change-the-greeting-message
+faq#how-do-i-check-whether-a-variable-is-defined
+faq#how-do-i-check-whether-a-variable-is-not-empty
+faq#how-do-i-customize-my-syntax-highlighting-colors
+faq#how-do-i-get-the-exit-status-of-a-command
+faq#how-do-i-run-a-command-every-login-what-s-fish-s-equivalent-to-bashrc-or-profile
+faq#how-do-i-run-a-command-from-history
+faq#how-do-i-run-a-subcommand-the-backtick-doesn-t-work
+faq#how-do-i-set-my-prompt
+faq#how-do-i-set-or-clear-an-environment-variable
+faq#i-m-getting-weird-graphical-glitches-a-staircase-effect-ghost-characters-cursor-in-the-wrong-position
+faq#my-command-pkg-config-gives-its-output-as-a-single-long-string
+faq#my-command-prints-no-matches-for-wildcard-but-works-in-bash
+faq#uninstalling-fish
+faq#what-is-the-equivalent-to-this-thing-from-bash-or-other-shells
+faq#why-does-my-prompt-show-a-i
+faq#why-doesn-t-history-substitution-etc-work
+faq#why-doesn-t-set-ux-exported-universal-variables-seem-to-work
+faq#why-won-t-ssh-scp-rsync-connect-properly-when-fish-is-my-login-shell
+fish_for_bash_users
+fish_for_bash_users#arithmetic-expansion
+fish_for_bash_users#blocks-and-loops
+fish_for_bash_users#builtins-and-other-commands
+fish_for_bash_users#command-substitutions
+fish_for_bash_users#heredocs
+fish_for_bash_users#other-facilities
+fish_for_bash_users#process-substitution
+fish_for_bash_users#prompts
+fish_for_bash_users#quoting
+fish_for_bash_users#special-variables
+fish_for_bash_users#string-manipulation
+fish_for_bash_users#subshells
+fish_for_bash_users#test-test
+fish_for_bash_users#variables
+fish_for_bash_users#wildcards-globs
+index
+index#configuration
+index#default-shell
+index#examples
+index#installation
+index#other-help-pages
+index#resources
+index#setup
+index#shebang-line
+index#starting-and-exiting
+index#uninstalling
+index#where-to-go
+interactive
+interactive#abbreviations
+interactive#autosuggestions
+interactive#command-line-editor
+interactive#command-mode
+interactive#configurable-greeting
+interactive#copy-and-paste-kill-ring
+interactive#custom-bindings
+interactive#directory-stack
+interactive#emacs-mode-commands
+interactive#help
+interactive#insert-mode
+interactive#key-sequences
+interactive#multiline-editing
+interactive#navigating-directories
+interactive#pager-color-variables
+interactive#private-mode
+interactive#programmable-prompt
+interactive#programmable-title
+interactive#searchable-command-history
+interactive#shared-bindings
+interactive#syntax-highlighting
+interactive#syntax-highlighting-variables
+interactive#tab-completion
+interactive#vi-mode-commands
+interactive#visual-mode
+language
+language#argument-handling
+language#autoloading-functions
+language#brace-expansion
+language#builtin-commands
+language#combiners-and-or
+language#combining-different-expansions
+language#combining-lists
+language#combining-pipes-and-redirections
+language#command-lookup
+language#command-substitution
+language#comments
+language#conditions
+language#configuration-files
+language#debugging-fish-scripts
+language#defining-aliases
+language#dereferencing-variables
+language#escaping-characters
+language#event-handlers
+language#exporting-variables
+language#functions
+language#future-feature-flags
+language#home-directory-expansion
+language#input-output-redirection
+language#job-control
+language#lists
+language#locale-variables
+language#loops-and-blocks
+language#overriding-variables-for-a-single-command
+language#parameter-expansion
+language#path-variables
+language#piping
+language#profiling-fish-scripts
+language#querying-for-user-input
+language#quotes
+language#quoting-variables
+language#shell-variable-and-function-names
+language#shell-variables
+language#slices
+language#special-variables
+language#syntax-overview
+language#table-of-operators
+language#terminology
+language#the-if-statement
+language#the-status-variable
+language#the-switch-statement
+language#universal-variables
+language#variable-expansion
+language#variable-scope
+language#variables-as-command
+language#wildcards-globbing
+license
+license#gnu-library-general-public-license
+license#license-for-fish
+license#license-for-the-python-docs-theme
+license#mit-license
+prompt
+prompt#adding-color
+prompt#formatting
+prompt#our-first-prompt
+prompt#save-the-prompt
+prompt#shortening-the-working-directory
+prompt#status
+prompt#transient-prompt
+prompt#where-to-go-from-here
+relnotes
+terminal-compatibility
+terminal-compatibility#dcs-commands-and-gnu-screen
+terminal-compatibility#optional-commands
+terminal-compatibility#required-commands
+terminal-compatibility#unicode-codepoints
+tutorial
+tutorial#autoloading-functions
+tutorial#autosuggestions
+tutorial#combiners-and-or-not
+tutorial#command-substitutions
+tutorial#conditionals-if-else-switch
+tutorial#exit-status
+tutorial#exports-shell-variables
+tutorial#functions
+tutorial#getting-help
+tutorial#getting-started
+tutorial#learning-fish
+tutorial#lists
+tutorial#loops
+tutorial#path
+tutorial#pipes-and-redirections
+tutorial#prompt
+tutorial#ready-for-more
+tutorial#running-commands
+tutorial#separating-commands-semicolon
+tutorial#startup-where-s-bashrc
+tutorial#syntax-highlighting
+tutorial#tab-completions
+tutorial#universal-variables
+tutorial#variables
+tutorial#why-fish
+tutorial#wildcards

src/builtins/status.rs

@@ -65,7 +65,6 @@ enum StatusCmd {
     STATUS_BUILDINFO,
     STATUS_GET_FILE,
     STATUS_LIST_FILES,
-    STATUS_HELP_SECTIONS,
     STATUS_TERMINAL,
     STATUS_TERMINAL_OS,
     STATUS_TEST_TERMINAL_FEATURE,
@@ -90,7 +89,6 @@ enum StatusCmd {
     (STATUS_FUNCTION, "function"),
     (STATUS_GET_FILE, "get-file"),
     (STATUS_LIST_FILES, "list-files"),
-    (STATUS_HELP_SECTIONS, "help-sections"),
     (STATUS_IS_BLOCK, "is-block"),
     (STATUS_IS_BREAKPOINT, "is-breakpoint"),
     (STATUS_IS_COMMAND_SUB, "is-command-substitution"),
@@ -734,12 +732,6 @@ pub fn status(parser: &Parser, streams: &mut IoStreams, args: &mut [&wstr]) -> B
                     };
                     streams.out.appendln(result);
                 }
-                STATUS_HELP_SECTIONS => {
-                    streams
-                        .out
-                        .append_narrow(fish_build_man_pages::HELP_SECTIONS);
-                    return Ok(SUCCESS);
-                }
                 STATUS_TERMINAL => {
                     let xtversion = xtversion().unwrap_or_default();
                     streams.out.appendln(xtversion);

tests/checks/help-completions.fish

@@ -2,7 +2,7 @@
 # REQUIRES: command -v sphinx-build
 # REQUIRES: command -v diff
 
-status help-sections | grep -v ^cmds/ >expected
+__fish_data_with_file help_sections (command -v cat) | grep -v ^cmds/ >expected
 
 __fish_data_with_file completions/help.fish cat |
     awk '

tests/checks/sphinx-html.fish

@@ -1,7 +1,8 @@
 #RUN: fish_indent=%fish_indent %fish %s
 #REQUIRES: command -v sphinx-build
 
-set -l build_script (status dirname)/../test_functions/sphinx-shared.sh
+set -l workspace_root (status dirname)/../..
+set -l build_script $workspace_root/tests/test_functions/sphinx-shared.sh
 # sphinx-build needs fish_indent in $PATH
 set -lxp PATH (path dirname $fish_indent)
 $build_script html

tests/checks/sphinx-man.fish

@@ -1,5 +1,7 @@
 #RUN: %fish %s
 #REQUIRES: command -v sphinx-build
 
-set -l build_script (status dirname)/../test_functions/sphinx-shared.sh
-$build_script man
+set -l workspace_root (status dirname)/../..
+set -l build_script $workspace_root/tests/test_functions/sphinx-shared.sh
+$build_script man -D fish_help_sections_output=$PWD/help_sections
+diff -u $workspace_root/share/help_sections $PWD/help_sections

tests/test_functions/sphinx-shared.sh

@@ -12,6 +12,7 @@ trap cleanup EXIT INT TERM HUP
 
 workspace_root=$(dirname "$0")/../..
 builder=$1
+shift
 docsrc=$workspace_root/doc_src
 tmp_dir=$(mktemp -d)
 doctree=$tmp_dir/doctree
@@ -24,5 +25,6 @@ sphinx-build \
     -b "$builder" \
     -c "$docsrc" \
     -d "$doctree" \
+    "$@" \
     "$docsrc" \
     "$output_dir"