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 1 week 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; 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 'i help' renders flush end-to-end. punk::ns suite 53/53; make.tcl modules
clean. clean.
- Planning note: the constructed-def normalization increment's consumer proof - Decision (user, 2026-07-12): when the constructed-def normalization mechanism
was to be define_docs "dropping manual pre-normalization". define_docs now lands, define_docs converts from its interim left-margin authoring to
uses the documented -unindentedfields idiom (left-margin authoring), not a indented-plus-normalized authoring - it remains the acceptance's consumer
hack - when normalization lands, either define_docs converts to proof as written. Left-margin authoring via -unindentedfields stays a
indented-plus-normalized authoring (likely nicer in a builder proc) or supported style proven by tests (rendering_unindentedfields_arg_help,
ensemble_subcommands_definition serves as the proof; decide and record then. rendering_unindentedfields_cmd_help), but it is not the preferred style for
define_docs itself.
Remaining for acceptance: Remaining for acceptance:
- record-continuation mechanism (the -& candidate): collision rules, escape - record-continuation mechanism (the -& candidate): collision rules, escape
story, parses identically to backslash-continuation equivalent, documented story, parses identically to backslash-continuation equivalent, documented
- constructed-definition whole-block normalization opt-in, with - constructed-definition whole-block normalization opt-in, with
rendering_constructed_def_indent_characterization expectations updated and rendering_constructed_def_indent_characterization expectations updated and
a constructed-def consumer converted as proof (see increment 2 planning note ::punk::helptopic::define_docs converted from interim left-margin authoring
on define_docs vs ensemble_subcommands_definition) 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 - defquoting.test container quoting rules promoted into the punk::args::define
-help documentation -help documentation

Loading…
Cancel
Save