Re: ob-octave: improve MATLAB support

[Ihor Radchenko <yantar92@posteo.net>]

John C <john.ciolfi.32@gmail.com> writes:

> Thanks for the feedback. See updated org-matlab.patch. Note code evaluation
> will now error out when using an out-of-date matlab-mode (rather than
> generating a warning) because when using an older matlab-mode, code block
> evaluation doesn't work. We need to wait for the matlab-shell to be ready.
> Without that capability found in newer matlab-mode, the errors are very
> hard to understand.

Maybe you can use `org-require-package'.
Note that we generally guarantee support for the latest stable
third-party library release. Not older. So, failing to work with old
matlab-mode is not a problem.
See https://orgmode.org/worg/org-maintenance.html#emacs-compatibility

> You mentioned that we should expect org users to understand sessions,
> however the doc on sessions is a bit light. Searching
> https://orgmode.org/org.html for "session", we see it used two different
> ways "Emacs session" and babel code block evaluations sessions described in
> "Using sessions". What is there is okay, but doesn't really help one
> understand when they should/shouldn't use babel code block evaluation
> sessions. What would be nice is if "Using sessions" were titled "Babel code
> block evaluation sessions" containing the existing content minus the "Only
> languages that provide interactive evaluation ..." paragraph because this
> is vague.

Feel free to submit a patch improving the manual.

> ... In addition, each language should have a way of describing what
> :session means to them, perhaps by extracting this info from ob-LANGUAGE.el
> or maybe ob-LANGUAGE.org, or maybe something else that inserts the language
> specific into the org manual.

See https://list.orgmode.org/877c83h09b.fsf@localhost/T/#t
[TASK] Move babel backend docs from WORG to Org manual

> * lisp/ob-comint.el: enhanced org-babel-comint-with-output
>   - The META argument of org-babel-comint-with-output now supports an
> optional
>     STRIP-REGEXPS which can be used to remove content from the returned
> output.

Please document this change in "New functions and changes in function
arguments" section of ORG-NEWS.

> * testing/org-test.el
>   - Added org-test-get-code-block which is for use by testing/lisp/test*.el
> files
>     to extract code blocks from testing/examples/*.org files for on-the-fly
>     testing using org-test-with-temp-text.

I am not sure if it is really needed.
Why not directly using `org-test-with-temp-text' and putting the src
block there? Having the tested src block away from the test itself makes
it hard to read tests.

> -(defvar org-babel-default-header-args:matlab '())
> +(defvar org-babel-default-header-args:matlab '((:session . "*MATLAB*"))
> +  "Reuse the matlab-shell buffer for code block evaluations.
> +Add the MATLAB clear command to your code block to clear the
> +MATLAB workspace.")

This docstring is not appropriate.
A docstring should describe what variable does in the first line.
Optionally, it can also describe the default value; but not as the first line.

For example, this is what I have on one of WIP branches:

(defvar org-babel-default-header-args:matlab '()
  "Default header arguments for Matlab code blocks.")
(defvar org-babel-default-header-args:octave '()
  "Default header arguments for Octave code blocks.")

See "D.6 Tips for Documentation Strings" in Elisp manual.

> +(defun org-babel-matlab-shell ()
> +  "Start and/or wait for MATLAB shell."
> +  (require 'matlab-shell) ;; make `matlab-shell-busy-checker' available

Maybe use `org-require-package' here.

> +                 (const :tag "MATLAB" matlab)
>  		 (const :tag "Maxima" maxima)
>                   (const :tag "OCaml" ocaml)
> -		 (const :tag "Octave and MatLab" octave)
> +		 (const :tag "Octave" octave)

This makes me wonder if ob-matlab and ob-octave diverged enough to put
matlab-specific code into ob-matlab itself.

-- 
Ihor Radchenko // yantar92,
Org mode maintainer,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>