Versions for multiple programming languages

[tobydriscoll]

I have a textbook written in JB, using Julia extensively.

I also have equivalent codes in Python and MATLAB for all the functions and examples. I'd like to find the most efficient and sustainable (mainly, with least duplication) way to have book versions for all three languages.

Attempt 1 was to have a parent page for each section that would {include} different versions within a tab set or other conditional framework. But AFAICT, the parent has to declare a single kernel, which rules out multiple execution.

Attempt 2 is to {embed} instead within a tab set. E.g.,

:::::{tab-set}
::::{tab-item} Julia
:sync: julia
:::{embed} #demo-instab-julia
:::
::::
::::{tab-item} Python
:sync: python
:::{embed} #demo-instab-python
:::
::::
::::{tab-item} MATLAB
:sync: matlab
:::{embed} #demo-instab-matlab
:::
::::
:::::

This seems to work as intended, with each example and function labeled (as already was the case, anyway). The chief downside is that embedded content seems to require being listed in the TOC, and therefore each chapter or an appendix will show subfolders for the three languages, with long lists of strange filenames (or manually numbered examples) giving each individual example again, out of context.

It looks like a lot to manage. Do I understand the situation correctly? Is there a way to embed content that does not have to appear somewhere else as well? Or is there an Option 3 that I have overlooked, besides not going down this rabbit hole at all?

[choldgraf]

It sounds like what needs to exist is a myst version of the orphan metadata in sphinx

https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#file-wide-metadata

That way you could have content parsed by myst so it's references exist, but not included in the table of contents. Is that right?

[tobydriscoll]

I'm unclear on what happens in sphinx. The description of orphan reads like it's just about warning messages, not about any substantive behavior. When I leave a page out of the TOC in myst.yml, its content isn't available to embed, in my experiments.

[agoose77]

Linking to a new issue here: #1666

In the article theme, we have support for supplementary notebooks that aren't the main focus of the publication. But there's no analogue for books, at the moment. I wonder if we should have some concept of "appendix".

[tobydriscoll]

I realize now that the TOC issue is not as bad as I first thought, because I can put all the to-be-embedded blocks in one file per language, or per chapter-language. Having a collection of examples in one place is not such a bad thing.

But I also realize that numbering is a potentially bigger problem for me. The embedded location is the one that I would want to govern the numbering for every appearance.

Numbering in general in myst seems to lack the power of jb, unless I am missing something. Being able to number equations within chapters or sections is useful for something at book length, so you can write "eq (7.1.6)" instead of always having to write "eq (6) in section 7.1" and the like. Not only within the book, but in lectures and discussions about it. Plus, it's frustrating to realize that you've been looking at the wrong damn equation (6) for the last 20 minutes.