docs: remove the sales / marketing tone

Author: danielsreichenbach

.github/workflows/cache-cleanup.yml

@@ -0,0 +1,21 @@
+---
+name: Cleanup caches for closed PRs
+
+on:
+  # Run twice every day to remove the cache so that the caches from the closed prs
+  # are removed.
+  schedule:
+    - cron: '0 17 * * *'
+    - cron: '30 18 * * *'
+  workflow_dispatch:
+
+jobs:
+  clear-github-caches:
+    name: Clear all GitHub action caches
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clear all caches
+        run: gh cache delete --succeed-on-no-caches --all --repo wowemulation-dev/warcraft-rs
+        env:
+          # This token requires the "repo" scope.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CHANGELOG.md

@@ -12,8 +12,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **wow-mpq**: Complete archive modification API with `MutableArchive` for adding, removing, and renaming files
 - **wow-mpq**: Automatic listfile and attributes updates during archive modifications
 - **wow-mpq**: Full StormLib bidirectional compatibility - archives created/modified by wow-mpq are readable by StormLib and vice versa
-- **wow-mpq**: Achieved 100% compatibility with all WoW versions (1.12.1 through 5.4.8)
-- **wow-mpq**: Full support for all official World of Warcraft MPQ archives (versions 1.12.1 - 5.4.8)
+- **wow-mpq**: Compatibility with WoW versions 1.12.1 through 5.4.8
+- **wow-mpq**: Support for official World of Warcraft MPQ archives (versions 1.12.1 - 5.4.8)
 - **wow-mpq**: Support for all MPQ format versions (V1, V2, V3 with HET/BET, V4 with advanced HET/BET)
 - **wow-mpq**: Portable WoW data discovery system using environment variables and common paths
 - **wow-mpq**: `test-utils` feature for examples requiring WoW game data
@@ -26,7 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **warcraft-rs CLI**: Added path separator conversion in `mpq extract` subcommand for proper cross-platform file extraction
 - **wow-wdl**: Initial implementation of WDL (World Data Low-resolution) format support
 - **warcraft-rs CLI**: Added `wdl` subcommand with validate, convert, and info commands for WDL file manipulation
-- **wow-wdt**: Complete WDT (World Data Table) format support with 100% parsing success rate across all WoW versions
+- **wow-wdt**: WDT (World Data Table) format support with parsing for WoW versions
 - **warcraft-rs CLI**: Added `wdt` subcommand with info, validate, convert, and tiles commands for WDT file manipulation
 - **wow-adt**: Integrated comprehensive ADT (terrain) file support
 - **wow-adt**: Full parsing support for all ADT chunk types including terrain, textures, water, and object placement
@@ -71,7 +71,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - **wow-mpq**: Attributes files now use StormLib-compatible 149-byte format instead of 24-byte format
-- **Documentation**: Comprehensively updated all documentation to reflect 100% StormLib compatibility
+- **Documentation**: Updated documentation to reflect StormLib compatibility
 - **Documentation**: Added notes about Blizzard archive compatibility and common warnings
 
 ### Removed

README.md

@@ -13,75 +13,75 @@ A collection of crates handling World of Warcraft file formats for WoW 1.12.1,
 
 </div>
 
-`warcraft-rs` is part of a fantastic Rust WoW community. Be sure to check out
-[awesome-wow-rust](https://github.com/arlyon/awesome-wow-rust) for more cool
-projects and a link to official WoW Rust Discord.
+`warcraft-rs` is part of the Rust WoW community. See
+[awesome-wow-rust](https://github.com/arlyon/awesome-wow-rust) for other
+projects and a link to the WoW Rust Discord.
 
 ## Features
 
 ### 📦 Format Support
 
 - **MPQ Archives** - Read, write, modify, rebuild and compare MPQ archive files (v1-v4)
-  - ✅ **Full StormLib Compatibility** - 100% bidirectional compatibility with reference implementation
-  - ✅ **100% WoW Version Support** - Tested with all versions from 1.12.1 through 5.4.8
+  - ✅ **StormLib Compatibility** - Bidirectional compatibility with reference implementation
+  - ✅ **WoW Version Support** - Tested with versions 1.12.1 through 5.4.8
   - ✏️ **Archive Modification** - Add, remove, and rename files with automatic listfile/attributes updates
-  - 🔄 **Archive Rebuilding** - Recreate archives 1:1 with format upgrades and optimization
+  - 🔄 **Archive Rebuilding** - Recreate archives with format upgrades and optimization
   - 🔍 **Archive Comparison** - Compare archives for differences in metadata, files, and content
-  - 🔐 **Digital Signatures** - Generate and verify archive signatures for integrity protection
-  - 🎮 **Official WoW Archive Support** - Handles all Blizzard-specific quirks and format variations
+  - 🔐 **Digital Signatures** - Generate and verify archive signatures
+  - 🎮 **Official WoW Archive Support** - Handles Blizzard-specific quirks and format variations
 - **DBC Database** - Parse client database files
 - **BLP Textures** - Handle texture files
 - **M2 Models** - Work with character and creature models
 - **WMO Objects** - Process world map objects (buildings, structures)
-  - ✅ **Full Format Support** - Parse and write root and group files
-  - ✅ **All WoW Versions** - Supports v17 (Classic) through v27 (The War Within)
+  - ✅ **Format Support** - Parse and write root and group files
+  - ✅ **WoW Versions** - Supports v17 (Classic) through v27 (The War Within)
   - 🔄 **Version Conversion** - Convert between expansions (Classic → Cataclysm, etc.)
   - 🏗️ **Builder API** - Create WMO files programmatically
-  - 🔍 **Comprehensive Validation** - Field-level and structural checks
+  - 🔍 **Validation** - Field-level and structural checks
 - **ADT Terrain** - Parse terrain and map data
 - **WDT Maps** - World map definitions and tile layouts
 - **WDL Maps** - Low-resolution terrain heightmaps
 
 ### 🛠️ Command-Line Tools
 
-Each format comes with its own CLI tool for common operations:
+CLI tools for each format:
 
 ```bash
 # MPQ archive manipulation
 warcraft-rs mpq list archive.mpq
 warcraft-rs mpq extract archive.mpq --output ./extracted
 warcraft-rs mpq create new.mpq --add file1.txt --add file2.dat
 warcraft-rs mpq info archive.mpq
-warcraft-rs mpq tree archive.mpq  # NEW! Visualize archive structure
+warcraft-rs mpq tree archive.mpq  # Visualize archive structure
 
-# Archive rebuild and comparison (NEW!)
+# Archive rebuild and comparison
 warcraft-rs mpq rebuild original.mpq rebuilt.mpq --upgrade-to v4
 warcraft-rs mpq compare original.mpq rebuilt.mpq --content-check
 
 # WDL terrain data manipulation
 warcraft-rs wdl validate terrain.wdl
 warcraft-rs wdl info terrain.wdl
 warcraft-rs wdl convert terrain.wdl terrain_new.wdl --to wotlk
-warcraft-rs wdl tree terrain.wdl  # NEW! Visualize WDL structure
+warcraft-rs wdl tree terrain.wdl  # Visualize WDL structure
 
 # WDT map operations
 warcraft-rs wdt info map.wdt
 warcraft-rs wdt validate map.wdt
 warcraft-rs wdt convert map.wdt map_new.wdt --to wotlk
 warcraft-rs wdt tiles map.wdt
-warcraft-rs wdt tree map.wdt  # NEW! Visualize WDT structure
+warcraft-rs wdt tree map.wdt  # Visualize WDT structure
 
 # ADT terrain operations
 warcraft-rs adt info terrain.adt
 warcraft-rs adt validate terrain.adt --level strict
 warcraft-rs adt convert classic.adt cata.adt --to cataclysm
-warcraft-rs adt tree terrain.adt  # NEW! Visualize ADT structure
+warcraft-rs adt tree terrain.adt  # Visualize ADT structure
 
 # WMO object operations
 warcraft-rs wmo info building.wmo
 warcraft-rs wmo validate building.wmo --warnings
 warcraft-rs wmo convert classic.wmo modern.wmo --to 21
-warcraft-rs wmo tree building.wmo  # NEW! Visualize WMO structure
+warcraft-rs wmo tree building.wmo  # Visualize WMO structure
 warcraft-rs wmo edit building.wmo --set-flag has-fog
 warcraft-rs wmo build new.wmo --from config.yaml
 
@@ -93,7 +93,7 @@ warcraft-rs m2 info model.m2
 
 ### 📚 Library Usage
 
-All formats can also be used as Rust libraries:
+Using formats as Rust libraries:
 
 ```rust
 use wow_mpq::{Archive, ArchiveBuilder, MutableArchive, AddFileOptions};
@@ -126,29 +126,33 @@ println!("ADT version: {:?}", adt.version);
 println!("Terrain chunks: {}", adt.mcnk_chunks().len());
 
 // Validate the ADT file
-adt.validate_with_report(ValidationLevel::Standard)?;
+let report = adt.validate_with_report(ValidationLevel::Standard)?;
+println!("Validation passed with {} warnings", report.warnings.len());
 ```
 
 ```rust
 // WMO object parsing and manipulation
-use wow_wmo::{WmoRoot, WmoGroup, WmoParser, WmoWriter, WmoVersion};
+use wow_wmo::{WmoParser, WmoWriter, WmoVersion, WmoConverter};
 use std::fs;
+use std::io::Cursor;
 
 // Parse WMO root file
 let data = fs::read("building.wmo")?;
-let wmo = WmoParser::parse_root(&data)?;
+let mut cursor = Cursor::new(&data);
+let parser = WmoParser::new();
+let wmo = parser.parse_root(&mut cursor)?;
 println!("WMO version: v{}", wmo.version.to_raw());
 println!("Groups: {}", wmo.groups.len());
 println!("Materials: {}", wmo.materials.len());
 
 // Convert to a different version
-let mut wmo = wmo;
-wmo.convert_to(WmoVersion::Cataclysm)?;
+let converter = WmoConverter::new();
+let converted_wmo = converter.convert(&wmo, WmoVersion::Cataclysm)?;
 
 // Save the converted file
 let writer = WmoWriter::new();
 let mut output = Vec::new();
-writer.write_root(&mut output, &wmo, WmoVersion::Cataclysm)?;
+writer.write_root(&mut output, &converted_wmo, WmoVersion::Cataclysm)?;
 fs::write("building_cata.wmo", output)?;
 ```
 
@@ -195,7 +199,7 @@ warcraft-rs mpq tree patch.mpq --depth 3  # Visualize archive structure
 # Extract files
 warcraft-rs mpq extract patch.mpq --output ./extracted --preserve-paths
 
-# Rebuild and modernize an archive
+# Rebuild an archive
 warcraft-rs mpq rebuild old.mpq modern.mpq --upgrade-to v4 --compression lzma
 
 # Verify the rebuild
@@ -210,25 +214,24 @@ warcraft-rs wmo tree building.wmo --show-refs # See WMO structure with reference
 
 ## Documentation
 
-Comprehensive documentation is available in the `docs/` directory:
+Documentation in the `docs/` directory:
 
 - [Getting Started](docs/getting-started/quick-start.md)
 - [Format Documentation](docs/formats/)
 - [API Reference](docs/api/)
 - [Examples and Guides](docs/guides/)
-  - **[📦 MPQ CLI Usage Guide](docs/guides/mpq-cli-usage.md)** - Complete CLI
-    reference with rebuild and compare examples
+  - **[📦 MPQ CLI Usage Guide](docs/guides/mpq-cli-usage.md)** - CLI
+    reference with examples
   - **[📦 MPQ Archives Guide](docs/guides/mpq-archives.md)** - Programming guide
     with rebuild and comparison APIs
   - **[🔍 StormLib vs wow-mpq](docs/guides/stormlib-differences.md)** - Technical
     comparison with the reference implementation
-  - **[🏰 WMO CLI Usage Guide](docs/guides/wmo-cli-usage.md)** - Complete guide
+  - **[🏰 WMO CLI Usage Guide](docs/guides/wmo-cli-usage.md)** - Guide
     for working with World Map Objects
 
 ## 🤝 Contributing
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for
-details on:
+See the [Contributing Guide](CONTRIBUTING.md) for:
 
 - Setting up your development environment
 - Finding issues to work on
@@ -247,7 +250,7 @@ This project uses GitHub Actions for continuous integration:
 
 ### Contributors
 
-Special thanks to all our [contributors](CONTRIBUTORS.md)!
+Thanks to all [contributors](CONTRIBUTORS.md).
 
 ---
 

docs/guides/mpq-archives.md

@@ -2,32 +2,31 @@
 
 ## Overview
 
-MPQ (Mo'PaQ) archives are Blizzard's proprietary archive format used extensively
-in World of Warcraft to store game assets. This guide covers how to work with
-MPQ archives using `warcraft-rs`, including reading, extracting, and managing
-files within these archives.
+MPQ (Mo'PaQ) archives are Blizzard's archive format used
+in World of Warcraft to store game assets. This guide covers working with
+MPQ archives using `warcraft-rs`.
 
 **Key Features:**
 
-- ✅ **100% StormLib Compatibility** - Full cross-implementation support
-- ✅ **Full Blizzard Archive Support** - Handles all official WoW archives (1.12.1 - 5.4.8)
-- ✅ **Bidirectional Compatibility** - Archives created by either implementation can be read by both
-- ✅ **Automatic Path Conversion** - Forward slashes automatically converted to backslashes
+- ✅ **StormLib Compatibility** - Cross-implementation support
+- ✅ **Blizzard Archive Support** - Handles official WoW archives (1.12.1 - 5.4.8)
+- ✅ **Bidirectional Compatibility** - Archives work with both implementations
+- ✅ **Path Conversion** - Forward slashes converted to backslashes
 
 ## Prerequisites
 
-Before working with MPQ archives, ensure you have:
+Prerequisites:
 
-- Basic understanding of Rust programming
+- Rust programming knowledge
 - `warcraft-rs` installed with the `mpq` feature enabled
 - Access to World of Warcraft MPQ files (from game installation)
-- Understanding of file I/O operations in Rust
+- File I/O knowledge in Rust
 
 ## Understanding MPQ Archives
 
-### What are MPQ Archives?
+### MPQ Archives
 
-MPQ archives are compressed file containers that can store:
+MPQ archives are file containers that store:
 
 - Game textures (BLP files)
 - Models (M2, WMO files)
@@ -40,11 +39,11 @@ MPQ archives are compressed file containers that can store:
 
 - **Compression**: Multiple compression algorithms (PKWARE, zlib, bzip2)
 - **Encryption**: Optional file encryption
-- **Listfiles**: Internal file listings (though not always present)
-- **Patches**: Support for incremental updates
+- **Listfiles**: Internal file listings (not always present)
+- **Patches**: Incremental updates
 - **Multi-locale**: Language-specific file variations
 
-## Step-by-Step Instructions
+## Instructions
 
 ### 1. Opening an MPQ Archive
 
@@ -90,7 +89,7 @@ fn list_archive_contents(archive: &mut Archive) -> Result<(), Box<dyn std::error
         }
         Err(_) => {
             println!("No listfile found in archive");
-            // You'll need to know exact filenames to extract without a listfile
+            // Need exact filenames without a listfile
         }
     }
 
@@ -156,8 +155,8 @@ fn extract_all_files(archive: &mut Archive, output_dir: &str) -> Result<(), Box<
 
 ### 4. Working with Multiple Archives using PatchChain
 
-The `PatchChain` struct provides automatic priority-based file resolution across
-multiple MPQ archives, mimicking how World of Warcraft handles patches.
+The `PatchChain` struct provides priority-based file resolution across
+multiple MPQ archives.
 
 ```rust
 use wow_mpq::{PatchChain, Archive};
@@ -174,21 +173,21 @@ fn work_with_patch_chain() -> Result<(), Box<dyn std::error::Error>> {
     chain.add_archive(PathBuf::from("Data/patch-2.MPQ"), 300)?;    // Patch 2
     chain.add_archive(PathBuf::from("Data/patch-3.MPQ"), 400)?;    // Patch 3 (highest priority)
 
-    // Extract a file - automatically uses the highest priority version
+    // Extract a file - uses the highest priority version
     let filename = "Interface/Icons/INV_Misc_QuestionMark.blp";
     let data = chain.read_file(filename)?;
     println!("Extracted {} ({} bytes)", filename, data.len());
 
-    // Find which archive contains a specific file
+    // Find which archive contains a file
     if let Some(archive_path) = chain.find_file_archive(filename) {
         println!("File found in: {}", archive_path.display());
     }
 
-    // List all unique files across all archives
+    // List unique files across archives
     let all_files = chain.list()?;
     println!("Total unique files: {}", all_files.len());
 
-    // Get information about all archives in the chain
+    // Get information about archives
     let chain_info = chain.get_chain_info();
     for info in &chain_info {
         println!("{} (priority {}): {} files",
@@ -240,7 +239,7 @@ fn work_with_multiple_archives_manual() -> Result<(), Box<dyn std::error::Error>
 use wow_mpq::{ArchiveBuilder, FormatVersion, ListfileOption};
 
 fn create_simple_archive() -> Result<(), Box<dyn std::error::Error>> {
-    // Create a basic archive
+    // Create archive
     ArchiveBuilder::new()
         .add_file("readme.txt", "README.txt")
         .add_file_data(b"Hello World".to_vec(), "hello.txt")
@@ -285,8 +284,8 @@ fn create_advanced_archive() -> Result<(), Box<dyn std::error::Error>> {
 
 ### 6. Rebuilding and Comparing Archives
 
-The `warcraft-rs` CLI provides powerful tools for rebuilding MPQ archives and
-comparing them for differences.
+The `warcraft-rs` CLI provides tools for rebuilding MPQ archives and
+comparing them.
 
 #### Rebuilding Archives
 
@@ -802,8 +801,8 @@ let archive = Archive::open("Data/patch.mpq")?;  // Works despite warning
 ### Understanding Patch Chains
 
 World of Warcraft uses a patch chain system where newer patches override files
-in older archives. The `PatchChain` struct automates this process, ensuring you
-always get the most recent version of a file.
+in older archives. The `PatchChain` struct automates this process, returning
+the highest priority version of a file.
 
 ### Critical Loading Order Rules