Home / books / building-with-larc / RESTRUCTURING_STATUS

Building with LARC - Restructuring Status

Executive Summary

Goal: Transform "Building with LARC" from a 1,376-page tutorial/reference hybrid into a lean "Programming Perl"-style reference manual of 550-650 pages. Current Progress: ~18% complete (foundation work done) Estimated Final Reduction: 60-65% (from 1,376 pages to 550-650 pages)

Completed Work ✓

Phase 1: Remove Redundant Chapters (COMPLETE)

  • ✅ Deleted chapter-02-philosophy.md (6,533 words) — Covered in Learning LARC Ch 1
  • ✅ Deleted chapter-03-story.md (2,935 words) — Narrative content
  • ✅ Deleted chapter-06-basic-message-flow.md (3,002 words) — Covered in Learning LARC Ch 5
  • ✅ Deleted chapter-07-working-with-components.md (2,980 words) — Covered in Learning LARC Ch 4,7
  • ✅ Renumbered remaining 21 chapters to close gaps
Impact: Removed 15,450 words (15% of total content)

Phase 2: Convert to Reference Style (PARTIAL - 3/16 chapters)

  • ✅ Chapter 1 (Introduction): 305 lines → 143 lines (53% reduction)
- Removed all "what is LARC" tutorial content - Added prominent "Read Learning LARC first" notice - Kept only: book structure, conventions, prerequisites
  • ✅ Chapter 2 (Core Concepts): 1,186 lines → 342 lines (71% reduction)
- Converted from tutorial to quick reference lookup - Kept essential API tables and cross-references - Removed all progressive explanations
  • ✅ Chapter 3 (Getting Started): 1,302 lines → 258 lines (80% reduction)
- Reduced to installation commands and minimal examples - Removed step-by-step tutorials - Cross-referenced Learning LARC Ch 3 Impact: Reduced 2,050 lines across 3 chapters (avg 68% reduction)

Remaining Work ⚠️

Phase 2: Chapters 4-16 (13 chapters) — NOT STARTED

Current: ~35,000 words, ~13,000 lines Target: ~10,000 words, ~4,000 lines (70% reduction) Priority: MEDIUM (smaller page impact than component chapters)

Chapters to convert:

  • [x] Ch 1-3: Foundation (DONE)
  • [ ] Ch 4: State Management (1,120 lines)
  • [ ] Ch 5: Routing (775 lines)
  • [ ] Ch 6: Forms (1,069 lines)
  • [ ] Ch 7: APIs (1,082 lines)
  • [ ] Ch 8: Authentication (1,219 lines)
  • [ ] Ch 9: Realtime (1,333 lines)
  • [ ] Ch 10: File Management (1,600 lines)
  • [ ] Ch 11: Theming (937 lines)
  • [ ] Ch 12: Performance (987 lines)
  • [ ] Ch 13: Testing (1,024 lines)
  • [ ] Ch 14: Debugging (880 lines)
  • [ ] Ch 15: Patterns (974 lines)
  • [ ] Ch 16: Deployment (1,024 lines)
Strategy for each:
  • Remove all "how-to" tutorials → Reference Learning LARC
  • Keep only: Configuration tables, pattern summaries, quick examples
  • Add cross-references to component chapters
  • Target: 300-400 lines per chapter

    • Phase 3: Component Reference Chapters 17-21 — NOT STARTED

    Current: 8,236 lines, 307 code blocks Target: ~3,000 lines, ~100 code blocks (65% reduction) Priority: HIGHEST (biggest contributor to page count)

    | Chapter | Current | Code Blocks | Target Lines | Target Blocks | |---------|---------|-------------|--------------|---------------| | 17: Core Components | 1,912 | 87 | ~600 | ~20 | | 18: Data Components | 1,467 | 46 | ~500 | ~15 | | 19: UI Components | 1,354 | 63 | ~600 | ~20 | | 20: Integration | 2,111 | 66 | ~800 | ~25 | | 21: Utility | 1,392 | 45 | ~500 | ~20 |

    Problem: Each component has 5-10 code examples. Way too many. Solution: Standard format per component: 
    ## Component Name

**Purpose**: One-sentence description
**Import**: `import statement`

### Quick Example
[ONE complete example, 10-20 lines]

### Attributes
| Attribute | Type | Default | Description |
[Table only - NO examples for each attribute]

### Methods
| Method | Parameters | Returns | Description |
[Table only - ONE-LINE usage examples if complex]

### Events  
| Event | Payload | Description |
[Table only]

### Complete Example
[ONE comprehensive real-world example, 30-50 lines]

### See Also
- Cross-references
    Action items:
  • For each component in chapters 17-21:
    • - Remove all "Example:" sections except 2 per component - Convert verbose method documentation to tables - Remove redundant "When to use" discussions - Keep API reference tables
  • Target: 70% reduction in lines, 75% reduction in code blocks

    • Phase 4: Update Build System — NOT STARTED

    • [ ] Update index.md with new chapter structure
    • [ ] Update Makefile/build-book.sh if needed
    • [ ] Rebuild PDF: make pdf
    • [ ] Verify page count: Should be 550-650 pages (down from 1,376)
    • [ ] Update README with new structure

    Backup Location

    All original files backed up to: 

    /Users/cdr/Projects/larc-repos/docs/books/backup/building-with-larc-original-20251226/

    Progress Metrics

    | Metric | Original | Current | Target | Progress | |--------|----------|---------|--------|----------| | Total Chapters | 25 + 7 appendices | 21 + 7 appendices | 21 + 7 | ✅ 100% | | Word Count | 103,583 | ~85,000 (est) | 38,000-40,000 | 🟡 18% | | Page Count | 1,376 | TBD | 550-650 | ⚠️ 0% (needs rebuild) | | Code Blocks | ~615 (ch 21-25 only) | ~607 | ~160 | ⚠️ 1% |

    Next Steps (Priority Order)

    CRITICAL PATH:

  • Streamline Chapters 17-21 (component reference)
    • - Automated script to remove redundant examples - Manual review of API tables - Est. time: 4-6 hours
  • Rebuild PDF and verify page count
    • - Run make pdf - Check if target (550-650 pages) achieved - If not, proceed to step 3
  • Trim Chapters 4-16 (if needed)
    • - Convert to dense reference style - Remove tutorials - Est. time: 4-6 hours

    OPTIONAL:

  • Fine-tune appendices (if still over target)
  • Update cross-references throughout book
  • Generate updated index

    • Automation Scripts

    Script 1: Slim Middle Chapters (4-16)

    /tmp/slim_chapters_4_16.sh
# Converts tutorial chapters to reference style
# Keeps: tables, config, patterns
# Removes: tutorials, verbose explanations

    Script 2: Streamline Component Chapters (17-21)

    /tmp/streamline_components_17_21.py
# For each component:
# - Keep 1 quick example + 1 comprehensive example
# - Remove all other code blocks
# - Convert verbose docs to tables

    Script 3: Rebuild and Verify

    cd /Users/cdr/Projects/larc-repos/docs/books/building-with-larc
make clean
make pdf
pdfinfo output/pdf/building-with-larc.pdf | grep Pages

    Success Criteria

    • [ ] Page count: 550-650 pages (down from 1,376)
    • [ ] Word count: 38,000-40,000 words (down from 103,583)
    • [ ] Code blocks in ch 17-21: ~100 blocks (down from 307)
    • [ ] All chapters converted to reference style
    • [ ] Cross-references updated
    • [ ] PDF builds successfully
    • [ ] Book reads like "Programming Perl", not "Learning Perl"

    Contact & Support

    Questions about this restructuring:

    • See: /Users/cdr/Projects/larc-repos/docs/books/RESTRUCTURING_PLAN.md
    • Compare with: learning-larc book (the tutorial companion)
    Last Updated: 2024-12-26 Status: IN PROGRESS (18% complete)