Convert to literate document

[mankoff]

Change LaTeX -> Org Mode. Embed code examples in the document.

• Org Mode can export to LaTeX and export to bit-compatible with the original LaTeX
• Org Mode can be used to render the book online (on GitHub, for example).

Once in Org Mode, equations and graphs could be coupled with code (Python and/or Octave) and be made interactive.

[koldunovn]

Hi @mankoff
Can you, please, be more specific. I don't have any experience with Org Mode. Fast googling makes me think it is something specific to emacs?

In general, it would be nice to have the book in a more modern format that is interactive and searchable. I personally would prefer Sphinx, for example. But from my experience converting latex to Sphinx takes a lot of time. I would be hesitant to move too fast from the Latex, which is still lingua franca for technical documents and potential contributors. Again something to discuss and think about.

[mankoff]

OK - as you point out, Org is Emacs-specific for authoring which means maybe it is not appropriate to tie this textbook to that editor. But it is not emacs-specific for viewing - GitHub renders Org files very well.

The title still stands - a literate document with interactive code embedded in the textbook is probably a better learning device than a static textbook. But this textbook may not be the appropriate place for this. Feel free to close if you agree.

[koldunovn]

I don't think that Latex is the best format in 2020, and having the book in a more modern interactive format would be useful. But one has to decide what is the best way to convert (and who volunteer to do this :) ). We can keep an issue as a reminder that this is something we would be interested to do in principle, and a place were people can discuss the options.

[ocefpaf]

I suggest a Jupyter-book format. We can render online, make interactive plots, publish as HTML, convert to pretty much any format. It is a lot of work and the Latex conversion never renders in the same way... But I don't see a lot of people reading this in PDF form anymore.

[koldunovn]

@ocefpaf I am all-in for the Jupyter-book, or anything that supports well conversion to different formats, but this is a huge amount of work, espetially if one would like to do interactive plots/examples inside.

[ocefpaf]

Maybe we can try to apply for a grant or something similar to get help from the community.
If we cannot, then we need a plan with small increments. Like:

1. maintain the the Latex for now but split the document into smaller chunks
2. re-do some figures using Python/R so they are "interactive ready;"
3. slowly convert each chunk to a jupyter notebook, or markdown, and then the jupyter-book.

[koldunovn]

Do you have in mind funding opportunitues we can apply for? I will try to search for something in Europe. The steps you suggested sounds very reasonable to me.

[ocefpaf]

Do you have in mind funding opportunitues we can apply for?

Nothing comes to mind at the moment but I'll ask around and keep an eye for it.

[richardsc]

Late to the game here (just discovered this repo last week!), but I agree with @ocefpaf the Jupyter notebook approach would be fantastic. Particularly the ability to embed some interactivity and also to highlight the examples and figures using code from a variety of languages and approaches.

I am also not aware of any existing funding opportunities to look at here, but in my job I am often hiring technical people for various science/data jobs, so breaking up the process means that we could take advantage of a range of opportunities (co-op/summer students, for example, who work on specific parts relevant to their studies).