From 5db8c6b59144af91e72333be461039e066f9b2ae Mon Sep 17 00:00:00 2001
From: undergroundwires <git@undergroundwires.dev>
Date: Thu, 17 Oct 2024 14:42:15 +0200
Subject: [PATCH] Fix HTML semantics in script run instructions

This commit corrects HTML semantic errors in browser instruction dialogs
displayed when a script is downloaded via browser.

Key changes:

- Fix HTML structure by removing `<ul>` and `<ol>` tags from `<p>`
  elements
- Replace `<code>` with `<kbd>` for keyboard inputs

Other supporting changes:

- Improve clarity readability of some instructions
- Add CSS styles for `<kbd>`
---
 .../assets/styles/base/_index.scss            | 14 ++++
 .../BrowserRunInstructions.vue                |  2 +-
 .../Steps/Platforms/LinuxInstructions.vue     | 76 ++++++++++---------
 .../Steps/Platforms/MacOsInstructions.vue     | 46 ++++++++---
 .../Steps/Platforms/WindowsInstructions.vue   | 17 +++--
 5 files changed, 99 insertions(+), 56 deletions(-)

diff --git a/src/presentation/assets/styles/base/_index.scss b/src/presentation/assets/styles/base/_index.scss
index 081a99b63..11313fe28 100644
--- a/src/presentation/assets/styles/base/_index.scss
+++ b/src/presentation/assets/styles/base/_index.scss
@@ -53,3 +53,17 @@ sup {
   vertical-align: super;
   font-size: $font-size-relative-smallest;
 }
+
+kbd {
+  font-family: unset; // Reset the default browser styles
+  background-color: $color-primary-dark;
+  border: 1px solid $color-primary-darker;
+  border-radius: 0.2em;
+  box-shadow: inset 0 1px 0 0 $color-primary-dark, inset 0 -2px 0 0 $color-primary-darker;
+  font-family: $font-family-monospace;
+  font-size: $font-size-relative-smallest;
+  padding: $spacing-relative-x-small $spacing-relative-x-small;
+  text-align: center;
+  user-select: none;
+  white-space: nowrap;
+}
diff --git a/src/presentation/components/Code/CodeButtons/Save/BrowserRunInstructions/BrowserRunInstructions.vue b/src/presentation/components/Code/CodeButtons/Save/BrowserRunInstructions/BrowserRunInstructions.vue
index b6d025a18..1bf8bb819 100644
--- a/src/presentation/components/Code/CodeButtons/Save/BrowserRunInstructions/BrowserRunInstructions.vue
+++ b/src/presentation/components/Code/CodeButtons/Save/BrowserRunInstructions/BrowserRunInstructions.vue
@@ -6,7 +6,7 @@
     <article>
       <h3>1. The Easy Alternative</h3>
       <p>
-        Run your script without any manual steps by
+        Run your script securely without any manual steps by
         <a :href="downloadUrl">downloading desktop version</a> of {{ appName }} on the
         {{ osName }} system you wish to configure, and then click on the Run button. This is
         recommended for most users.
diff --git a/src/presentation/components/Code/CodeButtons/Save/BrowserRunInstructions/Steps/Platforms/LinuxInstructions.vue b/src/presentation/components/Code/CodeButtons/Save/BrowserRunInstructions/Steps/Platforms/LinuxInstructions.vue
index 8523a2ad9..ef19d0ea6 100644
--- a/src/presentation/components/Code/CodeButtons/Save/BrowserRunInstructions/Steps/Platforms/LinuxInstructions.vue
+++ b/src/presentation/components/Code/CodeButtons/Save/BrowserRunInstructions/Steps/Platforms/LinuxInstructions.vue
@@ -16,29 +16,29 @@
       Open terminal.
       <InfoTooltipInline>
         <p>
-          Opening terminal changes based on the distro you run.
+          Opening terminal changes based on the distribution you run.
         </p>
         <p>
           You may search for "Terminal" in your application launcher to find it.
         </p>
         <p>
-          Alternatively use terminal shortcut for your distro if it has one by default:
-          <ul>
-            <li>
-              <code>Ctrl-Alt-T</code>:
-              Ubuntu, CentOS, Linux Mint, Elementary OS, ubermix, Kali…
-            </li>
-            <li>
-              <code>Super-T</code>: Pop!_OS…
-            </li>
-            <li>
-              <code>Alt-T</code>: Parrot OS…
-            </li>
-            <li>
-              <code>Ctrl-Alt-Insert</code>: Bodhi Linux…
-            </li>
-          </ul>
+          Alternatively use terminal shortcut for your distribution if it has one by default:
         </p>
+        <ul>
+          <li>
+            <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>T</kbd>:
+            Ubuntu, CentOS, Linux Mint, Elementary OS, ubermix, Kali…
+          </li>
+          <li>
+            <kbd>Super</kbd> + <kbd>T</kbd>: Pop!_OS…
+          </li>
+          <li>
+            <kbd>Alt</kbd> + <kbd>T</kbd>: Parrot OS…
+          </li>
+          <li>
+            <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Insert</kbd>: Bodhi Linux…
+          </li>
+        </ul>
       </InfoTooltipInline>
     </InstructionStep>
     <InstructionStep>
@@ -50,19 +50,22 @@
           <CopyableCommand>cd ~/Downloads</CopyableCommand>
           <template #info>
             <p>
-              Press on <code>enter/return</code> key after running the command.
+              Press on <kbd>Enter</kbd> or <kbd>Return</kbd> key after running the command.
             </p>
             <p>
-              If the file is not downloaded on Downloads folder,
-              change <code>Downloads</code> to path where the file is downloaded.
+              If you didn't save the file in your <strong>Downloads</strong> folder:
             </p>
+            <ol>
+              <li>Locate where you saved the file.</li>
+              <li>In the command, replace <code>Downloads</code> with the correct folder path.</li>
+            </ol>
             <p>
               This command means:
-              <ul>
-                <li><code>cd</code> will change the current folder.</li>
-                <li><code>~</code> is the user home directory.</li>
-              </ul>
             </p>
+            <ul>
+              <li><code>cd</code> will change the current folder.</li>
+              <li><code>~</code> is the user home directory.</li>
+            </ul>
           </template>
         </InfoTooltipWrapper>
       </p>
@@ -76,21 +79,23 @@
           <CopyableCommand>chmod +x {{ filename }}</CopyableCommand>
           <template #info>
             <p>
-              Press on <code>enter/return</code> key after running the command.
+              Press on <kbd>Enter</kbd> or <kbd>Return</kbd> key after running the command.
             </p>
             <p>
               It will make the file executable.
             </p>
             <p>
-              If you use desktop environment you can alternatively (instead of running the command):
-              <ol>
-                <li>Locate the file using your file manager.</li>
-                <li>Right click on the file, select "Properties".</li>
-                <li>Go to "Permissions" and check "Allow executing file as program".</li>
-              </ol>
+              Alternatively, if you're using a graphical desktop environment, you can do this
+              without the command line:
             </p>
+            <ol>
+              <li>Locate the file using your file manager.</li>
+              <li>Right click on the file, select <strong>Properties</strong>.</li>
+              <li>Go to <strong>Permissions</strong>.</li>
+              <li>Check <strong>Allow executing file as program</strong>.</li>
+            </ol>
             <p>
-              These GUI steps and name of options may change depending on your file manager.'
+              These GUI steps and name of options may change depending on your file manager.
             </p>
           </template>
         </InfoTooltipWrapper>
@@ -110,7 +115,8 @@
             </p>
             <ol>
               <li>Locate the file using your file manager.</li>
-              <li>Right click on the file, select "Run as program".</li>
+              <li>Right click on the file.</li>
+              <li>Select <strong>Run as program</strong> or similar option.</li>
             </ol>
           </template>
         </InfoTooltipWrapper>
@@ -124,10 +130,10 @@
           registered, so keep typing.
         </p>
         <p>
-          Press on <code>enter/return</code> key after typing your password.
+          Press the <kbd>Enter</kbd> or <kbd>Return</kbd> key after typing your password.
         </p>
         <p>
-          Administrator privileges are required to configure OS.
+          Administrator privileges are required for configurations.
         </p>
       </InfoTooltipInline>
     </InstructionStep>
diff --git a/src/presentation/components/Code/CodeButtons/Save/BrowserRunInstructions/Steps/Platforms/MacOsInstructions.vue b/src/presentation/components/Code/CodeButtons/Save/BrowserRunInstructions/Steps/Platforms/MacOsInstructions.vue
index 16f23098d..cda2d77fb 100644
--- a/src/presentation/components/Code/CodeButtons/Save/BrowserRunInstructions/Steps/Platforms/MacOsInstructions.vue
+++ b/src/presentation/components/Code/CodeButtons/Save/BrowserRunInstructions/Steps/Platforms/MacOsInstructions.vue
@@ -13,9 +13,28 @@
       </InfoTooltipInline>
     </InstructionStep>
     <InstructionStep>
-      Open terminal.
+      Open your terminal.
       <InfoTooltipInline>
-        Type Terminal into Spotlight or open it from the Applications -> Utilities folder.
+        <p>There are two easy ways to open the default terminal on your Mac:</p>
+        <ol>
+          <li>
+            Using macOS search (<strong>Spotlight</strong>):
+            <ul>
+              <li>Press <kbd>Cmd</kbd> + <kbd>Space</kbd> to open <strong>Spotlight</strong>.</li>
+              <li>
+                Type <strong>Terminal</strong> and press <kbd>Enter</kbd> or <kbd>Return</kbd>.
+              </li>
+            </ul>
+          </li>
+          <li>
+            Using <strong>Finder</strong>:
+            <ul>
+              <li>Open <strong>Finder</strong>.</li>
+              <li>Go to <strong>Applications</strong> → <strong>Utilities</strong>.</li>
+              <li>Double-click on <strong>Terminal</strong>.</li>
+            </ul>
+          </li>
+        </ol>
       </InfoTooltipInline>
     </InstructionStep>
     <InstructionStep>
@@ -27,19 +46,22 @@
           <CopyableCommand>cd ~/Downloads</CopyableCommand>
           <template #info>
             <p>
-              Press on <code>enter/return</code> key after running the command.
+              Press on <kbd>Enter</kbd> or <kbd>Return</kbd> key after running the command.
             </p>
             <p>
-              If the file is not downloaded on Downloads folder,
-              change <code>Downloads</code> to path where the file is downloaded.
+              If you didn't save the file in your <strong>Downloads</strong> folder:
             </p>
+            <ol>
+              <li>Locate where you saved the file.</li>
+              <li>In the command, replace <code>Downloads</code> with the correct folder path.</li>
+            </ol>
             <p>
               This command means:
-              <ul>
-                <li><code>cd</code> will change the current folder.</li>
-                <li><code>~</code> is the user home directory.</li>
-              </ul>
             </p>
+            <ul>
+              <li><code>cd</code> will change the current folder.</li>
+              <li><code>~</code> is the user home directory.</li>
+            </ul>
           </template>
         </InfoTooltipWrapper>
       </p>
@@ -53,7 +75,7 @@
           <CopyableCommand>chmod +x {{ filename }}</CopyableCommand>
           <template #info>
             <p>
-              Press on <code>enter/return</code> key after running the command.
+              Press on <kbd>Enter</kbd> or <kbd>Return</kbd> key after running the command.
             </p>
             <p>
               It will make the file executable.
@@ -83,10 +105,10 @@
           still registered, so keep typing.
         </p>
         <p>
-          Press on <code>enter/return</code> key after typing your password.
+          Press the <kbd>Enter</kbd> or <kbd>Return</kbd> key after typing your password.
         </p>
         <p>
-          Administrator privileges are required to configure OS.
+          Administrator privileges are required for configurations.
         </p>
       </InfoTooltipInline>
     </InstructionStep>
diff --git a/src/presentation/components/Code/CodeButtons/Save/BrowserRunInstructions/Steps/Platforms/WindowsInstructions.vue b/src/presentation/components/Code/CodeButtons/Save/BrowserRunInstructions/Steps/Platforms/WindowsInstructions.vue
index 037dd1061..e772ca89f 100644
--- a/src/presentation/components/Code/CodeButtons/Save/BrowserRunInstructions/Steps/Platforms/WindowsInstructions.vue
+++ b/src/presentation/components/Code/CodeButtons/Save/BrowserRunInstructions/Steps/Platforms/WindowsInstructions.vue
@@ -36,7 +36,7 @@
       </InfoTooltipInline>
     </InstructionStep>
     <InstructionStep>
-      If your antivirus (e.g., Defender) alerts you, address the warning.
+      If your antivirus (e.g., <strong>Defender</strong>) alerts you, address the warning.
       <InfoTooltipInline>
         <!--
           Tests (15/01/2023):
@@ -52,7 +52,7 @@
           Don't worry; privacy.sexy is secure, transparent, and open-source.
         </p>
         <p>
-          To handle false warnings in Microsoft Defender:
+          To handle false warnings in <strong>Defender</strong>:
         </p>
         <ol>
           <li>
@@ -103,21 +103,22 @@
       </InfoTooltipInline>
     </InstructionStep>
     <InstructionStep>
-      If prompted, confirm SmartScreen warnings.
+      If prompted, confirm <strong>SmartScreen</strong> warnings.
       <InfoTooltipInline>
         <p>
-          Windows SmartScreen might display a cautionary message.
+          <strong>Defender SmartScreen</strong> may display a cautionary message.
         </p>
         <p>
           This happens since privacy.sexy scripts are not recognized
           by Microsoft's certification process.
         </p>
         <p>
-          <ol>
-            <li>Select <strong>More info</strong>.</li>
-            <li>Select <strong>Run anyway</strong>.</li>
-          </ol>
+          If you see the warning, bypass it by following these steps:
         </p>
+        <ol>
+          <li>Select <strong>More info</strong>.</li>
+          <li>Select <strong>Run anyway</strong>.</li>
+        </ol>
       </InfoTooltipInline>
     </InstructionStep>
     <InstructionStep>