README.org - improve the overview / getting started

With this, the start of the README.org should address the need for a getting started guide.

#39

Author: JohnC32

README.org

@@ -14,25 +14,51 @@
 
 2. *Code navigation and more*
 
-   - [[https://github.com/mathworks/MATLAB-language-server][MATLAB Language Server]], matlabls, for code navigation, code completion, go to definition, find
-     references, and more. See [[file:doc/matlab-language-server-lsp-mode.org][doc/matlab-language-server-lsp-mode.org]].
+   - The [[https://github.com/mathworks/MATLAB-language-server][MATLAB Language Server]], matlabls, for code navigation, code completion, go to definition,
+     find references, and more. matlabls is a separate special MATLAB process that Emacs
+     communicates with. For example, when you ask Emacs to jump to the definition of a function via
+     =M-.= or =M-x xref-find-definitions=, Emacs will ask the matlabls process where the function is
+     located and use it's response to jump to the definition.
+
+     #+begin_example
+       +-----------+            +------------+
+       |           |            |            |
+       |   Emacs   |<==========>|  matlabls  |
+       |           |            |            |
+       +-----------+            +------------+
+     #+end_example
+
+     You need to install and setup the MATLAB Language Server to use it.
+     See [[file:doc/matlab-language-server-lsp-mode.org][doc/matlab-language-server-lsp-mode.org]].
 
    - Imenu support for quickly jumping to function declarations in the current ~*.m~ file.
      See [[file:doc/matlab-imenu.org][doc/matlab-imenu.org]].
 
-3. *M-x matlab-shell* for running and debugging MATLAB within Emacs (Unix-only).
+3. *M-x matlab-shell* for running and debugging MATLAB within Emacs (Unix only).
 
    - MATLAB command window errors are hyper-linked and files open in Emacs
    - Debugging support is available from the MATLAB menu.
    - matlab-shell uses company-mode for completions.
-   - You can use Emacs TRAMP and =M-x matlab-shell= to run remote MATLAB within your local Emacs
-     session, see [[file:doc/remote-matlab-shell.org][doc/remote-matlab-shell.org]].
 
-4. *M-x matlab-netshell* for running MATLAB code on Microsoft Windows within Emacs using an attached
-   MATLAB.
+   See [[file:doc/matlab-shell-for-unix.org][doc/matlab-shell-for-unix.org]]
+
+4. *M-x matlab-shell* to run remote Unix MATLAB within your local Emacs session.
 
    #+begin_example
+     +----------------+                 +-----------------+
+     | Local Computer |                 | Remote Computer |
+     |                |<===============>|                 |
+     |     Emacs      |      ssh        |      MATLAB     |
+     +----------------+                 +-----------------+
+   #+end_example
 
+   You use Emacs on your local computer to edit files on the remote computer, run and debug remote
+   MATLAB in a matlab-shell in your local Emacs.  See [[file:doc/remote-matlab-shell.org][doc/remote-matlab-shell.org]].
+
+5. *M-x matlab-netshell* for running MATLAB code on Microsoft Windows within Emacs using an attached
+   MATLAB.
+
+   #+begin_example
     +--------------- Emacs ----------------+         +------------  MATLAB  ------------+
     |                                      |         |                                  |
     | (1) M-x matlab-netshell-server-start |         | (2) connect to Emacs             |
@@ -41,17 +67,16 @@
     |     "MATLAB -> Code Sections" menu   |         | >>                               |
     |     or the key bindings              |         |                                  |
     +--------------------------------------+         +----------------------------------+
-
    #+end_example
-   
-5. *Code sections* support for MATLAB script files. See [[file:doc/matlab-code-sections.org][doc/matlab-code-sections.org]].
+
+6. *Code sections* support for MATLAB script files. See [[file:doc/matlab-code-sections.org][doc/matlab-code-sections.org]].
 
    - After visiting a MATLAB script, you have a *"MATLAB -> Code Sections"* menu and key bindings
      which lets you navigate, run, and move code sections.
 
    - Try out code sections using: [[file:examples/matlab-sections/tryout_matlabsection.m][./examples/matlab-sections/tryout_matlabsection.m]].
 
-6. *Creation of scientific papers, theses, and documents* using MATLAB and [[http://orgmode.org]].
+7. *Creation of scientific papers, theses, and documents* using MATLAB and [[http://orgmode.org]].
 
    - Org enables [[https://en.wikipedia.org/wiki/Literate_programming][literate programming]] which directly supports reproducible research by allowing
      scientists and engineers to write code along with detailed explanations in natural language.
@@ -66,7 +91,7 @@
    - See [[file:examples/matlab-and-org-mode][./examples/matlab-and-org-mode/]] to get started. This directory contains a [[file:examples/matlab-and-org-mode/matlab-and-org-mode.pdf][PDF]] generated from
      [[file:examples/matlab-and-org-mode/matlab-and-org-mode.org][./examples/matlab-and-org-mode/matlab-and-org-mode.org]].
 
-7. *tlc-mode* for editing ~*.tlc~ files. The Target Language Compiler (TLC) is part of Simulink®
+8. *tlc-mode* for editing ~*.tlc~ files. The Target Language Compiler (TLC) is part of Simulink®
    Coder™.
 
 * Installation

doc/matlab-shell-for-unix.org

@@ -5,7 +5,7 @@
 
 # Copyright 2025 Free Software Foundation, Inc.
 
-* MATLAB inside of Emacs on Unix (Linux or Mac)
+* Running MATLAB inside of Emacs on Unix (Linux or Mac)
 
 In Emacs,
 
@@ -19,3 +19,10 @@ matlab-shell to use a specific version of MATLAB run
 
 In the =*MATAB*= matlab-shell buffer, you can run MATLAB commands, debug MATLAB =*.m= files, and
 more. See the MATLAB menu for capabilities.
+
+At the MATLAB prompt, ">>", you can TAB complete commands.  matlab-shell uses company-mode for
+completions. For example:
+
+ : >> plot(a, b, 'Line<TAB>
+
+will complete =Line= to =LineWidth=.

doc/remote-matlab-shell.org

@@ -7,7 +7,7 @@
 
 * Remote M-x matlab-shell
 
-You can use Emacs TRAMP to run matlab-shell on a remote system.
+You can use Emacs [[https://www.gnu.org/software/tramp/][TRAMP]] to run matlab-shell on a remote system.
 
 1. First verify you can connect to the remote system in a terminal