feat(docs): add CLASSIFICATION function-header field, rename history shadow

Rename the C1 history() shadow to pretty-history so it never collides
with the fish builtin -- every function expecting stock history
semantics (search, --max, merge, ...) would otherwise silently break.
hist.fish, which relied on the shadow's timestamp formatting, now
requests it explicitly via builtin history --show-time.

Add a CLASSIFICATION doc-header label so a function can declare its
interaction with C1-shadowed commands (uses-shadow/bypasses-shadow)
and general hazards (destructive, network, blocking-prompt) for
anyone deciding to disable an opinionated category or call the
function from automation. Wired into the manual/site build pipeline
(manualtools.py, build-manual.py) and the C1 shadow doc gets a new
"For function authors" bypass-mechanism reference table
(command/builtin/__original_help, and which shadows have no real
bypass target at all).

This commit is contained in:

rootiest

2026-09-21 21:26:40 -04:00

parent 392e6593ac

commit aef686af86

5 changed files with 82 additions and 6 deletions

									
										docs/manualtools.py
									
		+1
		
												View File
												
				@@ -64,6 +64,7 @@ SECTIONS = (

				    "CATEGORY",

				    "COMPONENT",

				    "DEPENDENCIES",

				    "CLASSIFICATION",

				    "SYNOPSIS",

				    "DESCRIPTION",

				    "ARGUMENTS",