< Back to IRCAM Forum

Towards a revivified OpenMusic manual

OpenMusic
#1

(Split from the docstring thread.

Karim,

By way of trial, I took one of the files you gave me–the title page of the old Manual–through a round-trip conversion through Markdown, using Pandoc:

As you can see, the output HTML is lacking the JavaScript elements of the original, but otherwise isn’t too bad and was easy to make.

Specifically, I used the “dialect” GitHub-flavored Markdown, which had a couple of eminent qualities:

  1. It’s the format of GitHub, obviously, where OM is hosted.
  2. It’s a uperset of what this forum is already used to.

It shouldn’t be hard to convert the whole #manual to markup, and then convert back to HTML, as needed, for inclusion into the website.

The manual is partially uploaded to this repo. More to come.

-Jonathan

#doc

4 Likes
#2

Dear Jonathan,

Amazing. Thank you. Once converted, we will update most of the contents. Basically it is still valid, but many things have been added since then. We (me and all the om community) is grateful for this. I hope it isn’t time consuming.

Best
K
PS: Keep me informed

1 Like
#3

Here’s the next step in what I hope is the right direction. The rest of the old manual is converted to Markdown. The process is scripted and can be repeated as necessary to refine the results, though it’s not yet well documented (#18). I’m using a Lisp HTML library for this part.
Once that is completed to you guys’ satisfaction, my plan is that the Markdown files should become the basis for future editions of the manual, and be simpler to maintain than HTML.

You’ll note that the Markdown files, in om6-manual/co, link to other Markdown files, making the whole thing browsable on GitHub. If you will also want an HTML version, this can be generated with a second set of functions which edit the links again. All the HTML files in the same directory were made this way; for comparison, the orignal files are now in om6-manual/v6_6-original. I have improved the depth of this process, as well: the files spot-check as valid HTML 5. It’s still ugly-looking, though. I haven’t fixed the JS.

We (me and all the om community) is grateful for this.

You maybe should wait to thank me till it’s done! There are many remaining issues.

I hope it isn’t time consuming.

It is slow, but that’s because of the process I’ve chosen to follow. I like to address problems in “topological order,” which isn’t necessarily the order they appear in; I also experiment with programming techniques and study new topics concurrently. For instance, still learning how to use Pandoc, and I know very little of the specifics of HTML and webpage design.

– J.

2 Likes
#4

Wow!
Lovely!
Thank you a lot! This is very valuable to all of us!
THank you Jonathan!