Converts the specified string into another string that may be used as a file or directory name (suitable for any file system) as well as a URL path segment.

In particular, the function works as the following:

  1. In the initial string, all characters other than letters, digits and '-', '~', '(', ')' are replaced with spaces.
  2. The spaces are collapsed (so that any repeating spaces are replaces with only one) and trimmed from the left and right.
  3. All spaces that have been left are replaced with '-' character.
  4. The result string is returned by the function.

Examples:

This function is used in some DocFlex/XML template sets to generate for a given URI the name of a directory in which the documentation files related to that URI are to be stored. For example, for the URI:

http://www.w3.org/2001/XMLSchema
the function will return the string:
"http_www_w3_org_2001_XMLSchema"