From 2a536d4a3fb0eb15dad3b64c7a30079949dfe906 Mon Sep 17 00:00:00 2001 From: Thomas Lindop Date: Sat, 24 May 2025 09:49:31 +0100 Subject: [PATCH] >> move notes from TODO into the man page and "FAQ" --- README.md | 3 ++- iaq.md | 40 ++++++++++++++++++++++++++++++++++++++++ man.md | 26 ++++++++++++++++++++++++++ 3 files changed, 68 insertions(+), 1 deletion(-) create mode 100644 iaq.md diff --git a/README.md b/README.md index 70a71fb..484ea3e 100644 --- a/README.md +++ b/README.md @@ -20,8 +20,9 @@ characters, at least if you don't want to manually write a very complex regular expression every time you encounter this problem. Owl will hunt down any files with these issues and rename them as -appropriate - see `man.md` for usage. +appropriate - see `man.md` for usage and other important information. +See [Infrequently Asked Questions](./iaq.md) for unimportant information. --- diff --git a/iaq.md b/iaq.md new file mode 100644 index 0000000..ea5fcbe --- /dev/null +++ b/iaq.md @@ -0,0 +1,40 @@ +# Infrequently Asked Questions +No one but has asked these questions, but I'm giving answers anyway, mainly +so I don't forget them in future. + +## Why didn't you use Punycode? +[Punycode](https://en.wikipedia.org/wiki/Punycode) is a web standard for +converting general Unicode text into ASCII, for use in domain names, and for +nothing else. As the Wikipedia page says, it maps "München" to "Mnchen-3ya", +which I personally find harder to understand than "M_Ufc_nchen". It also +would add a dash to the end of pure +[ASCII](https://en.wikipedia.org/wiki/ASCII) text, so "London" would become +"London-", and its output does not handle characters that are bad for +shells, like "?". + +## Why didn't you use `base64/32/16`? +These are internet encoding standards used to convert any binary data to +ASCII text, which sounds perfect for the job. However, their outputs are not +human readable, and Owl is designed so that you will at least know roughly +what the file was originally called. +See for examples. + +## Why not just `mmv`? Or `zsh`? +[mmv](https://github.com/rrthomas/mmv) is command line tool to do a kind of +"glob search and replace" with filenames. [zsh](https://zsh.sourceforge.io/) +is a shell, Bash or the PowerShell, but it has a tool to do a similar thing +called `zmv`. These require writing a regular expression of glob pattern to +represent the changes you wish to make, which is fiddly work when what you +want is to exclude potentially thousands of characters, not to mention +potential issues with hidden files (a.k.a. "dot files") and shell globbing. + +### Other alternatives +- : This actually does + pretty much what Owl does, but is more specialised to its author's needs. + +## Tree +This is used for testing. It should be available on any Linux system from +your distribution's repositories. If not, the source code can be downloaded +from the GitLab repository at + or from the home page of the +project at . diff --git a/man.md b/man.md index d9e292e..ba8f15c 100644 --- a/man.md +++ b/man.md @@ -33,3 +33,29 @@ Show version information. ### -h, \-\-help Show a small help message. + + +## Edge Cases & Other Tidbits +## What doesn't FAT allow? +Mainly `*<>\|/:?'` + +### What about whitespace? +Some of these (like tab, line feed, and carriage return) are not valid under +FAT and will be removed. + +If a sequence of invalid characters surrounded by spaces is in one of the +file names, and the `remove` strategy is being used, then you will be left +with multiple whitespace characters in a row. For example, +``` +Really questionable ?? filename +``` +will become +``` +Really questionable filename +``` +with a double space before `filename`. + +### What about invalid UTF-8/UTF-16? +This is removed and replaced with "\_INVALID_". This replacement is done +before anything else. +