docs: rewrite the archive TODO section, pruning superseded notes - #456
Merged
Conversation
Two problems in one section, both mine.
STRUCTURE: my sub-bullets used 4-6 space indents, which prettier reads as
continuation PROSE rather than list items, so ~23 intended bullets were reflowed
into run-on lines ("...split point. - **NEXT SLICE..."). Rewritten with at most
two bullet levels - top level at column 0, children at exactly 2 spaces, long
explanations as continuation paragraphs at 4 - which is a shape prettier keeps.
A mechanical re-split was tried first and DISCARDED: splitting on " - `" cut
sentences in half, because that sequence is also a spaced-hyphen separator in
prose. It scored perfectly on the checks I had written ("0 joined bullets", stable
trunk fmt) while the text had become nonsense - the checks were measuring the
wrong property, so this rewrite was verified by READING it.
CONTENT: pruned what later decisions had superseded, 129 lines out for 95 in:
- the long "member path spelling is TBD / here are the candidate conventions"
debate, now that both flags have shipped - kept as one decision statement;
- the separate "correcting an earlier note" entries about the URI authority rule
and about `/` being lossy - the erroneous claims themselves are gone, so the
corrections have nothing to correct;
- the nine-method "NEXT SLICE, mapped onto the seam" mapping, now that the backend
is built (#455) - replaced by what its tests actually pin;
- duplicate statements of the concatenation / first-separator rules.
Kept whole: the libarchive decision and NOTICE obligations, the ratified
--archive/-z control surface and flavor defaults, dual container identity,
--archive-depth, detection and sniff-gating, read-only member semantics, and the
two genuinely OPEN items (per-format schemes + AUTO separator, phar), each now
naming its task (#177, #176).
Also fixes one more joined bullet outside this section (the span-diagram entry),
same cause. `trunk fmt` is idempotent afterwards and zero joins remain.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two problems in one section, both mine.
Structure. My sub-bullets used 4-6 space indents, which prettier reads as continuation prose rather than list items - so ~23 intended bullets had been reflowed into run-on lines (
...split point. - **NEXT SLICE...). Rewritten with at most two bullet levels: top level at column 0, children at exactly 2 spaces, long explanations as continuation paragraphs at 4. That is a shape prettier preserves.A mechanical re-split was tried first and discarded: splitting on
" -"cut sentences in half, because that sequence is also a spaced-hyphen separator in prose. It scored perfectly against the checks I had written - zero joined bullets, stabletrunk fmt` - while the text had become nonsense. The checks were measuring the wrong property, so this rewrite was verified by reading it.Content. Pruned what later decisions superseded - 129 lines out, 95 in:
/being lossy - the erroneous claims are gone, so their corrections have nothing left to correct;Kept whole: the libarchive decision and NOTICE obligations, the ratified
--archive/-zsurface and flavor defaults, dual container identity,--archive-depth, detection and sniff-gating, read-only member semantics, and the two genuinely OPEN items (per-format schemes +AUTOseparator, phar) - each now naming its task (#177, #176).Also fixes one more joined bullet outside this section (the span-diagram entry), same cause.
Verified: zero joined bullets,
trunk fmtidempotent, hooks clean. Docs only.Not armed - queues behind #450 and #455.