The Python Software
Foundation has given me a grant to open source my course on
software engineering for scientists and engineers. I’ve been
consulting with several people on what the course’s exact content
should be; the other issue I have to sort out before I start work is
its format. The course will include:

• point-form lecture notes that:
  • lecturers can use in class
  • students can skim through when they already know something about
    a topic
• full-text explanations for people who ”don’t” know the topic,
  and won’t be able to figure it out from point-form notes
• images
  • line drawings
  • screen shots
• programs
  • The lecture notes and text will need to be able to refer to
    specific sections, either by callout (O’Reilly style—cleaner look,
    harder to engineer) or by line number
• sample data files
• “generated” files (e.g. program output)
  • Must be able to re-generate all program output
    automatically
  • Must also get a report if/when any of it changes, so that I can
    check back against the text
• supporting code
  • Makefiles (or the equivalent, if I use SCons or some other system)
  • libraries and other big (often platform-specific) things

The question is, how to prepare, store, transform, and present all
of this? I bring this up here because my students face many of the
same challenges every time they have to write a final report. While
they don’t need to mix slide content and prose side-by-side, they do
have to manage images, code fragments, and so on.

Lots of systems already exist that do some or all of what I want,
and new ones are appearing all the time. (For example, S5, the Simple
Standards-Based Slide Show System, uses XHTML and JavaScript to create
a simple slide show.) The problem I have is that I’ve used all of the
ones described below, and haven’t been happy with any of them:

• A (modified?) form of Wiki text as the source (so that it’s easy
  to edit and diff)
  • Generate slides and prose programmatically
  • Use a simple CGI system to display pages in a browser while
    editing in order to check formatting
  • Transform generated HTML/XML to create printable copy
• LaTeX
  • Already has grown-up production tools (don’t need to invent any
    wheels!)
  • Editing and diffing is harder than Wiki text (comparable to
    XML)
  • Expressing formatting right (e.g. indentation of code samples in
    slide bullet points) is easier than with Wiki text
• HTML
  • Can view exactly what I’m writing…
  • …except I don’t want to: included code, point form vs. prose,
    etc.
  • Can CSS take care of some of the display/view problems?
• XML (home grown)
  • Can provide exactly as much information as I need to
  • Transformation is relatively straightforward
  • Do I really want to build up my own tagset?
• XML (borrowed from the Pragmatic Programmers)
  • Don’t know if they’d let me
  • Doesn’t handle slides
• XML (DocBook or other)
  • Overkill (esp. from an editing point of view)
  • Don’t know if it handles slides or not
• WYSIWYG (Word, OpenOffice, etc.)
  • Hard to process (e.g. extract slides to one fileset, prose to
    another, or insert/check code samples)

What else is there? What have you used that helped make you
productive?