Fix shell-commands.rst

core/installation/shell-commands.rst

@@ -28,22 +28,22 @@ If you have :ref:`pioide` already installed, you do not need to install
 Unix and Unix-like
 ~~~~~~~~~~~~~~~~~~
 
-In Unix and Unix-like systems, there are multiple ways to achieve this.
-
 Method 1
 ''''''''
 
-You can export the PlatformIO executables' directory to the PATH environmental
-variable. This method will allow you to execute ``platformio`` commands from
-any terminal emulator as long as you're logged in as the user PlatformIO is
-installed and configured for.
+In Unix and Unix-like systems, you can create symbolic links (symlinks) 
+in your ``$HOME/.local/bin/`` directory to the necessary PlatformIO executables.
+This will allow you to execute ``platformio`` commands from any terminal emulator 
+as long as you're logged in as the user PlatformIO is installed and configured for.
 
-If you use Bash as your default shell, you can do it by editing either
-``~/.profile`` or ``~/.bash_profile`` and adding the following line:
+First, if it's not already the case, you should export your ``$HOME/.local/bin/``
+directory to the PATH environmental variable. If you use Bash as your default shell, 
+you can do it by editing either ``~/.profile`` or ``~/.bash_profile`` and adding the
+following line:
 
 .. code-block:: shell
 
-    export PATH=$PATH:$HOME/.platformio/penv/bin
+    export PATH=$PATH:$HOME/.local/bin
 
 If you use Zsh, you can either edit ``~/.zprofile`` and add the code above, or
 for supporting both, Bash and Zsh, you can first edit ``~/.profile`` and add
@@ -53,21 +53,32 @@ the code above, then edit ``~/.zprofile`` and add the following line:
 
     emulate sh -c '. ~/.profile'
 
-After everything's done, just restart your session (log out and log back in) and you're good to go.
-
 If you don't know the difference between the two, check out `this page <https://serverfault.com/questions/261802/what-are-the-functional-differences-between-profile-bash-profile-and-bashrc>`_.
 
+Now that is done, or if ``$HOME/.local/bin/`` was already exported to your PATH environmental
+variable, you can create the symlinks by opening your system terminal app and paste these
+commands.
+
+.. code-block:: shell
+
+    ln -s ~/.platformio/penv/bin/platformio ~/.local/bin/platformio
+    ln -s ~/.platformio/penv/bin/pio ~/.local/bin/pio
+    ln -s ~/.platformio/penv/bin/piodebuggdb ~/.local/bin/piodebuggdb
+
+After everything's done, just restart your session (log out and log back in) and you're good to go.
+
 Method 2
 ''''''''
 
 You can create system-wide symlinks. This method is not recommended if you have
 multiple users on your computer because the symlinks will be broken for other users
 and they will get errors while executing PlatformIO commands. If that's not a problem,
-open your system terminal app and paste these commands
-(**MAY require** administrator access ``sudo``):
+open your system terminal app and paste these commands.
+(**PROBABLY requires** administrator access ``sudo``):
 
 .. code-block:: shell
 
+    mkdir -p /usr/local/bin
     ln -s ~/.platformio/penv/bin/platformio /usr/local/bin/platformio
     ln -s ~/.platformio/penv/bin/pio /usr/local/bin/pio
     ln -s ~/.platformio/penv/bin/piodebuggdb /usr/local/bin/piodebuggdb
@@ -81,4 +92,4 @@ Please read one of these instructions `How do I set or change the PATH system va
 
 You need to edit the system environment variable called ``Path`` and append
 ``C:\Users\UserName\.platformio\penv\Scripts;`` path in the beginning of a
-list (please replace ``UserName`` with your account name).
+list (please replace ``UserName`` with your account name).