Un-deprecate navigator.platform (was: Replace Deprecated_Header in na…

…vigator.platform doc and adjust navigator.userAgentData.platform note wording) (#14452)

* Adjust wording of note about navigator.userAgentData.platform

- Don’t say that navigator.userAgentData.platform is “recommended”; it’s
  sufficient to just point out that it exists as an alternative.
- Since it’s so far only in Blink, say “not yet supported by **most**
  browsers” rather than “not yet supported by some major browsers.

See #14429

* Replace Deprecated_Header in navigator.platform doc

For the navigator.platform article, this change replaces the
Deprecated_Header macro and its boilerplate text with some
more-appropriate alternative pseudo-boilerplate text.

See #14429

* Update files/en-us/web/api/navigator/platform/index.md

Co-authored-by: wbamberg <[email protected]>

* Drop “yet” in text about navigator.userAgentData.platform not being supported/adopted

* Un-deprecate navigator.platform; improve advice and example

Fixes #14429.

For the navigator.platform article, this change does the following:

- Drop the Deprecated_Header macro.
- Add admonishments that navigator.platform should be avoided in favor
  of feature detection.
- Relegate mention of (equally-bad) navigator.userAgentData.platform to
  just being a "See also".
- Add an example of the single known good case where using
  navigator.platform isn’t completely bad.

Related BCD change: mdn/browser-compat-data#15599

Related spec change: whatwg/html#7762

* Refine explanation of matching on navigator.platform value

* Fix markdown formatting of example navigator.platform values

* Grammar fix

* Update files/en-us/web/api/navigator/platform/index.md

Co-authored-by: Jean-Yves Perrier <[email protected]>

Co-authored-by: wbamberg <[email protected]>
Co-authored-by: Jean-Yves Perrier <[email protected]>

files/en-us/web/api/navigator/platform/index.md

@@ -1,5 +1,5 @@
 ---
-title: Navigator.platform
+title: navigator.platform
 slug: Web/API/Navigator/platform
 tags:
   - API
@@ -11,26 +11,29 @@ tags:
   - platform
 browser-compat: api.Navigator.platform
 ---
-{{ APIRef("HTML DOM") }} {{Deprecated_Header}}
+{{ APIRef("HTML DOM") }}
 
-> **Note:** The recommended alternative to this property is {{domxref("NavigatorUAData.platform", "navigator.userAgentData.platform")}}. However, {{domxref("NavigatorUAData.platform", "navigator.userAgentData.platform")}} is not yet supported by some major browsers, and the specification which defines it has not yet been adopted by any standards group (specifically, it is not part of any specification published by the W3C or WHATWG).
+The **`platform`** property read-only property of the {{domxref("Navigator")}} interface returns a string identifying the platform on which the user’s browser is running.
 
-Returns a string representing the platform of the browser.
-The specification allows browsers to always return the empty string, so don't rely on this property to get a reliable answer.
+> **Note:** In general, you should whenever possible avoid writing code that uses methods or properties like this one to try to find out information about the user’s environment, and instead write code that does [feature detection](/en-US/docs/Learn/Tools_and_testing/Cross_browser_testing/Feature_detection).
 
 ## Value
 
-A {{domxref("DOMString")}} identifying the platform on which the browser is running, or an empty string if the browser declines to (or is unable to) identify the platform.
-`platform` is a string that must be an empty string or a string representing the platform on which the browser is executing.
-
-For example: "`MacIntel`", "`Win32`", "`FreeBSD i386`", "`WebTV OS`"
+A string identifying the platform on which the user’s browser is running; for example: `"MacIntel"`, `"Win32"`, `"Linux x86_64"`, `"Linux x86_64"`.
 
 ## Examples
 
+`navigator.platform` should almost always be avoided in favor of [feature detection](/en-US/docs/Learn/Tools_and_testing/Cross_browser_testing/Feature_detection). But there is one case where, among the options you could use, `navigator.platform` may be the least-bad option: When you need to show users advice about whether the modifier key for keyboard shortcuts is the `⌘` command key (found on Apple systems) rather than the `⌃` control key (on non-Apple systems):
+
 ```js
-console.log(navigator.platform);
+let modifierKeyPrefix = "^"; // control key
+if (navigator.platform.indexOf("Mac") === 0 || navigator.platform === "iPhone") {
+    modifierKeyPrefix = "⌘"; // command key
+}
 ```
 
+That is, check if `navigator.platform` starts with `"Mac"` or else is an exact match for `"iPhone"`, and then based on whether either of those is true, choose the modifier key your web application’s UI will advise users to press in keyboard shortcuts.
+
 ## Usage notes
 
 Most browsers, including Chrome, Edge, and Firefox 63 and later, return `"Win32"` even if running on a 64-bit version of Windows.
@@ -43,3 +46,7 @@ Internet Explorer and versions of Firefox prior to version 63 still report `"Win
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- [`navigator.userAgentData.platform`](/en-US/docs/Web/API/NavigatorUAData/platform)