Message Boards Message Boards

Writing Literate Notebooks

Posted 9 years ago

I would be interested in starting a discussion on writing literate Mathematica notebooks. For purposes of the discussion a literate notebook is one that looks like a technical paper with sectional organization, textual discussion, active calculations or derivations, and dynamic presentations of concepts and results. They might be used in communicating with other people, writing tutorials, publishing papers, as essay question responses in technical courses, or simply for studying material.

I would like to know what other Mathematica users think about this.

1) Do you think this is a significant application of Mathematica?

2) If so, do you think the design and implementation of Mathematica is adequate for the purpose in terms of capability, stability and ease of use?

8 Replies

I think that this application of Mathematica is critical. This is the kind of thing that has been promised for Mathematica since almost version 1. I have used Mathematica in this way when I was working to communicate with my work colleagues, but there were significant tissues, only some of which have been addressed in recent releases.

First off, the style sheet mechanism is entirely inadequate to the task. The user should be able to embed fonts, as you can with PDF documents. There needs to be a way to globally replace, for example, Arial with something else, and not have to hint around all the variants on the styles to find them.

Having two column documents, or sections, is also useful. This functionality can be implemented with Grid[], but it is not the same as a word processor. Even for documents which are to be viewed on-screen, having two columns is a useful option.

The CDF player (or its replacement) needs to be more flexible, and allow the end user (who does not have Mathematica) to do more things. In my former company, there was an issue with installing the reader, but that is not a problem with Wolfram technology, but one with IT myopia. Still, something might be done.

I would like to see a website, similar to the Demonstrations project, where users could submit documents to share with others. The restrictions for a Demonstration — size, restrictions on text, etc. — limits what can be done. I have done some work that is not worth publishing formally, but which, I hope, would be interesting to other people, and not just Mathematica users.

I'm pretty sure that embedding fonts in a notebook document is possible. The style sheets need a good revision, with the goal of delivering an excellent experience, for both producers and consumers, of documents that will (only) be accessed on screen. With these changes, I thnk that Mathematica is up to the task.

Beyond that, having a site to share documents, similar to the Demonstrations Project website, will provide an incentive to make the documents, and to provide a showcase of good design for other users. I know that something like this has been discussed at previous Wolfram Technology Conferences, so it should be possible for Wolfram Research to do this as well.

I continue to struggle with the writing of Notebooks that are "literate". I think Knuth had a great idea when he proposed "Literate Programming" but it got side-tracked, in my opinion, with the macro-expansion implementation.

My main problem is that Mathematica best practices seem to dictate use of functional programming - and, in general, I like this idea very much. The resulting problem is that the best way to develop functional programming solutions seems to be to design and implement things bottom-up and inside-out. (I've seen Wolfram personnel do this in Webcasts and I've had a conversation with a Support staffer about this very point.)

While the resulting code is compact, and - assuming it fits in main memory - very fast, it is also (to me) very difficult to understand later. Notions such as abstraction, information hiding, and the lot, don't seem to have a place in this paradigm.

For example, arguments critical to understanding what a function does can be "far" away from the invocation of the function making it hard to "grok" things conceptually.

So, I write prose to try to describe how whatever I wrote works, and, often, why I did it the way I did. I do this so I can come back later and understand what I did.

To me, "Literate Programming" is about capturing much of the thought process that went into the development of the code.

If I were a better mathematician I might be able to make my solutions "read" more like math, but I've been unable to do this.

POSTED BY: Mark Tuttle

I have several questions about the current state of creating and reading CDF files.

Can they use private (third party) style sheets, and packages? Many advance research papers might use private routines in packages. Could one write a document that looks like a technical paper that uses such style sheets and packages?

I'm thinking of a method where there would be something like a UserBaseDirectory for the CDF player. Then you send a zip file to a colleague or someone who was interested in the 'paper' that contained the application with package(s) and style sheets. He could just unzip it into his CDF UserBaseDirectory location and read the paper.

In Mathematica 9 it was possible to install packages and style sheets in the Wolfram CDF files, where they had Applications and style sheets, and it appeared to me to work. But WRI choked that path off.

Owning Mathematica, or at least professional Mathematica, or Premier service should be enough to produce such documents.

It should be almost as easy to produce a CDF document from a Mathematica notebook as it is to produce a PDF document.

My view is that CDF is not yet good enough, but maybe getting close. Have there been any significant improvements toward this goal since Mathematica 10.0 first came out?

Posted 8 years ago

I have been teaching math for the past 30 years and have used Mathematica for about the last 15. It's an amazing tool, but I have to report that after all this time, I still have TONS of problems making my materials available to a wider audience. My peers who write documents in "Word", all share their tests and notes and other documents, sharing the work. The documents are all 'dead'. but since everyone is using the same application, it's easy to collaborate. When I try to share some of my notebooks with colleagues, they are all "amazed" at what Mathematica can do but A) are not willing to change their approach and B) often find that they can't even install the CDF player to view the files because of security issues at their place of employment.

Currently, I am employed as academic support (aka , math and science tutor) at a technical school. I have hundreds of Mathematica documents that I could use to help with explaining ideas, but again, I find there is no easy way, well, in fact no way, for me to share these documents with students. I can't install any software on the schools computers, and students are all using phones and tablets so no go there.

I have always appreciated David's perspective on writing and using Mathematica as a communication tool. My question at this point is, what should I do with the hundreds of "teaching" notebooks I have? I totally agree that the demonstrations site is not the place for these. It's a great resource, but I have always wondered why there isn't some place where users could post lessons, get feedback, and make them available. Like the "Wolfram Lessons Site".

Anyway... thanks for listening... I don't suspect this has any kind of reasonable solution at the current time.

POSTED BY: Tom De Vries

I have hundreds of Mathematica documents that I could use to help with explaining ideas, but again, I find there is no easy way, well, in fact no way, for me to share these documents with students.

One can always export the notebook to PDF file for static content. For dynamic content (CDF's), then this issue is really nothing to do with Mathematica per say. The plugin is dead. Java applets are dead. So anything that requires a plugin to run in the browser is not going to work. If one wants to run dynamic content on the web these days, one can code it in HTML5 and Javascript. This will insure it runs everywhere with nothing to download or install on the user part.

But there is the Mathematica player, which anyone can download for free, and then download the CDF file and run them in the player. This will work on windows, mac and Linux. How hard can it be to install the Player? It takes few minutes.

The problem is that students can not install the player on university computers. But almost every student these days have a laptop with them which they can install the player there and run your CDF's.

I also think that WRI could do a better job in promoting CDF technology. Hardly anyone I know at school uses CDF's or even knows about them. Everyone is stuck to Matlab and static plots.

POSTED BY: Nasser M. Abbasi
Posted 8 years ago

I have a similar problem to that mentioned by T. De Vries. Now in retirement, I have hundreds of nicely formatted notebooks I would like to share over the internet. I thought the CDF technology would provide a solution but, as pointed out by N. Abbassi, security problems have thwarted the wide spread use of plugins. I thought that Wolfram Cloud Technology would provide a solution, but from what I can glean, it is not possible to display notebooks with sophisticated formatting and mathematical notation -- for example, a typical Wolfram Journal article -- in any of the commonly used browsers. This surprises me. Formatted notebooks are one of the most useful features of Mathematica and I would have thought the display of notebooks on the web to be a high priority for Wolfram cloud developers.

I would much like to hear knowledgeable people inside Wolfram discuss this issue. Is the inability to display formatted notebooks on the web a fundamental problem? or just a technical problem that will be solved when resources are freed from cloud related projects that are deemed to have higher priority? If the latter, what is the approximate time scale for a solution? If it is months, I will wait. If it is years, I will reluctantly translate my notebooks into PDFs.

POSTED BY: Tom Gladd

Some of you mentioned that you'd like a way to share notebooks, at least with other Mathematica users, and that the Demonstrations Project is obviously not the correct place. Doesn't the Wolfram Library Archive accept all sorts of documents? Or is that site really so dead by now that you wouldn't expect any readers if you upload there (and share links elsewhere)?

@David J M Park Jr, I'll happily be corrected on this, but I believe package loading and any kind of file import/export are still features of Player Pro only.

POSTED BY: Bianca Eifert

Player Pro only kills it.

Reply to this discussion
Community posts can be styled and formatted using the Markdown syntax.
Reply Preview
or Discard

Group Abstract Group Abstract