Repository navigation
docs+refactor: professional-voice + idiomatic cleanup across the site - #39
Merged
Merged
Conversation
…code figures Chapters, part/chapter cards, READMEs, and diagrams: - De-referenced ~500 narrative 'Chapter N'/'chN' cross-references to the concept each names, so chapters read standalone (outline TOC kept). - Voice cleanup across chapters, example READMEs, homepage, and _parts/chapter card blurbs/descriptions: recast em dashes and the ASCII ' -- ' substitute, cut hedges/hype/meta-narration/defect framing, trimmed 'deliberately' to the justified one-per-chapter use, 'capstone' -> 'final project' in prose. - Figures: removed chapter-code shorthand (ChNN/chNN) baked into 30 diagram SVGs (+ their .excalidraw), regenerating the one spec-backed pair and hand- editing the rest; recast the ASCII dash. Real CLI '-- ' separators kept. No code, identifiers, commands, flags, recorded output, or figure numbers changed.
…mment dashes Per-language idiomatic audit of the C++/Go/Rust/Lua/Python examples, behavior preserving and build-verified where the toolchain is present: - Go: signal.NotifyContext, net.JoinHostPort (vet IPv6), fixed an os.Exit that skipped a deferred OTel shutdown (dropped final telemetry batch); go build ./... passes all modules, go vet clean. - Rust: unwrap->expect with invariants, manual loops->iterators, is_some_and; cargo build passes all touched crates. Raw-syscall/unsafe demos left intact. - C++: no idiom violations found (naked new/delete all legitimately scoped). - Python: generate_diagram.py open() -> pathlib context managers; print() kept where it is a CLI's actual output. - Recast em dashes and ASCII ' -- ' in code comments across all five languages (CLI flags, '-- ' separators, decrement operators, and output strings untouched).
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
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.
Full voice + idiomatic cleanup of the Linux systems-programming tutorial (C++/Go/Rust + Lua/Python), run with lgtm-professional-voice and lgtm-idiomatic-review. Two commits:
1. docs: voice + de-reference chapter cross-refs + de-code figures
Chapter N/chNcross-references de-referenced to the concept each names (57 chapters + 56 example READMEs); outline TOC kept._parts/chapter card blurbs +description:meta: em dashes and ASCII--recast, hedges/hype/meta-narration/defect-framing cut,deliberatelytrimmed to justified one-per-chapter,capstone→final projectin prose.ChNN/chNN) removed from 30 diagram SVGs +.excalidraw(one spec regenerated, the rest hand-edited); ASCII dash recast.delve(the Go debugger tool), real CLI--separators in code, reasoneddeliberately, and one quoted program-output em dash.2. refactor(examples): idiomatic fixes (behavior-preserving) + comment-dash recast
signal.NotifyContext,net.JoinHostPort(vet IPv6-clean), and a real bug fix (anos.Exitskipping a deferred OTelshutdown).go build ./...+go vetclean across all modules.unwrap→expectwith invariants, manual loops→iterators;cargo buildpasses all touched crates. Raw-syscall/unsafe demos and lint-bait fixtures left intact.new/deleteall legitimately scoped). Builds: 41/48 pass; the 7 fails are pre-existing env gaps (libseccomp, Boost 1.80, libcurl/Perl not installed) that fail before reaching any edited file.generate_diagram.pyopen()→pathlib;print()kept where it's a CLI's output.--recast across all five languages; flags,--separators, decrement operators, and output strings untouched.Scope: no behavior, identifiers, commands, flags, recorded output, or figure numbers changed. Deck N/A (none). Hub card already clean.
Flagged for a separate follow-up (not in this PR): four example READMEs (
37/38/40/41) are still_templateboilerplate (content gap, not wording).