Re: [was Promotion of octave ...] Octave material for presentations

[Kai Torben Ohlhus]

On 11/26/19 9:51 PM, Juan Pablo Carbajal wrote:
> On Tue, Nov 26, 2019 at 11:48 AM Kai Torben Ohlhus <address@hidden> wrote:
>>
>> On 11/26/19 6:45 AM, Juan Pablo Carbajal wrote:
>>
>>> BTW, I remember you were working on a nb extension for publish, how is
>>> it going? Also, would you be able to weigh how much work would be to
>>> create a sphynx extension for Octave?
>>
>> The efforts of this work got stalled.  Without JSON support bug #53100
>> this simply is too complicated parsing and writing ipynb-files (JSON)
>> on my own.  Unfortunately, as time goes by the number of possible
>> implementations increases and bug #53100 (JSON) got stuck in some
>> analysis paralysis.
>>
>> Since I worked on publish between 2016 and 2018, Jupyter(Lab) has really
>> become a great tool, which you can run offline on you local machine,
>> with Octave as back-end (as I did in my presentation on Friday).  Thus I
>> find there is hardly a need to further go down the road to "improve" the
>> Matlab-invented publish-syntax (I prefer Markdown).
> 
> I think there is no room for discussion here. I also use jupyter(lab)
> for reporting and teaching, and markdown (with math extension) is
> "unschlagbar" (as of today).
> 
>>
>> The remaining projects after solving bug #53100 (JSON) I have in mind is:
>>
>> (A) Import/open .ipynb files as Octave scripts.  All Markdown sections
>> are imported as comments and remain untouched.  Output cells are ignored.
>>
> Is this on the Octave kernel or you would this as a function in octave?
> What about a pandoc filter[1] to do this? This would be python (or
> Haskel) coding, I would be interested in getting involved.


I think this should come as Octave function.  Just run
grabcode("myjupyter.ipynb") on the JSON-file and import what is
possible.  That is code sections as usual Octave code in a script file
and Markdown sections as comments.  The grabbed code is stored in some
temporary script file, which can in turn be publish()ed again.  The only
necessary dependency should be jsonencode()/jsondecode(), which do not
have to be performant at all.


> [...]>
> [3] is exactly what I meant, I wonder why this did not show up in my
> searches. It seems to be licensed under FreeBSD , do you see any
> reasons why not to prefer sphynx over texinfo? I am pretty usre there
> are opinionated positions out there for and agaisnt texinfo (I
> actually never liked it too much).
> Have you tested [3]?
> What about texinfo <-> sphynx using sphynx? [2]

Yes, I have tested [3] and considered it for one of my Octave projects I
think three years ago.  After rewriting large parts of the
documentation, the results where not very satisfying and I dropped this
approach.  Sphinx is natively written for Python code.  Thus the
documentation for multiple return arguments does simply look poor
compared to multiple input arguments, even using [3].  Especially, if we
want to document multiple ways of return value combinations.  Here an
example [4].  Additionally, function references were quite "clumsy"
compared to documenting Python code with Sphinx.  Manual post-processing
for "see also" links has to be done...  Same experience goes for Doxygen
which supports Markdown as well.  Both documentation frameworks have
their target programming languages and this is neither Octave nor Matlab
:-/  Another promising tools was [5], but the output looks a bit
"old-school", compared to Sphinx and Doxygen output.

The 1k pages manual with about 800 docstrings might be another reason
not to move away from Texinfo easily.  I can totally understand your
motivation, I don't like Texinfo that much either.  But I think it does
a good enough job for now, as out-of-the-box alternatives are rare and
just introduce new limitations for providing a little more beautiful
markup, I guess.

A more promising approach might be to search for another language with
features that Octave documentation needs (functions, scripts, classes,
multiple return values, cross-referencing ...) and see how they generate
a great looking documentation.  I am also very interesting in such a
language/tool.

Best,
Kai

[1]: https://pandoc.org/filters.html
[2]: https://www.gnu.org/software/texinfo/ under "Conversion to/from
Texinfo"
[3]: https://github.com/sphinx-contrib/matlabdomain
[4]:
https://github.com/sphinx-contrib/matlabdomain/blob/master/tests/test_data/f_example.m
[5]: https://www.artefact.tk/software/matlab/m2html/