@@ -140,12 +140,35 @@ know exactly how the file system stores the path. Otherwise if we display
140140it differently, the user may use the displayed result to find the file
141141and may not find it.
142142
143+OS Specific Path Encodings
144+--------------------------
145+
146+In general, the OS does not have to look inside the path components
147+other than the ability to recognize the separator char to parse the
148+path into components and to construct it from components. However, in
149+some cases the OS may may have to look inside the path e.g. "." or ".."
150+special paths on Unix.
151+
152+On Unix a path component is just a blob of bytes. The user can encode
153+and decode this blob of bytes as they desire. All they need to care
154+about is that the path separator byte is respected. However, the the
155+path component blobs may be changed by the underlying filesystem
156+e.g. apple HFS may normalize the path before storing, therefore, the
157+representation may change when it is returned back to the user.
158+
159+On modern Windows systems a path component is UTF16-LE
160+encoded. Theoretically, from the OS perspective, it does not have to
161+look inside the path components other than determining whether a 16-bit
162+unit represents the separator character, therefore, users can use any
163+encoding as long as it encodes to 16-bit multiples and the separator is
164+preserved as equivalent to the UTF16-LE representation.
165+
143166Type Safety Requirements
144167------------------------
145168
146169* Safety against using an absolute path where a relative path is to be
147− used and vice-versa.
148−
170+ used and vice-versa.
171+
149172 * Validations for absolute or relative path when constructing a path.
150173 * We cannot append an absolute path to another path
151174* Safety against using a file name where a directory name is to be used and