Module Authoring Infrastructure

3 replies [Last post]
shaffer
shaffer's picture
Offline
White BeltYellow BeltGreen BeltRed BeltBlack Belt
Joined: 2009-05-28
Posts:
Points: 2019

As mentioned in another post, we are going to try to make better use of this forum for significant policy and technical discussions about the OpenDSA project.

Recently, we have been discussing the authoring infrastructure for modules. Until now, we have been using raw HTML augmented by some additional tags that are handled by our own pre-processor script. Documentation is at http://algoviz.org/OpenDSA/Doc/ModuleAuthoring.html . This has been satisfactory for creating a few test prototypes, but we would like to migrate to something with better support rather than reinvent the wheel if we can find an alternative to get us what we need.

Following discussions with Brad Miller at SIGCSE, I started investigating reStructuredText (reST — see http://docutils.sourceforge.net/rst.html). See Brad’s interactive Python textbook (http://thinkcspy.appspot.com/build/index.html) for a good example of what is possible. This includes extensions to reST that support editing and executing Python code right in the browser.

Tom, Ville, and I started discussing the possibility of using reST, and Ville rightfully pointed out that we haven’t critically examined other possibilities. So I have been doing some research into various alternatives, and my results are at http://algoviz.org/algoviz-wiki/index.php/Module_Authoring_Support.

Based on this, I still believe that reST is our best option. For a demonstration of our material converted to RST (primarily my standard Shellsort demo), see http://algoviz.org/OpenDSA/RST/build/html/.

We would love to hear more feedback on this issue.

 

ville
ville's picture
Offline
White BeltYellow BeltGreen BeltRed BeltBlack Belt
Joined: 2009-05-28
Posts:
Points: 559
Re: Module Authoring Infrastructure

At this point, I agree with you. ReST seems like the best option given our requirements and goals.

Ville Karavirta, Aalto University, http://villekaravirta.com/

shaffer
shaffer's picture
Offline
White BeltYellow BeltGreen BeltRed BeltBlack Belt
Joined: 2009-05-28
Posts:
Points: 2019
Re: Module Authoring Infrastructure

I have been doing some more research. I have determined that (with more or less pain that I cannot quantify at this point), DITA, AsciiDoc, and Markdown all have mechanisms that allow for access to MathJax (so they can all allow LaTeX math formatting), and they all have passthrough mechanisms (so that we can pass through JavaScript code and thereby have dynamic visualization snippets and "live code").

OK, so that means reST, AsciiDoc, DITA, and Markdown are all potentially viable for doing our project. How to decide between them?

Here is my biased view on this:

Some of the markup languages are XML-based (like HTML, they have lots of tags), and some are "lightweight" (in general, they require less typing to express the format). If you had no other reason to choose, lightweight appears to be the way to go from an ease of creation standpoint. From an ease of reading/understanding the source standpoint, any lightweight markup is hands-down better (that being a primary design goal). That makes DITA (and, of course, DocBook) unattractive if you can get what you need from a lightweight language ecosystem.

From what I read, the consensus is that, while Markdown is more convenient than reST for small tasks, it is basically "reST lite" overall. For what we want to do, we are probably better served by the reST flexibility and ecosystem.

The biggest competitor to reST, from what I can determine so far, is AsciiDoc. But I haven’t learned enough about that yet.

 

Does anyone have some helpful input to add?

 

naps
Offline
White BeltYellow BeltGreen BeltRed Belt
Joined: 2009-06-11
Posts:
Points: 65
Re: Module Authoring Infrastructure

 Yes, reST seems to be the best choice.   In theory the big advantage of XML-based languages is the huge variety of tools that are available to process and transform them into other languages.   But from what I understand, the Python community has developed many analogous kinds of tools for reST, so that would remove one reservation that some might have regarding a non-XML language.