rootiest
41e801eab1
--pattern matched the first textual occurrence of the keyword anywhere in the document. Replace with psub to make bat's output seekable, then use --jump-target with the line number resolved by grep against heading lines only (^#+.*keyword), so keyword jumps land on the actual section header rather than an example or body reference.
94 lines
3.2 KiB
Fish
94 lines
3.2 KiB
Fish
# Copyright (C) 2026 Rootiest
|
|
# SPDX-License-Identifier: AGPL-3.0-or-later
|
|
|
|
# SYNOPSIS
|
|
# config_help [section]
|
|
#
|
|
# DESCRIPTION
|
|
# Opens the offline fish shell configuration manual in the best available
|
|
# pager. Falls back through ov -> bat -> man -> less -> cat.
|
|
# If a section keyword is provided, the pager opens at the first heading
|
|
# that matches the keyword (case-insensitive).
|
|
#
|
|
# ARGUMENTS
|
|
# section Optional keyword to jump to a matching section heading
|
|
#
|
|
# RETURNS
|
|
# 0 Manual displayed
|
|
# 1 Documentation file not found
|
|
#
|
|
# EXAMPLE
|
|
# config_help
|
|
# config_help keybindings
|
|
# config_help pkg
|
|
# config_help fish-deps
|
|
function config_help --description 'Open the offline fish shell configuration manual'
|
|
set -l doc_file "$__fish_config_dir/docs/fish-config.md"
|
|
set -l man_file "$__fish_config_dir/docs/fish-config.1"
|
|
|
|
if not test -f "$doc_file"
|
|
set_color red
|
|
echo "error: documentation not found at $doc_file" >&2
|
|
set_color normal
|
|
return 1
|
|
end
|
|
|
|
# ── Resolve section start line ───────────────────────────────
|
|
set -l start_line 1
|
|
if test -n "$argv[1]"
|
|
set -l found (grep -n -im 1 "^#\+.*$argv[1]" "$doc_file" | cut -d: -f1)
|
|
if test -n "$found"
|
|
set start_line $found
|
|
else
|
|
set_color yellow
|
|
echo "note: no section matching '$argv[1]' — opening at top" >&2
|
|
set_color normal
|
|
end
|
|
end
|
|
|
|
# ── Viewer fallback chain ────────────────────────────────────
|
|
# bat colors the output; ov matches headers via an ANSI-aware regex.
|
|
# bat emits: ESC[<color>m# ... so delimiter ^(\x1b\[[0-9;]*m)+# matches
|
|
# any 8/24-bit color sequence before a '#', theme-agnostic.
|
|
# Section nav: Space (next), ^ (previous), Alt+u (section list sidebar).
|
|
# psub creates a seekable temp file so --jump-target works on bat output.
|
|
if type -q ov; and type -q bat
|
|
set -l ov_args \
|
|
--section-delimiter "^(\x1b\[[0-9;]*m)+#" \
|
|
--section-header
|
|
if test $start_line -gt 1
|
|
set -a ov_args --jump-target $start_line
|
|
end
|
|
ov $ov_args (bat --color=always --style=plain --language=markdown "$doc_file" | psub)
|
|
|
|
# ov alone: section navigation on raw Markdown; no code highlighting.
|
|
else if type -q ov
|
|
set -l ov_args \
|
|
--section-delimiter "^#" \
|
|
--section-header
|
|
if test $start_line -gt 1
|
|
set -a ov_args --jump-target $start_line
|
|
end
|
|
ov $ov_args "$doc_file"
|
|
|
|
# bat alone: syntax highlighting with built-in paging; no line jump.
|
|
else if type -q bat
|
|
if test $start_line -gt 1
|
|
set_color brblack
|
|
echo "note: bat pager — use / to search for your section" >&2
|
|
set_color normal
|
|
end
|
|
bat --language=markdown --paging=always "$doc_file"
|
|
|
|
# Pre-compiled man page (generated by CI after merge).
|
|
else if test -f "$man_file"
|
|
man -l "$man_file"
|
|
|
|
else if type -q less
|
|
less +"$start_line" "$doc_file"
|
|
|
|
else
|
|
cat "$doc_file"
|
|
end
|
|
end
|