Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

All manuals

ASCII names

Read the full manual →

Documentation · Changelog

Application icon

A small Rust application for cleaning filenames before using a folder on an ASCII-only computer. Run it on your modern computer while the USB drive is plugged in. It changes names in place; file contents are never opened or rewritten.

cargo run --locked -p ascii-names

Drop a folder into the window (or use Choose folder). Preview lists proposed changes without writing anything. Clean names processes all files and subfolders. Stop stops between entries; completed renames remain in place. The window keeps the latest 200 messages. Drop one folder at a time.

The selected folder itself keeps its name, so selecting a drive’s mount point is safe. To clean a folder’s own name too, select its parent. Symlinks and special files are skipped, including links to other folders. Hidden files are included. Nested mounted directories are treated as ordinary directories.

Naming rules

  • Accented Latin letters lose their accents, including decomposed macOS accents: Été.mov → Ete.mov. Ligatures and common letters such as œ, ß, ø, ł become oe, ss, o, l.
  • Common Unicode quotes and dashes become ASCII punctuation. Other characters without a supported equivalent become _. This is not transliteration of every writing system: 日本.txt becomes __.txt.
  • ASCII control characters and <>:"/\|?* become _ for filesystem compatibility. Trailing dots/spaces are removed; empty names become _. Windows reserved names such as CON.txt gain an underscore prefix.
  • Names longer than 220 ASCII bytes are shortened, preserving short extensions.
  • Existing destinations are never overwritten or merged. Collisions receive _1, _2, etc., before a file’s extension: résumé.txt becomes resume_1.txt when resume.txt already exists. Directories get the suffix at the end.

Directories are handled inside out. Filesystem work runs on one worker, with 25 ms between rename attempts (at most about 40 renames per second). There are no parallel scans, content copies, or per-file flushes. Eject the USB drive normally afterward so the operating system finishes any buffered writes.

Keep the selected tree idle while running. Names referenced by playlists, shortcuts, documents or projects are not updated inside those files. Preview first when these references matter. There is no automatic undo. Read/rename errors are reported and processing continues where possible; rerun after resolving the reported cause. A failed directory rename can leave already-cleaned children.

Command line

The same binary supports a folder argument, useful for terminal drag and drop:

cargo run --locked -p ascii-names -- /path/to/folder --dry-run
cargo run --locked -p ascii-names -- /path/to/folder
cargo run --locked -p ascii-names -- /path/to/folder --delay-ms 100

--delay-ms accepts 0–1000; the default is 25. Preview does not sleep. The CLI prints every change and a summary, and exits nonzero on errors. Preview paths show the traversal’s intermediate paths before ancestor folders are renamed; preview is not a saved plan, and cleanup scans again.

Build a standalone desktop binary with cargo build --locked --release -p ascii-names. For a smaller CLI-only build, add --no-default-features. No FFprobe or other external command is required. The desktop uses the same egui dependencies as the other Rust tools. Linux/macOS use an atomic no-replace rename and Windows uses MoveFileExW without replacement. Filesystems that do not support safe no-replace renames produce an error; the tool never falls back to an overwriting rename.

The crate is included in workspace tests, Clippy, Rustdoc and coverage. Regression tests cover collisions, nested directories, previews, cancellation, pacing, symlinks, invalid UTF-8 filenames on Unix, and content preservation.

FreeBSD CI hosts

FreeBSD uses renameat2 with AT_RENAME_NOREPLACE when available. The symbol is resolved at runtime, so older jail userlands (including FreeBSD 12) can still build, launch and preview. Actual cleanup on those systems returns an actionable unsupported-operation error without renaming anything. No overwriting fallback is used. The kernel, jail userland and filesystem must all support the operation. See the FreeBSD API documentation change.

On a FreeBSD jail whose libc lacks renameat2, the rename integration tests verify safe refusal and unchanged sources instead of executing their successful rename assertions; this limitation is printed in CI output. Preview and name conversion tests still run normally. Hosts exposing the API run the full rename tests; unexpected filesystem/permission/kernel errors still fail them. Successful renames and collision protection must also be tested on a supported host (Linux, macOS, Windows, or a FreeBSD installation with the API). Jenkins prints its OS version, and failing tests retain the underlying rename errors and CLI output.

All manuals

Cross builds and portable releases

Run commands from the repository root. The primary release workflow is the rust_realease named bundle described below. The standalone packager remains available for manual/offline packaging until native acceptance tests are complete. Cross needs Docker or Podman; Cross.toml selects Windows GNU x64 and Linux GNU x64 images. Jenkins does not run release builds or publish releases.

cross build --locked -p pptx-reporter --release --target x86_64-pc-windows-gnu
cross build --locked -p pptx-reporter --release --target x86_64-unknown-linux-gnu
python3 scripts/package-portable.py --target x86_64-pc-windows-gnu --fetch-ffprobe
python3 scripts/package-portable.py --target x86_64-unknown-linux-gnu --fetch-ffprobe

The packager reads target/<target>/release/ and produces a Windows ZIP or Linux .tar.gz in dist/, plus a SHA-256 checksum. Each includes GUI and CLI binaries, FFprobe, licenses/provenance and quick-start instructions. Existing archives are protected; use --output DIR for a new test build.

FFprobe

scripts/fetch_ffprobe.py downloads BtbN FFmpeg 9.0 release-branch, non-shared LGPL builds. It verifies GitHub’s archive SHA-256, executable format and x86-64 architecture, then tests ffprobe -version on a matching host. Foreign binaries are inspected without execution. Verified binaries/notices are cached in ignored downloads/ffprobe/; no FFprobe binary is committed.

The default upstream latest tag moves. Pin repeatable builds with --ffprobe-release TAG --ffprobe-sha256 HASH. Provenance records release/asset IDs, download URL and digest. Cached files are checked on reuse, but online metadata verification still requires GitHub access.

For offline packaging or another provider:

python3 scripts/package-portable.py --target x86_64-pc-windows-gnu \
  --ffprobe /path/to/ffprobe.exe --ffprobe-licenses /path/to/notices

Review upstream platform requirements and distribution notices for the selected build. Test Windows launch, drag/drop, file dialogs, scaling, Unicode paths and opening reports on a Windows machine; cross-compilation alone cannot verify them.

Release automation

Root Cargo.toml → workspace.package.version is authoritative. The reporter inherits it; its manifest contains cargo-binstall metadata. rust-release.toml configures targets and the canonical Gitea URL for rust_realease:

rust_realease . --package pptx-reporter --dry-run
rust_realease . --package pptx-reporter --compile-only

Publication needs a clean checkout and a matching explicitly created/pushed version tag. The existing local v0.1.0 marks the original trial, not subsequent changes; do not move it implicitly.

The portable named bundle adds Windows/macOS ZIPs and a Linux .tgz, containing both Cargo binaries, adjacent FFprobe, quick-start instructions and licenses. Canonical cargo-binstall .tgz archives remain unchanged and require external FFprobe. Python 3.11+ is required on the build host only.

The protocol-1 hook scripts/prepare-release.py uses the publisher’s output and cache directories, copies FFprobe/notices and emits a hashed file manifest. It never guesses Cargo output paths or creates archives. The publisher handles archive validation, checksums and upload. See the upstream named-bundle contract.

crates/pptx-reporter/ffprobe-pins.json pins a dated BtbN release, exact non-shared LGPL 9.0 asset name and published SHA-256 digest per Windows/Linux target. Dated assets have versioned names, unlike the downloader’s default latest assets. To update, review the provider release and its notices, then update all three fields together. These dated releases are not marked immutable by GitHub; digest verification fails closed if an asset changes. Pinned cached binaries and notices are rechecked locally before any network access; unpinned downloads still refresh upstream metadata.

rust_realease . --package pptx-reporter --target x86_64-unknown-linux-gnu --compile-only

Dry-run validates static configuration without downloads. Compile-only prepares and packages bundles without a token, tag creation, push or publication. After a successful invocation, read dist/latest-artifacts.json; resolve its manifest and checksums paths relative to dist/. Resolve assets relative to the resulting artifact-manifest.json directory and verify SHA256SUMS. Do not guess build paths.

Before publication, extract both portable trees. On Linux, generate a report using adjacent FFprobe without relying on PATH. On Windows, launch the GUI and generate a report without separately installed FFmpeg or Python. Cross compilation and fixture tests do not replace native acceptance tests. Keep the standalone packager until those checks are complete. Jenkins remains checks/coverage/badges only.

macOS

Release builds include aarch64-apple-darwin (Apple Silicon) and x86_64-apple-darwin (Intel), with macOS 13.0 as the minimum. Choose the portable ZIP for your Mac. It contains pptx-reporter, pptx-reporter-gui, FFprobe, notices and a quick-start guide. Extract the entire archive, then run ./pptx-reporter-gui in Terminal, or:

./pptx-reporter presentation.pptx --report all

Keep FFprobe beside the applications. No separate FFmpeg, Python, PowerPoint or PDF compiler is needed. The smaller canonical cargo-binstall TGZs contain only the reporter applications and still require external FFprobe.

These are separate architecture-specific executables, not universal binaries or Finder .app bundles. They are not Developer ID signed or notarized. If macOS blocks a trusted release, open Terminal in the extracted folder:

xattr -d com.apple.quarantine pptx-reporter pptx-reporter-gui ffprobe
chmod +x pptx-reporter pptx-reporter-gui ffprobe
./pptx-reporter-gui

An attribute-not-found message means that file is already unquarantined. Native startup, file dialogs, drag/drop, report generation and Gatekeeper behavior still require testing on compatible Macs.

Bundled macOS FFprobe

scripts/build_macos_ffprobe.py builds FFprobe from the exact official source archive and SHA-256 pinned per Mac target in ffprobe-pins.json. It uses the same digest-pinned cargo-zigbuild image as the reporter, enables local file probing, and disables network input and external codec-library autodetection. It does not enable GPL or nonfree components. The dependency is a separate LGPL executable with statically linked FFmpeg libraries and only macOS system libraries loaded dynamically.

The source build needs Linux, Python 3.11+, and Podman or Docker (selected via CROSS_CONTAINER_ENGINE, or Podman if available). The image must be available to the engine. Compilation runs with container networking disabled; downloading the pinned source occurs first on the host. First preparation can take several minutes. The cache identity covers the source pin, target, image and recipe; reused payloads have their hashes and Mach-O compatibility checked. A warm cache needs no dependency download.

Each Mac portable ZIP includes the complete FFmpeg source archive, LGPL license, reproduction scripts and BUILDING.txt under LICENSES/ffmpeg/. The dependency validator checks the CPU, macOS minimum and system-only library paths without running foreign binaries. The publisher must include Mach-O support for named bundle executables, in addition to its existing macOS build support.

On the Linux release host, the same publisher routes Apple targets through the digest-pinned cargo-zigbuild image in [build.apple]; Cross remains responsible for Windows/Linux. No host Xcode or Darwin Cross image is used. The image pin, SDK path and deployment minimum are explicit in rust-release.toml. See the upstream automated macOS workflow.

# Validate the complete four-target release configuration.
rust_realease . --package pptx-reporter --dry-run
# Build/package just the two macOS architectures, without publication.
rust_realease . --package pptx-reporter \
  --target aarch64-apple-darwin --target x86_64-apple-darwin --compile-only
# Build/package the complete release, including Windows/Linux portable bundles.
rust_realease . --package pptx-reporter --compile-only

Review SHA256SUMS and archive executable modes, including the bundled FFprobe. The publisher checks Mach-O architecture, the exact macOS deployment minimum and system-only dynamic dependencies. Foreign cargo-binstall checks install files without executing them; macOS runtime validation is explicitly skipped on Linux. Publish the complete configured matrix together so its checksum manifest covers all platforms.

Application artwork

All three Rust apps embed their own PNG window icon and Windows ICO resource, including CLI-only Windows builds. Linux/FreeBSD X11 uses the window icon; Wayland desktops match each app ID to its desktop entry. macOS uses the ICNS resource in an app bundle. A bare Unix executable has no Finder/application-menu icon.

Five coordinated icons were generated with the built-in ImageGen tool. The exact prompts are retained. Each Rust crate keeps its app-icon-source.png, app-icon.png, app-icon.ico and app-icon.icns in assets/. Python artwork lives in tools/assets/exporter/; Companion artwork lives in companion-modules/media-player-classic/companion/assets/. Earlier reporter and converter artwork remains available under its original filenames.

Builds consume committed derivatives and need no image tools. To regenerate the 256px PNG, seven-size ICO (16–256px), and ICNS (128–1024px), install ImageMagick 7 and run python3 scripts/build-icons.py from the repository root.

Desktop launchers

After building or extracting a release, create a launcher pointing to the binary at its permanent location. The helper refuses existing launchers/icons. Linux/BSD launchers reference the original executable and stop working if it moves. macOS bundles copy the binary and adjacent LICENSES directory. Reporter bundles also copy an adjacent FFprobe (requiring its LICENSES directory); otherwise FFprobe must be on PATH. Recreate macOS bundles after updating binaries.

# Linux / FreeBSD: install into your desktop's user application directory.
python3 scripts/create-desktop-launcher.py ascii-names \
  --binary "$PWD/target/release/ascii-names" --output "$HOME/.local/share"

# macOS: create a Finder/Dock launcher (run on the Mac).
python3 scripts/create-desktop-launcher.py ascii-names --platform macos \
  --binary "$PWD/target/release/ascii-names" --output "$HOME/Applications"

The same helper supports pptx-reporter and rundown-converter; pass their -gui executable. Reporter and rundown portable archives include the helper, its supporting module, and the icon formats, so these commands also work from an extracted archive. Respect XDG_DATA_HOME instead of ~/.local/share when customized. Desktop menus may need a refresh. Windows executables have embedded icons; shortcuts inherit those icons.

Python scripts and the Companion module run inside a host application and cannot replace its OS icon. Their PNG/ICO/ICNS files are available for custom shortcuts; the Companion README displays its module icon. Shared libraries, CI scripts, packaging helpers and progress.py are not standalone applications.

Launcher output is described in the desktop launcher contract. Automated checks validate icon containers and launcher output on Linux. Finder, Dock, Windows Explorer/taskbar and individual Wayland desktop behavior still need native visual checks. The macOS launchers are not signed or notarized.

Releases containing both tools

The workspace version applies to both tools. Build the reporter with the root configuration, and the converter with its overlay (which omits FFprobe):

rust_realease . --package pptx-reporter --compile-only
rust_realease . --package rundown-converter --config rust-release-rundown.toml --compile-only

Publish both packages’ canonical and portable archives under the same version tag. Aggregate their checksum lists into one SHA256SUMS; do not replace one package’s checksums with the other’s. Each archive includes both CLI and GUI.

All manuals

Development

Documentation · CI and coverage · Releases

Layout and workflow

DirectoryPurpose
tools/Python prototypes and document utilities
tests/Python regression and CI/packaging tests
crates/<tool>/Rust ports, each with its own source, tests and assets
scripts/Shared CI and release helpers
docs/Tool usage and specialized workflows

Prototype in Python, then add a Rust workspace member when the workflow is stable. Retire the Python implementation once the Rust port is validated. The PPTX reporter is now Rust-only; the document exporter remains Python. The rundown converter is a separate Rust workspace member with CLI and egui interfaces. Its implementation checklist and evaluation corpus track coverage and remaining limitations. Avoid speculative shared crates; extract common code when multiple tools need it.

The root Cargo.toml owns workspace metadata, the shared version and build profiles. Members inherit that metadata. Keep one root Cargo.lock and target/. The reporter is the default member; CI explicitly checks the entire workspace. Use -p pptx-reporter to select it when building from a multi-tool workspace.

Checks

Use a recent stable Rust toolchain. Python tools need 3.9+; CI helpers need 3.11+. Run from the repository root:

cargo fmt --all --check
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
cargo test --locked --workspace --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --all-features --no-deps
python3 -m unittest discover -s tests -v
cargo build --locked --workspace --all-features

Rust regression tests cover archive parsing, trimming, loops, report formats, Ontime, CLI errors and GUI state; both PDF layouts compile with the embedded engine. Probe-process tests use a controlled stub. No external FFmpeg, FFprobe or Typst CLI is required for CI. The application still needs FFprobe at runtime. Python exporter tests mock external document applications. Inspect rendering changes visually as well.

cargo build -p pptx-reporter --no-default-features builds the CLI without the GUI or PDF engine; add --features pdf to restore embedded PDFs.

Keep generated files out of Git. Commit each completed task after checks; do not push without authorization. See CI and coverage and cross builds and packaging.

The converter can run without desktop dependencies using cargo run --locked -p rundown-converter --no-default-features --bin rundown-converter -- --help. Its tests generate synthetic XLSX inputs and never require private source files or network downloads. The existing workspace test, lint, Rustdoc and coverage commands include both tools; reporter release packaging remains separate.

The ASCII filename cleaner is a separate Rust workspace member. Run cargo run --locked -p ascii-names for its drag-and-drop window, or pass a folder for CLI cleanup. It uses the same workspace checks and coverage gates.

All manuals

ASCII Names changelog

All changelogs

Unreleased

v0.7.0 — 2026-11-14

  • Update the shared Rust application version to 0.7.0; see the release notes.

  • Add direct links to the published mdBook manual from the project README, tool guide and documentation indexes.

  • Add an mdBook manual built from the existing guides, with local assets and downloads. Jenkins publishes successful main builds under /mnt/books/manuals/; staging, link validation and scoped publication have regression coverage.

  • Use absolute Gitea main-branch URLs for repository file links in the root README; verify linked files exist.

v0.6.0 — 2026-11-14

  • Synchronize the shared Cargo package version with the v0.6.0 milestone tag; see the release notes.

  • Group the guide and supporting documentation in this tool’s folder; update portal, cross-document and packaging links for the new paths.

  • Add ImageGen application artwork in PNG, Windows ICO and macOS ICNS formats. Embed native icons and support Linux/BSD desktop entries and macOS app launchers; native Windows/macOS visual checks remain required.

2026-11-13

  • 00a43e8: Handle FreeBSD no-overwrite rename capabilities and safe-refusal CI expectations.