Rework README as user-facing, add usage and architecture docs - #16
Merged
Conversation
Slim the README down to what a newcomer needs: install commands, the four CLI one-liners, a minimal library example, the support matrix, and pointers into docs/. Details that served contributors more than users move out. Add docs/USAGE.md, the complete user guide: opening options and what they mean, inspection, extraction, creation, mutation, bootable image configuration (El Torito BIOS/EFI entries, boot info table), hybrid MBR/GPT layouts and when each applies, name handling across Rock Ridge, Joliet, and interchange levels, UDF, a CLI reference, and an honest limitations section (4 GiB write ceiling, UDF read-only, symlinks requiring Rock Ridge, keeping the source reader open). Add docs/ARCHITECTURE.md for contributors: package map, read path, the mutable tree and its two content sources, the Pack layout order and the sizes-before-locations rule, record plans and SUSP continuation budgeting, per-extension internals (Rock Ridge, Joliet, El Torito, hybrid boot, UDF), the eight invariants that keep images valid, the three-layer testing strategy, and a checklist for adding a new on-disk structure. Also add a public AddSymlink API on ISO9660 — symlinks could previously only enter an image through AddLocalDirectory, which made the documented API needlessly asymmetric. Tests that reached into the unexported tree now use it.
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.
Summary
Documentation restructure per the plan: README for newcomers, depth in
docs/.README
Now answers "what is this and how do I use it in 30 seconds": install, four CLI one-liners (extract / build / bootable build / inspect), a minimal library example, the support matrix, and links to the deeper docs. Contributor-oriented content moved out.
docs/USAGE.md — advanced user guide
The complete tour: open options and their effects, inspection, extraction, creation, mutation, El Torito boot configuration (BIOS/EFI, boot info table), hybrid MBR vs GPT layouts and why the two modes exist, name handling (Rock Ridge mangling, Joliet limits, interchange levels 1–3), UDF, full CLI flag reference, and a real limitations section — including operational gotchas like keeping the source reader open across Save.
docs/ARCHITECTURE.md — developer guide
For contributors: package map with dependency direction, the read path, the mutable tree's two content sources (pending vs reader-backed and why that makes modify memory-safe), the Pack layout order, the sizes-before-locations rule, record plans and SUSP continuation budgeting, internals per extension, the eight invariants that keep images valid, the three-layer testing strategy (with the lesson that symmetric bugs pass internal round-trips — only foreign readers catch them), and a step-by-step for adding a new on-disk structure.
One small API addition
ISO9660.AddSymlink(path, target)— symlinks could previously only enter an image viaAddLocalDirectory, which made the documented API asymmetric. Tests that reached into the unexported tree now use the public method.Test plan
go test -count=1 ./...), gofmt/vet clean