jedarden/pdftract
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
pdftract/notes/bf-2yhak.md
jedarden dfc94f33d5 chore(bf-2yhak): relocate useful generators to tools/ 
Relocate convert_to_scanned.sh from tests/fixtures/scanned/ to tools/
with comprehensive documentation header. Delete incomplete
regenerate.sh stub from tests/fixtures/grep-corpus/. Create
tools/README.md cataloging all 18 generators with usage examples.

Changes:
- Move: tests/fixtures/scanned/convert_to_scanned.sh → tools/convert_pdf_to_scanned.sh
- Delete: tests/fixtures/grep-corpus/regenerate.sh (incomplete stub)
- Create: tools/README.md (comprehensive generator catalog)
- Enhance: convert_pdf_to_scanned.sh with detailed documentation

Closes bf-2yhak
2026-07-05 20:17:04 -04:00

3.1 KiB
Raw Blame History

bf-2yhak: Relocate Useful Generators to Tools with Documentation

Summary

Successfully relocated useful generators from tests/fixtures/ to tools/ with comprehensive documentation as specified in bead bf-2yhak.

Changes Made

1. Relocated convert_to_scanned.sh to tools/

Source: tests/fixtures/scanned/convert_to_scanned.sh
Destination: tools/convert_pdf_to_scanned.sh

Enhancements:

  • Added comprehensive documentation header following existing tools pattern
  • Documented fixtures generated (invoice, letter, form at 300 DPI)
  • Documented requirements (pdftoppm, ImageMagick, nix-shell)
  • Documented conversion process (backup → PPM → PDF)
  • Renamed to convert_pdf_to_scanned.sh for clarity

2. Deleted incomplete regenerate.sh stub

Removed: tests/fixtures/grep-corpus/regenerate.sh

Reason: Incomplete stub with TODOs as identified in bf-1iefu categorization. This script was marked as RELOCATE but recommended for deletion unless prioritized, since it only contained placeholder structure.

3. Created comprehensive tools/README.md

Content:

  • Categorized documentation for all generators:
    • Python generators (encoding, encrypted, stress, invoice, docs)
    • Rust generators (invoice, encrypted)
    • Shell scripts (convert, count, release notes)
    • Debug tools (fingerprint, diff)
    • Specialized builders (objstm, xref)
  • Usage examples for each generator
  • Requirements and dependencies
  • Development workflow examples
  • Contributing guidelines

Acceptance Criteria Status

✅ All RELOCATE-category generators handled:

  • convert_to_scanned.sh → Relocated to tools/ with documentation
  • regenerate.sh → Deleted (incomplete stub)

✅ Each generator has clear documentation:

  • convert_pdf_to_scanned.sh includes comprehensive header comment
  • All existing generators documented in tools/README.md

✅ tools/README.md created:

  • Complete catalog of all 18 tools/generators
  • Usage examples for each tool
  • Dependency information
  • Development workflow section

✅ Changes committed:

  • Commit: chore(bf-2yhak): relocate useful generators to tools/

Verification

Files Created:

  • tools/convert_pdf_to_scanned.sh (3093 bytes)
  • tools/README.md (6296 bytes)
  • notes/bf-2yhak.md (this verification note)

Files Deleted:

  • tests/fixtures/grep-corpus/regenerate.sh

Files Moved:

  • tests/fixtures/scanned/convert_to_scanned.sh → tools/convert_pdf_to_scanned.sh

Documentation Quality:

  • ✅ Comprehensive header in convert_pdf_to_scanned.sh
  • ✅ Complete tools/README.md with all generators cataloged
  • ✅ Usage examples provided for each tool
  • ✅ Dependencies documented

Committed Work:

  • Single commit covering relocation, deletion, and documentation
  • Follows conventional commit format: chore(bf-2yhak): ...

Notes

  • Followed existing pattern from generate_encoding_fixtures.py for documentation style
  • Maintained executable permissions on shell script
  • tools/README.md serves as central documentation for all 18 tools/generators
  • Contributing guidelines added for future generator additions