Change implementation of filename cleaning as discussed in
#523

Also add some documentation for what and why this is done.