>> complete documentation

> reorder list of flags to be consistent

main.go

@@ -345,26 +345,26 @@ func printHelp() {
  (?,\,*,etc.) are removed.
 
  Options:
+   -r,--recurse DIRECTORY
+     Recursively search for files in DIRECTORY with bad characters
    -s,--strategy remove|represent
      What to do with bad characters; either replace with a representation or 
      remove
-   -h,--help
-     Show this message
-   -v,--version
-     Show version
-   -r,--recurse DIRECTORY
-     Recursively search for files in DIRECTORY with bad characters
-   -n,--dry-run
-     Do not rename anything, just print what would be done
-   -t,--truncate LENGTH
-     Truncate all filenames to at most LENGTH bytes
    -e,--valid-set fat|posix|shell
      Select a set of characters to limit filenames to.
    -p,--portable
      Alias for "--valid-set posix"
+   -t,--truncate LENGTH
+     Truncate all filenames to at most LENGTH bytes
    -c,--replace TARGET:REPLACEMENT1,REPLACEMENT2,...
      Replace each instance of TARGET in file names with REPLACEMENT1 the 
      first time they appear, REPLACEMENT2 the second time, and so on
+   -n,--dry-run
+     Do not rename anything, just print what would be done
+   -h,--help
+     Show this message
+   -v,--version
+     Show version
 
  See man page for more details
 `);

man.md

@@ -6,7 +6,7 @@ Owl is a file renaming tool; it removes character from file names which are
 not compatible with `FAT` file systems (typically `FAT32` or `exFAT`).
 
 ```
-owl COMMAND OPTIONS FILE1 FILE2 ...
+owl OPTIONS FILE1 FILE2 ...
 ```
 
 Rename `FILE`s given at the command line such that all `FAT`-incompatible 
@@ -15,7 +15,11 @@ characters are removed. By default it replaces invalid characters with
 flag below.
 
 
-## Options:
+## OPTIONS:
+### -r, \-\-recurse DIRECTORY
+Recursively search DIRECTORY for files/directories to rename. Search 
+includes DIRECTORY itself.
+
 ### -s, \-\-strategy STRATEGY
 Change what happens to invalid characters. Choices are:
 
@@ -24,14 +28,6 @@ Change what happens to invalid characters. Choices are:
 - "represent": replace each character with "\_Unum_", where "num" is the 
   Unicode Code Point of the character.
 
-### -r, \-\-recurse DIRECTORY
-Recursively search DIRECTORY for files/directories to rename. Search 
-includes DIRECTORY itself.
-
-### -n, \-\-dry-run
-Causes Owl to just print a representation of what would be done without 
-actually renaming any files.
-
 ### -e,\-\-valid-set fat|posix|shell
 Select which characters are considered "invalid" or "bad". Options are:
  - fat: Characters which are valid in file names on FAT file systems. This 
@@ -44,6 +40,27 @@ Select which characters are considered "invalid" or "bad". Options are:
 ### -p,\-\-portable
 An alias for "\-\-valid-set posix".
 
+### -t,\-\-truncate LENGTH
+Truncate all given file names to at most `LENGTH` bytes. Note that if you 
+have file names with larger Unicode code points (like CJK characters), you 
+may get unexpected results with this option, though it will not cut the file 
+name part way through a character.
+
+### -c,\-\-replace TARGET:REPLACEMENT1,REPLACEMENT2,...
+Remove every instance of the string `TARGET` in every file name and replace 
+the first instance with `REPLACEMENT1`, the second with `REPLACEMENT2`, and 
+so on. If there are N `REPLACEMENT`'s and more than N instances of `TARGET` 
+in a file name, all instances after the Nth are replaced by the last 
+replacement. Replacements can be empty. See EXAMPLES below for this one.
+
+Remember to quote `TARGET:REPLACEMENT1,...` so that your shell doesn't 
+misinterpret the colon.
+
+### -n, \-\-dry-run
+Causes Owl to just print a representation of what would be done without 
+actually renaming any files. Checks for name collisions with existing files 
+or other renaming operations are still done.
+
 ### -v, \-\-version
 Show version information.
 
@@ -51,7 +68,66 @@ Show version information.
 Show a small help message.
 
 
-## Edge Cases & Other Tidbits
+## EXAMPLES
+Suppose we have a file called
+```
+PodEp 37: Why are there so many spaces in this file name?
+```
+in the current working directory. We will refer to it as FILE Then:
+
+- The command
+  ```
+  owl --replace ' :,-,_' FILE
+  ```
+  will rename FILE to  
+  `PodEp37:-Why_are_there_so_many_spaces_in_this_file_name_U3F_`
+- The command
+  ```
+  owl --truncate 48 --replace ' :,-,_' FILE
+  ```
+  will rename FILE to
+  `PodEp37:-Why_are_there_so_many_spaces_in_this_fi`
+- The command
+  ```
+  owl --portable --strategy remove --truncate 48 FILE
+  ```
+  will rename FILE to
+  `PodEp37:Whyaretheresomanyspacesinthisfilename`
+
+Now suppose we have files "IMPORTANT FILE?" and "Important File".
+- If you run
+  ```
+  owl --strategy remove "IMPORTANT FILE?"
+  ```
+  owl will just return an error, saying that the new name would collide with 
+  "important file".
+- If you run
+  ```
+  owl --strategy remove --valid-set posix "IMPORTANT FILE?" "Important File"
+  ```
+  then owl will will rename one file, but refuse to rename the other, as it 
+  would conflict with the now-renamed first file.
+  Note you can use the `--dry-run` flag to check for collisions like this 
+  before renaming anything.
+
+
+## EDGE CASES & OTHER TIDBITS
+### What order does owl truncate, remove characters, etc.?
+Owl does things in the following order:
+
+1. Remove invalid UTF-8
+2. Replace stuff (see `--replace` flag)
+3. Deal with invalid characters (see `--strategy` flag)
+4. Truncate file name
+
+The order in which you use the flags does not change this.
+
+### What if the new name Owl chooses for a file already exists?
+Owl checks before each renaming operation to see if the new name already 
+exists, and skips that file if it does. The check is also case-insensitive.
+See [EXAMPLES](#examples) for more details.
+
+
 ### What doesn't FAT allow?
 Mainly `*<>\|/:?'`
 
@@ -80,6 +156,26 @@ Owl has only been tested so far on Linux with a UTF-8 locale. UTF-16 support
 on Windows is likely possible, but has not been tested. Please contact me if 
 you would like Windows support (see below).
 
+### What about other restrictions on file names?
+Windows (and by extension FAT file systems, which come from Microsoft) may 
+have other restrictions on file names, like specific disallowed names like 
+"CON" or names which ends with a ".". Owl does not check for such things; 
+you should look for those using a tool like `find`.
+
+For completeness, the disallowed names are
+```
+CON,AUX,COM1,COM2COM3,COM4,LPT1,LPT2,LPT3,PRN,NUL
+```
+
+### What about symbolic links (a.k.a. symlinks)?
+Owl will rename the *link*, but not the file that the link points to, even 
+if the link is broken. If you are having issues with broken symbolic links 
+and are on a POSIX/UNIX-like system, you can use
+```
+find -L DIRECTORY -type l
+```
+to find all broken links in DIRECTORY.
+
 
 ## AUTHORS & COPYRIGHT
 Written by user SixteenThousand of github.com (email