branch: externals/matlab-mode
commit b0222ac2c067292b43fba91a60b39a262c6149d3
Author: John Ciolfi <john.ciolfi...@gmail.com>
Commit: John Ciolfi <john.ciolfi...@gmail.com>
Add doc/matlab-netshell-for-windows.org
See: https://github.com/mathworks/Emacs-MATLAB-Mode/issues/36
---
README.org | 28 +++++++--
doc/matlab-netshell-for-windows.org | 112 ++++++++++++++++++++++++++++++++++++
2 files changed, 135 insertions(+), 5 deletions(-)
diff --git a/README.org b/README.org
index f06f88a772..29515aeb72 100644
--- a/README.org
+++ b/README.org
@@ -28,9 +28,27 @@
- 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. *Code sections* support. MATLAB script code files often contain many
commands and lines of text.
- You typically focus your efforts on a single part of your code at a time,
working with the code
- and related text in sections. You demarcate sections using /"%%
description"/ header comments.
+4. *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
|
+ | |<=======>| >> addpath
<matlab-mode>/toolbox |
+ | (3) Visit script *.m files and use | | >> emacsinit
|
+ | "MATLAB -> Code Sections" menu | | >>
|
+ | or the key bindings | |
|
+ +--------------------------------------+
+----------------------------------+
+
+ #+end_example
+
+5. *Code sections* support for MATLAB script files. Script files contain one
or more commands, such
+ as variable assignements, function calls, etc. Script files differ from
declaration files such
+ as those declaring function's or classdef's. You typically focus your
efforts on a single part
+ of your code at a time, working with the code and related text in sections.
You demarcate
+ sections using /"%% description"/ header comments.
- After visiting a MATLAB script, you have the *"MATLAB -> Code Sections"*
menu and key
bindings which lets you can navigate, run, and move code sections.
@@ -41,7 +59,7 @@
super key bindings for code sections. After visiting a file.m, see menu
*"MATLAB -> Code
Sections -> Help"*.
-5. *Creation of scientific papers, theses, and documents* using MATLAB and
[[http://orgmode.org]].
+6. *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.
@@ -56,7 +74,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]].
-6. *tlc-mode* for editing ~*.tlc~ files. The Target Language Compiler (TLC) is
part of Simulink®
+7. *tlc-mode* for editing ~*.tlc~ files. The Target Language Compiler (TLC) is
part of Simulink®
Coder™.
* Installation
diff --git a/doc/matlab-netshell-for-windows.org
b/doc/matlab-netshell-for-windows.org
new file mode 100644
index 0000000000..bc2b209845
--- /dev/null
+++ b/doc/matlab-netshell-for-windows.org
@@ -0,0 +1,112 @@
+# File: matlab-netshell-for-windows.org
+
+#+startup: showall
+#+options: toc:nil
+
+# Copyright 2025 Free Software Foundation, Inc.
+
+* Emacs MATLAB code execution on Microsoft Windows using the Emacs
matlab-netshell package
+
+MATLAB for Microsoft Windows does not have a console mode, which means Emacs
cannot run MATLAB
+inside of it (=M-x matlab-shell= is not available). However, Emacs can
communicate with a running
+MATLAB session using a local TCP connection:
+
+#+begin_example
+
+ +--------------- Emacs ----------------+ +------------ MATLAB
------------+
+ | | |
|
+ | (1) M-x matlab-netshell-server-start | | (2) connect to Emacs
|
+ | |<=======>| >> addpath
<matlab-mode>/toolbox |
+ | (3) Visit script *.m files and use | | >> emacsinit
|
+ | "MATLAB -> Code Sections" menu | | >>
|
+ | or the key bindings | |
|
+ +--------------------------------------+
+----------------------------------+
+
+#+end_example
+
+** Setup
+
+1. In Emacs,
+
+ #+begin_example
+ M-x matlab-netshell-server-start
+ #+end_example
+
+2. In a running MATLAB, addpath to the Emacs-MATLAB-Mode/toolbox directory and
then run
+ =emacsinit=. For example,
+
+ #+begin_example
+ >> addpath C:/Users/<USERNAME>/.emacs.d/elpa/matlab-mode-<VERSION>/toolbox
+ >> emacsinit
+ #+end_example
+
+** Example
+
+Open the following
[[file:~/emacs-projects/Emacs-MATLAB-Mode/examples/matlab-sections/tryout_matlabsection.m][../examples/matlab-sections/tryout_matlabsection.m]]
in Emacs and use the "MATLAB
+-> Code Sections" menu or key bindings to run the code sections in the
attached MATLAB.
+
+#+begin_src matlab
+ %% MATLAB code sections menu and keybindings
+ %
+ % Try:
+ %
+ % 1. Run (requires M-x matlab-shell, Unix only)
+ % MATLAB -> Code Sections -> Run section
+ % MATLAB -> Code Sections -> Run prior sections
+ % 2. Navigation
+ % MATLAB -> Code Sections -> Backward section
+ % MATLAB -> Code Sections -> Forward section
+ % MATLAB -> Code Sections -> Move to beginning
+ % MATLAB -> Code Sections -> Move to end
+ % 3. Move section content
+ % MATLAB -> Code Sections -> Mark/select section
+ % MATLAB -> Code Sections -> Move section up
+ % MATLAB -> Code Sections -> Move section down
+ % 4. Super "Windows" key bindings can be enabled or disabled, see
+ % MATLAB -> Code Sections -> Help
+
+ %% Preamble
+ clc
+ clear all
+
+ set(0,'defaultAxesTickLabelInterpreter','default');
+ set(0,'defaultTextInterpreter','latex');
+ set(0,'DefaultLegendInterpreter','latex');
+ set(0,'defaultAxesFontSize',13);
+
+ %% This is the first section, setting parameters
+
+ m = 1.0;
+ k = 4;
+ c = 2*0.01*sqrt(k*m);
+
+ F = 1.0;
+ Om = 4.0;
+
+ %% Second section - Transient Analysis
+ fsamp = 1024;
+ Tmax = 250*2*pi/Om;
+ Nt = fix(Tmax*fsamp);
+
+ [t,y] = ode45(@(t,y) [y(2); -c/m*y(2)-k/m*y(1)-F/m*cos(Om*t)], ...
+ (0:Nt)*Tmax/Nt, [0;0]);
+
+ fsz = 14;
+ figure(1)
+ clf()
+ sp = stackedplot(t, y, 'DisplayLabels', {'y1','y2'});
+ xlabel('Time (s)')
+ set(gca, 'FontSize', fsz)
+ grid on;
+
+ %% Third section
+ N = 1000;
+ fsz = 14;
+ figure(2)
+ clf()
+ plot(eig(randn(N,N))/sqrt(N), '.'); hold on
+ plot(cos((0:100)*2*pi/100), sin((0:100)*2*pi/100), '-');
+ axis equal; grid on
+ set(gca, 'FontSize', fsz)
+
+#+end_src
