20250426_00-rel Pretty complete and usable now.

- Updated docs,
- a shortcut for a macOS "QuickAction"
- Tested on macOS.

Author: unixwzrd

README.md

@@ -1,59 +1,127 @@
 # UnicodeFix
 
-Normalizes Unicode to ASCII equivalents
+Normalizes Unicode to ASCII equivalents.
+
+**I'm getting this out quickly as people need it. Updates will follow to polish this up more soon.**
+
+- [UnicodeFix](#unicodefix)
+  - [Installation](#installation)
+  - [Usage](#usage)
+  - [Shortcut for macOS](#shortcut-for-macos)
+    - [To add the shortcut:](#to-add-the-shortcut)
+  - [What's in This Repo:](#whats-in-this-repo)
+  - [Contributing](#contributing)
+  - [Support This and Other Projects I Have](#support-this-and-other-projects-i-have)
+  - [License](#license)
 
 ## Installation
 
-Clone the repository somewhere on your system. You will need to pop up a terminal window to do this.
+Clone the repository somewhere on your system. You will need to pop open a terminal window to do this.
 
-Then copy and paste the following commands into the command window.
+Then copy and paste the following commands into the terminal:
 
 ```bash
 git clone https://github.com/unixwzrd/UnicodeFix.git
 cd UnicodeFix
 bash setup.sh
 ```
 
-Setup will create a virtual environment to keep your system python clean.
-It will add the items needed to startup the script into your .bashrc
+Setup will create a virtual environment to keep your system Python clean.
+It will also add the items needed to start the script into your `.bashrc`.
 
-Look at the [setup.sh](setup.sh) file to see what it does if you like, it's very simple.
+Look at the [setup.sh](setup.sh) file to see exactly what it does if you like — it's very simple.
 
-The .bashrc items are necessary because I will have a shortcut you may use from the macOS context menu to run the script shortly.
+The `.bashrc` items are necessary because I have a Shortcut you may use from the macOS context menu to run the script directly.
 
 ## Usage
 
 ```bash
 (python-3.10-PA-dev) [unixwzrd@xanax: UnicodeFix]$ python bin/cleanup-text.py --help
-usage: cleanup-text.py [-h] [-o OUTPUT] [infile]
+usage: cleanup-text.py [-h] [infile ...]
 
 Clean Unicode quirks from text.
 
 positional arguments:
-  infile                Input file (or use STDIN)
+  infile                Input file(s)
 
 options:
-  -h, --help            show this help message and exit
-  -o OUTPUT, --output OUTPUT
-                        Output file (default: STDOUT)
+  -h, --help            Show this help message and exit
 
+Example:
 python bin/cleanup-text.py <input_file>
 ```
 
-## What's in this repo:
+The output file will be named the same as the input file, but with a `.clean.txt` extension.
+
+You can select multiple files at once.
+
+## Shortcut for macOS
+
+There is a "Shortcut" file in the `macOS/` directory which may be imported into the Shortcuts app.  
+It will allow the script to be run as a **Quick Action** from the Finder "Right Click" menu.  
+This allows selecting multiple files and scrubbing the Unicode quirks from them in bulk.
+
+### To add the shortcut:
+
+1. Open the "Shortcuts" app.
+
+   ![Shortcuts App Menu](macOS/Screenshot%202025-04-25%20at%2005.50.57.png)
+
+2. Go to `File -> Import...`
+
+   ![Import Shortcut](macOS/Screenshot%202025-04-25%20at%2005.51.54.png)
+
+3. Navigate to the `macOS` directory in this repository and select the `Strip Unicode.shortcut` file.
+
+   ![Select Shortcut File](macOS/Screenshot%202025-04-25%20at%2005.47.51.png)
+
+4. You will need to open the shortcut and change the location path of the `cleanup-text.py` script.
+
+   ![Edit Shortcut Script Path](macOS/Screenshot%202025-04-25%20at%2005.07.47.png)
+
+5. You may have to restart Finder (use `Command+Option+Esc`, select Finder, and click "Relaunch").
+
+6. Once setup, right-click on a file or multiple files in Finder, go to `Quick Actions`, and select `Strip Unicode`.
+
+   This will invoke the script on the selected files and create `.clean.txt` versions.
+
+Strip all the Unicode quirks out of your text files right in the finder using a Quick Action!
+
+If you know a better way for Linux or Windows users, feel free to submit a PR with your improvements.
+
+## What's in This Repo:
+
+- [bin/cleanup-text.py](bin/cleanup-text.py) — The script that cleans up the text.
+- [bin/cleanup-text](bin/cleanup-text) — A symlink without the `.py` extension for prettier usage in scripts.
+- [setup.sh](setup.sh) — A script that sets up the virtual environment.
+- [LICENSE](LICENSE) — The license for the project.
+- [README.md](README.md) — This file.
+- [requirements.txt](requirements.txt) — The dependencies needed to run.
+- [data/](data/) — Sample files full of Unicode issues for testing.
+- [docs/](docs/) — Supporting documentation for the project.
+- [macOS/](macOS/) — The Shortcut file for macOS users.
+
+## Contributing
+
+If you have suggestions, enhancements, or fixes, feel free to open an issue or pull request!  
+Testing and feedback are also very welcome.
+
+## Support This and Other Projects I Have
+
+AI and Unix are my passions — but I need to pay the bills too.
+
+If you find this project useful, please tell others, and consider supporting my work:
+
+- [Patreon](https://www.patreon.com/unixwzrd)
+- [Buy me a Ko-Fi](https://ko-fi.com/unixwzrd)
+- [Buy me a Coffee](https://www.buymeacoffee.com/unixwzrd)
 
-- [bin/cleanup-text.py](bin/cleanup-text.py) - The script that cleans up the text.
-- [setup.sh](setup.sh) - A script that sets up the environment to run the script.
-- [LICENSE](LICENSE) - The license for the project.
-- [README.md](README.md) - This file.
-- [requirements.txt](requirements.txt) - The dependencies for the project.
-- [data/](data/) - A directory with sample files full of unicode to test with.
+Thank you!
 
-## Coming SOon
-- macSO Shortcut
+## License
 
-## License  
-Copyright 2025 [email protected]
+Copyright 2025  
+[[email protected]](mailto:[email protected])
 
 [MIT License](LICENSE)
 

bin/cleanup-text

@@ -0,0 +1 @@
+cleanup-text.py

bin/cleanup-text.py

@@ -1,38 +1,91 @@
-#!/usr/bin/env python3
-#
+#!/usr/bin/env python
+
+"""
+Unicode Text Cleaner
+
+This script normalizes problematic Unicode characters to their ASCII equivalents.
+It handles common issues like fancy quotes, em/en dashes, and zero-width spaces
+that can cause problems in text processing.
+
+The script takes one or more input files and creates cleaned versions with
+".clean.txt" appended to the original filename. It skips duplicate files
+and handles errors gracefully.
+
+Example:
+    $ python cleanup-text.py file1.txt file2.txt
+    [✓] Cleaned: file1.txt → file1.clean.txt
+    [✓] Cleaned: file2.txt → file2.clean.txt
+"""
+
 import argparse
+import os
 import re
-import sys
 
 from unidecode import unidecode
 
 
-def clean_text(text):
+def clean_text(text: str) -> str:
     """
-    Clean Unicode quirks from text.
+    Normalize problematic or invisible Unicode characters to safe ASCII equivalents.
+
+    This function performs two main operations:
+    1. Converts typographic characters (quotes, dashes) to their ASCII equivalents
+    2. Removes zero-width and invisible Unicode characters
+
+    Args:
+        text (str): The input text containing Unicode characters
+
+    Returns:
+        str: The cleaned text with normalized ASCII characters
+
+    Example:
+        >>> clean_text('"Hello" — World')
+        '"Hello" - World'
     """
     replacements = {
-        '\u2018': "'", '\u2019': "'",
-        '\u201C': '"', '\u201D': '"',
-        '\u2013': '-', '\u2014': '-',
+        '\u2018': "'", '\u2019': "'",  # Smart single quotes
+        '\u201C': '"', '\u201D': '"',  # Smart double quotes
+        '\u2013': '-', '\u2014': '-',  # En and em dashes
     }
     for orig, repl in replacements.items():
         text = text.replace(orig, repl)
-    text = re.sub(r'[\u200B\u200C\u200D\uFEFF]', '', text)
-    return unidecode(text)
+    return re.sub(r'[\u200B\u200C\u200D\uFEFF]', '', text)
 
 
 def main():
+    """
+    Main function that handles command-line interface and file processing.
+
+    Parses command line arguments, processes input files, and creates cleaned
+    output files. Handles duplicate files and errors gracefully with informative
+    messages.
+
+    Returns:
+        None
+    """
     parser = argparse.ArgumentParser(description="Clean Unicode quirks from text.")
-    parser.add_argument('infile', nargs='?', type=argparse.FileType('r'), default=sys.stdin,
-                        help='Input file (or use STDIN)')
-    parser.add_argument('-o', '--output', type=argparse.FileType('w'), default=sys.stdout,
-                        help='Output file (default: STDOUT)')
+    parser.add_argument("infile", nargs="+", help="Input file(s)")
     args = parser.parse_args()
 
-    input_text = args.infile.read()
-    cleaned = clean_text(input_text)
-    args.output.write(cleaned)
+    seen = set()
+    for infile in args.infile:
+        if infile in seen:
+            print(f"[!] Skipping duplicate: {infile}")
+            continue
+        seen.add(infile)
+
+        try:
+            with open(infile, "r", encoding="utf-8", errors="replace") as f:
+                raw = f.read()
+            cleaned = clean_text(raw)
+
+            base, _ = os.path.splitext(infile)
+            outfile = base + ".clean.txt"
+            with open(outfile, "w", encoding="utf-8") as f:
+                f.write(cleaned)
+            print(f"[✓] Cleaned: {infile} → {outfile}")
+        except Exception as e:
+            print(f"[✗] Failed to process {infile}: {e}")
 
 
 if __name__ == '__main__':

output-clean.txt renamed to data/unicode-tst.clean.txt

@@ -1 +1 @@
-Unidecode==1.4.0
+unidecode==1.4.0