search

introocean / introocean-en

Introduction to Physical Oceanography by R. Stewart
Other
68 stars 11 forks source link

Convert to literate document #3

Open mankoff opened 4 years ago

mankoff commented 4 years ago

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

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

koldunovn commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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).