From c6f50de6530da6a615a1e575acd59f4ab9677e5f Mon Sep 17 00:00:00 2001
From: Steven Lehn <sjlehn@gmail.com>
Date: Thu, 27 Apr 2017 11:22:03 -0500
Subject: [PATCH 1/6] docs: explain why path.posix.normalize does not replace
 windows slashes

Add section to path docs that explains that path.posix.normalize
does not replace Windows slashes with POSIX slashes because POSIX
does not recognize / as a valid path separator.

Fixes: https://github.com/nodejs/node/issues/12298
---
 doc/api/path.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/doc/api/path.md b/doc/api/path.md
index d9452b00dbfd48..159cff5e3a0cfa 100644
--- a/doc/api/path.md
+++ b/doc/api/path.md
@@ -416,6 +416,16 @@ added: v0.11.15
 The `path.posix` property provides access to POSIX specific implementations
 of the `path` methods.
 
+### path.posix.normalize(path)
+The `path.posix.normalize()` method will not attempt to convert / (Windows) to \ (POSIX), as / is not recognized by 
+POSIX as a valid directory separator.  
+
+For example:
+```js
+path.posix.normalize("/some/thing/like/this")
+//Returns '/some/thing/like/this'
+```
+
 ## path.relative(from, to)
 <!-- YAML
 added: v0.5.0

From 91bb7fa7af8b8b6afdab7fe3227a7ff176847d89 Mon Sep 17 00:00:00 2001
From: Steven Lehn <sjlehn@gmail.com>
Date: Thu, 27 Apr 2017 11:29:34 -0500
Subject: [PATCH 2/6] docs: explain why path.posix.normalize does not replace
 windows slashes

Fix formatting (long line)

Fixes: https://github.com/nodejs/node/issues/12298
---
 doc/api/path.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/api/path.md b/doc/api/path.md
index 159cff5e3a0cfa..6b6dcdc98eec9f 100644
--- a/doc/api/path.md
+++ b/doc/api/path.md
@@ -417,8 +417,8 @@ The `path.posix` property provides access to POSIX specific implementations
 of the `path` methods.
 
 ### path.posix.normalize(path)
-The `path.posix.normalize()` method will not attempt to convert / (Windows) to \ (POSIX), as / is not recognized by 
-POSIX as a valid directory separator.  
+The `path.posix.normalize()` method will not attempt to convert / (Windows) to 
+\ (POSIX), as / is not recognized by POSIX as a valid directory separator.  
 
 For example:
 ```js

From cfaeba4424ee543d418b58813fa2b2ee4f1ef964 Mon Sep 17 00:00:00 2001
From: Steven Lehn <sjlehn@gmail.com>
Date: Thu, 27 Apr 2017 11:44:11 -0500
Subject: [PATCH 3/6] docs: explain why path.posix.normalize does not replace
 windows slashes

Move the comment up to the main path.normalize section and fix the
mix-up with / and \

Fixes: https://github.com/nodejs/node/issues/12298
---
 doc/api/path.md | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)

diff --git a/doc/api/path.md b/doc/api/path.md
index 6b6dcdc98eec9f..2b0e28af05ae3d 100644
--- a/doc/api/path.md
+++ b/doc/api/path.md
@@ -330,6 +330,15 @@ For example on POSIX:
 path.normalize('/foo/bar//baz/asdf/quux/..');
 // Returns: '/foo/bar/baz/asdf'
 ```
+*Note*: The `path.posix.normalize()` method will not attempt to convert \ 
+(Windows) to / (POSIX), as \ is not recognized by POSIX as a valid directory 
+separator.  
+
+For example:
+```js
+path.posix.normalize("\\some\\thing\\like\\this")
+//Returns '\some\thing\like\this'
+```
 
 On Windows:
 
@@ -416,16 +425,6 @@ added: v0.11.15
 The `path.posix` property provides access to POSIX specific implementations
 of the `path` methods.
 
-### path.posix.normalize(path)
-The `path.posix.normalize()` method will not attempt to convert / (Windows) to 
-\ (POSIX), as / is not recognized by POSIX as a valid directory separator.  
-
-For example:
-```js
-path.posix.normalize("/some/thing/like/this")
-//Returns '/some/thing/like/this'
-```
-
 ## path.relative(from, to)
 <!-- YAML
 added: v0.5.0

From b4eda57a35df81eb836adc2ce81f988d5bf03577 Mon Sep 17 00:00:00 2001
From: Steven Lehn <sjlehn@gmail.com>
Date: Thu, 27 Apr 2017 11:58:47 -0500
Subject: [PATCH 4/6] docs: explain why path.posix.normalize does not replace
 windows slashes

Couple more formatting changes as requested in review: add backticks
to slashes, and add .. to example path.

Fixes: https://github.com/nodejs/node/issues/12298
---
 doc/api/path.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/doc/api/path.md b/doc/api/path.md
index 2b0e28af05ae3d..8dd89adef64d47 100644
--- a/doc/api/path.md
+++ b/doc/api/path.md
@@ -330,14 +330,14 @@ For example on POSIX:
 path.normalize('/foo/bar//baz/asdf/quux/..');
 // Returns: '/foo/bar/baz/asdf'
 ```
-*Note*: The `path.posix.normalize()` method will not attempt to convert \ 
-(Windows) to / (POSIX), as \ is not recognized by POSIX as a valid directory 
-separator.  
+*Note*: The `path.posix.normalize()` method will not attempt to convert `\ ` 
+(Windows) to `/` (POSIX), as `\ ` is not recognized by POSIX as a valid 
+directory separator.  
 
 For example:
 ```js
-path.posix.normalize("\\some\\thing\\like\\this")
-//Returns '\some\thing\like\this'
+path.posix.normalize("\\..\\some\\thing\\like\\this")
+//Returns '\..\some\thing\like\this'
 ```
 
 On Windows:

From 7dd712f7f175e9ec86117cc23d34731c2a721a44 Mon Sep 17 00:00:00 2001
From: Steven Lehn <sjlehn@gmail.com>
Date: Fri, 28 Apr 2017 11:13:05 -0500
Subject: [PATCH 5/6] docs: explain why path.posix.normalize does not replace
 windows slashes

Reword note to describe what the method does, rather than what it
doesn't do, per PR feedback

Fixes: https://github.com/nodejs/node/issues/12298
---
 doc/api/path.md | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/doc/api/path.md b/doc/api/path.md
index 8dd89adef64d47..65761c2ca52331 100644
--- a/doc/api/path.md
+++ b/doc/api/path.md
@@ -318,8 +318,9 @@ The `path.normalize()` method normalizes the given `path`, resolving `'..'` and
 `'.'` segments.
 
 When multiple, sequential path segment separation characters are found (e.g.
-`/` on POSIX and `\` on Windows), they are replaced by a single instance of the
-platform specific path segment separator. Trailing separators are preserved.
+`/` on POSIX and either `\` or `/` on Windows), they are replaced by a single 
+instance of the platform specific path segment separator. Trailing separators 
+are preserved.
 
 If the `path` is a zero-length string, `'.'` is returned, representing the
 current working directory.
@@ -330,15 +331,6 @@ For example on POSIX:
 path.normalize('/foo/bar//baz/asdf/quux/..');
 // Returns: '/foo/bar/baz/asdf'
 ```
-*Note*: The `path.posix.normalize()` method will not attempt to convert `\ ` 
-(Windows) to `/` (POSIX), as `\ ` is not recognized by POSIX as a valid 
-directory separator.  
-
-For example:
-```js
-path.posix.normalize("\\..\\some\\thing\\like\\this")
-//Returns '\..\some\thing\like\this'
-```
 
 On Windows:
 
@@ -347,6 +339,14 @@ path.normalize('C:\\temp\\\\foo\\bar\\..\\');
 // Returns: 'C:\\temp\\foo\\'
 ```
 
+Since Windows recognizes multiple path separators, both separators will be
+replaced by instances of the Windows preferred separator (`\`):
+
+```js
+path.win32.normalize("C:////temp\\\\/\\/\\\/foo/bar")
+// Returns: 'C:\\temp\\foo\\bar'
+```
+
 A [`TypeError`][] is thrown if `path` is not a string.
 
 ## path.parse(path)

From cb7d451ae9a203089659c140eb309685daf5f9aa Mon Sep 17 00:00:00 2001
From: Steven Lehn <sjlehn@gmail.com>
Date: Fri, 28 Apr 2017 15:33:15 -0500
Subject: [PATCH 6/6] docs: explain why path.posix.normalize does not replace
 windows slashes

Clarify "platform specific separator"

Fixes: https://github.com/nodejs/node/issues/12298
---
 doc/api/path.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/api/path.md b/doc/api/path.md
index 65761c2ca52331..cb0afd9f713658 100644
--- a/doc/api/path.md
+++ b/doc/api/path.md
@@ -319,8 +319,8 @@ The `path.normalize()` method normalizes the given `path`, resolving `'..'` and
 
 When multiple, sequential path segment separation characters are found (e.g.
 `/` on POSIX and either `\` or `/` on Windows), they are replaced by a single 
-instance of the platform specific path segment separator. Trailing separators 
-are preserved.
+instance of the platform specific path segment separator (`/` on POSIX and 
+`\` on Windows). Trailing separators are preserved.
 
 If the `path` is a zero-length string, `'.'` is returned, representing the
 current working directory.