Update browsers.nim, deprecate unimplemented `openDefaultBrowser()` (#23332)

For this
[proc](https://github.com/nim-lang/Nim/blob/773c066634d831a968bb464eab35b25a00026525/lib/pure/browsers.nim#L83)
`proc openDefaultBrowser*() {.since: (1, 1).}`:

though it's documented to open default browser with `about:blank` page,
it behaves differently:

- On Windows, it failed and open no window
- On Linux(Debian with Kde), it opens not default browser but
`Konqueror`

I have paid much effort to implement this variant, but even the
implementation on Windows is considerably complex.

In short, it's not only hard but unworthy to fix this.

Just as Araq
[said](https://github.com/nim-lang/Nim/issues/22250#issuecomment-1631360617),

we shall remove the `proc openDefaultBrowser*() {.since: (1, 1).}`
variant

---------

Co-authored-by: ringabout <43030857+ringabout@users.noreply.github.com>

1 files changed, 25 insertions, 14 deletions

diff --git a/lib/pure/browsers.nim b/lib/pure/browsers.nim
index 5708582e1..59e2078df 100644
--- a/lib/pure/browsers.nim
+++ b/lib/pure/browsers.nim
@@ -12,7 +12,7 @@
 ##
 ## Unstable API.
 
-import std/private/since
+import std/private/since # used by the deprecated `openDefaultBrowser()`
 
 import std/strutils
 
@@ -40,7 +40,7 @@ proc prepare(s: string): string =
   else:
     result = "file://" & absolutePath(s)
 
-proc openDefaultBrowserImplPrep(url: string) =
+proc openDefaultBrowserRaw(url: string) =
   ## note the url argument should be alreadly prepared, i.e. the url is passed "AS IS"
 
   when defined(windows):
@@ -60,9 +60,6 @@ proc openDefaultBrowserImplPrep(url: string) =
       except OSError:
         discard
 
-proc openDefaultBrowserImpl(url: string) =
-  openDefaultBrowserImplPrep(prepare url)
-
 proc openDefaultBrowser*(url: string) =
   ## Opens `url` with the user's default browser. This does not block.
   ## The URL must not be empty string, to open on a blank page see `openDefaultBrowser()`.
@@ -78,16 +75,30 @@ proc openDefaultBrowser*(url: string) =
   ##   block: openDefaultBrowser("https://nim-lang.org")
   ##   ```
   doAssert url.len > 0, "URL must not be empty string"
-  openDefaultBrowserImpl(url)
+  openDefaultBrowserRaw(url)
 
-proc openDefaultBrowser*() {.since: (1, 1).} =
-  ## Opens the user's default browser without any `url` (blank page). This does not block.
-  ## Implements IETF RFC-6694 Section 3, "about:blank" must be reserved for a blank page.
+proc openDefaultBrowser*() {.since: (1, 1), deprecated: 
+  "not implemented, please open with a specific url instead".} =
+  ## Intends to open the user's default browser without any `url` (blank page).
+  ## This does not block.
+  ## Intends to implement IETF RFC-6694 Section 3,
+  ## ("about:blank" is reserved for a blank page).
   ##
-  ## Under Windows, `ShellExecute` is used. Under Mac OS X the `open`
-  ## command is used. Under Unix, it is checked if `xdg-open` exists and
-  ## used if it does. Otherwise the environment variable `BROWSER` is
-  ## used to determine the default browser to use.
+  ## Beware that this intended behavior is **not** implemented and 
+  ## considered not worthy to implement here.
+  ##
+  ## The following describes the behavior of current implementation:
+  ## 
+  ##  - Under Windows, this will only cause a pop-up dialog \
+  ## asking the assocated application with `about` \
+  ## (as Windows simply treats `about:` as a protocol like `http`).
+  ##  - Under Mac OS X the `open "about:blank"` command is used.
+  ##  - Under Unix, it is checked if `xdg-open` exists and used \
+  ## if it does and open the application assocated with `text/html` mime \
+  ## (not `x-scheme-handler/http`, so maybe html-viewer \
+  ## other than your default browser is opened). \
+  ## Otherwise the environment variable `BROWSER` is used \
+  ## to determine the default browser to use.
   ##
   ## This proc doesn't raise an exception on error, beware.
   ##
@@ -98,4 +109,4 @@ proc openDefaultBrowser*() {.since: (1, 1).} =
   ## **See also:**
   ##
   ## * https://tools.ietf.org/html/rfc6694#section-3
-  openDefaultBrowserImplPrep("about:blank")  # See IETF RFC-6694 Section 3.
+  openDefaultBrowserRaw("about:blank")  # See IETF RFC-6694 Section 3.