Browse Source

goals: G-045 record define_docs end-state decision (indented-plus-normalized)

User decision 2026-07-12: when the constructed-definition normalization
mechanism lands, define_docs converts from its interim left-margin
authoring to indented-plus-normalized authoring, remaining the
acceptance criterion's consumer proof as written. Left-margin authoring
via -unindentedfields stays a supported style proven by the rendering
tests, but is not the preferred style for define_docs itself.

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
master
Julian Noble 5 days ago
parent
commit
590b09d38c
  1. 18
      goals/G-045-punkargs-authoring-ergonomics.md

18
goals/G-045-punkargs-authoring-ergonomics.md

@ -127,19 +127,21 @@ punk::imap4's {\Deleted}/{$MDNSent} choice values) have them stated, not just te
block's +12 continuation leak and the topic Help first-line +4 are both gone;
'i help' renders flush end-to-end. punk::ns suite 53/53; make.tcl modules
clean.
- Planning note: the constructed-def normalization increment's consumer proof
was to be define_docs "dropping manual pre-normalization". define_docs now
uses the documented -unindentedfields idiom (left-margin authoring), not a
hack - when normalization lands, either define_docs converts to
indented-plus-normalized authoring (likely nicer in a builder proc) or
ensemble_subcommands_definition serves as the proof; decide and record then.
- Decision (user, 2026-07-12): when the constructed-def normalization mechanism
lands, define_docs converts from its interim left-margin authoring to
indented-plus-normalized authoring - it remains the acceptance's consumer
proof as written. Left-margin authoring via -unindentedfields stays a
supported style proven by tests (rendering_unindentedfields_arg_help,
rendering_unindentedfields_cmd_help), but it is not the preferred style for
define_docs itself.
Remaining for acceptance:
- record-continuation mechanism (the -& candidate): collision rules, escape
story, parses identically to backslash-continuation equivalent, documented
- constructed-definition whole-block normalization opt-in, with
rendering_constructed_def_indent_characterization expectations updated and
a constructed-def consumer converted as proof (see increment 2 planning note
on define_docs vs ensemble_subcommands_definition)
::punk::helptopic::define_docs converted from interim left-margin authoring
to indented-plus-normalized as the consumer proof (user decision 2026-07-12,
see increment 2 notes)
- defquoting.test container quoting rules promoted into the punk::args::define
-help documentation

Loading…
Cancel
Save