path-utils: update docs

Author: LiberalArtist

gui-lib/framework/main.rkt

@@ -535,6 +535,57 @@
   @{Opens a dialog that queries the user about exiting.  Returns the user's
     decision.})
 
+ (proc-doc/names
+  path-utils:generate-backup-name
+  (path? . -> . path?)
+  (filename)
+  @{
+ Generates a path for a backup file based on @racket[filename].
+
+ @index{'path-utils:backup-dir}
+ The value of @racket[(preferences:get 'path-utils:backup-dir)]
+ determines the directory of the resulting path.
+ The value of this preference must be either a path
+ satisfying @racket[complete-path?] and @racket[directory-exists?],
+ in which case it is additionally checked to ensure that the
+ directory has not been deleted since the preference was set,
+ or @racket[#f] (the default).
+ When the preference contains a valid path,
+ the resulting path will use that directory;
+ otherwise, and by default, 
+ the result will use the same directory as @racket[filename].
+ 
+ The final element of the resulting path is derived from @racket[filename].
+ When @racket[(preferences:get 'path-utils:backup-dir)] does not specify
+ an extant directory, the final element of @racket[filename] is
+ used directly as the base for the new element.
+ Otherwise, the base is formed by transforming the complete path to @racket[filename]
+ (resolved, if necessary, relative to @racket[(current-directory)])
+ according to the following @deftech{encoding scheme}:
+ @itemlist[#:style 'ordered
+           @item{A @racket[separator-byte] is selected: @litchar{!} by default,
+             but a list of visually-appealing one-byte characters are
+             tried if @litchar{!} occurs in the complete path to
+             @racket[filename].}
+           @item{Every seperator between path elements is replaced with
+             @racket[separator-byte], as are any other occurances of the
+             reserved separator character (@litchar{\} on Windows or
+             @litchar{/} on Unix or Mac OS), e.g. in the name of the root directory.}
+           @item{A single @racket[separator-byte] is added at the beginning
+             so that the seperator can be unambiguously identified.}
+           @item{If the result of the previous step is excessively long, it
+             may be shortened by replacing some bytes in the middle with
+             @racket[(bytes-append separator-byte #"..." separator-byte)]
+             (i.e. @litchar{!...!} with @litchar{!} as the @racket[separator-byte]).}]
+ 
+ In either case, the final path element is formed from the base
+ in a platform-specific manner:
+ @itemlist[
+ @item{On Unix and Mac OS, a @litchar{~} is added to the end.}
+ @item{On Windows, the extension (in the sense of @racket[path-replace-extension])
+   is replaced with @litchar{.bak}.}]
+ })
+ 
  (proc-doc/names
   path-utils:generate-autosave-name
   (-> (or/c #f path-string? path-for-some-system?) path?)
@@ -544,69 +595,39 @@
 
  @index{'path-utils:autosave-dir}
  The value of @racket[(preferences:get 'path-utils:autosave-dir)]
- determines the directory of the resulting path.
- When the preference value is @racket[#f] (the default),
- result will use the same directory as the @racket[filename]
+ determines the directory of the resulting path
+ in much the same way as @racket[path-utils:generate-backup-name]
+ with @racket['path-utils:backup-dir].
+ When the preference value is @racket[#f] (the default) or a
+ directory that no longer exists, the
+ result will use the same directory as @racket[filename]
  (or, when @racket[filename] is @racket[#f], the directory determined by
  @racket[(find-system-path 'doc-dir)]).
- Otherwise, when @racket[(preferences:get 'path-utils:autosave-dir)]
- returns a path satisfying @racket[complete-path?] and
- @racket[directory-exists?], the autosave file will be saved in
- that directory.
- A relative @racket[filename] will be resolved based on
- the value of @racket[(current-directory)].
+ Otherwise, the resulting path will use the directory specified by the preference.
 
  When @racket[filename] is @racket[#f], the final element of the
  resulting path will be an automatically-generated unique name.
+ 
  Otherwise, the final path element will be derived from @racket[filename].
- When @racket[(preferences:get 'path-utils:autosave-dir)] returns
- @racket[#f], the original file name will be used directly as the base;
- otherwise, base will be the complete path to @racket[filename],
- encoded by replacing each seperator (@litchar{\} on Windows or
- @litchar{/} on Unix or Mac OS) with @litchar{!}.
- This base is transformed into the final path element in a
- platform-specific manner:
+ When @racket[(preferences:get 'path-utils:autosave-dir)] does not return
+ an extant directory, the last element of @racket[filename] will be
+ used directly as the base for the new element.
+ When a valid autosave directory is specified, the base will be
+ the complete path to @racket[filename],
+ transformed according to the same @tech{encoding scheme} as
+ with @racket[path-utils:generate-backup-name].
+ In either case, the final path element is formed from the base
+ in a platform-specific manner:
  @itemlist[
  @item{On Unix and Mac OS, a @litchar{#} is added to the start
-   and end of the file’s name, then a number is added after the
+   and end, then a number is added after the
    ending @litchar{#}, and then one more @litchar{#} is appended
    after the number.
    The number is selected to make the autosave filename unique.}
- @item{On Windows, the file’s extension is replaced with a number
-   to make the autosave filename unique.}
+ @item{On Windows, the file’s extension (in the sense of @racket[path-replace-extension])
+   is replaced with a number to make the autosave filename unique.}
  ]})
 
- (proc-doc/names
-  path-utils:generate-backup-name
-  (path? . -> . path?)
-  (filename)
-  @{
- Generates a path for a backup file based on @racket[filename].
-
- @index{'path-utils:backup-dir}
- The value of @racket[(preferences:get 'path-utils:backup-dir)]
- determines the directory of the resulting path in much the same
- way as @racket[path-utils:generate-autosave-name] responds to
- the preference  @racket['path-utils:autosave-dir]:
- when the value is @racket[#f] (the default), the directory of
- @racket[filename] is used, and otherwise the directory from the
- preference is used.
-
- The final element of the resulting path is generated from
- @racket[filename] in a platform-specific manner:
- @itemlist[
- @item{On Unix and Mac OS, a @litchar{~} is added to the end
-   of the file’s name.}
- @item{On Windows, the file’s extension is replaced
-   with @litchar{.bak}.}]
- In either case, when @racket[(preferences:get 'path-utils:backup-dir)]
- returns a non-false value, the result of the above transformation
- is combined with the complete path of @racket[filename],
- encoded by replacing seperators with @litchar{!} as with
- @racket[path-utils:generate-autosave-name], to form the final
- path element.
- })
-
  (parameter-doc
   finder:dialog-parent-parameter
   (parameter/c (or/c false/c (is-a?/c dialog%) (is-a?/c frame%)))