# Publishing a Mathematica notebook

I am considering publishing a Mathematica notebook, used for analysis of some data, as a “supporting information” file alongside a research paper. What are the common practices for doing so, and what should I consider in making this choice? In particular, I am wondering:

• Is the .nb format suitable, or should I transform it into a CDF?
• Or is it better to include a PDF of the Mathematica notebook (thus readable by anyone), attaching the notebook itself inside the PDF (thus allowing Mathematica owners/users to use it directly)?
• Do I need to audit/edit the content of the file to remove any metadata that could leak?
-
To be safe, why not provide both the CDF file and the notebook? –  Ｊ. Ｍ. Nov 2 '12 at 15:30
@J.M. I don't want to overload the supporting information with what would be duplicate information… I have meanwhile had the idea for another possibility (PDF), and thus edited the question. –  F'x Nov 2 '12 at 15:38
@J.M. A CDF file can be opened in Mathematica and, in my experience, works just like a notebook in that context. What's the advantage of publishing both? I think I'd go with CDF so that anyone can read it. –  Mark McClure Nov 2 '12 at 15:55
@F'x You have probably already tried to do as you planned. Could you please give a feedback. Did it work smoothly? Did the journal accept this form of the Supplementing Materials? Where could we have a look at it? Have you some further advises for those who choose to follow this way? –  Alexei Boulbitch Aug 14 '13 at 11:19
@F'x, so how did it go in the end? –  Ajasja Jan 20 at 18:59

While this might depend on the journal where the submission goes, here are the available options (possibly combinable) in the advised priority:

• Notebook. Pro: code can be run if Mathematica exists; no limitations (like in CDF); Con: needs Mathematica, cannot be opened in the free Player; might contain sensitive data (see here); interpreting file contents without Mathematica might be really hard (e.g. in a text editor).
• CDF. Pro: can be run; can be opened in Mathematica and in the free Player as well; works like a notebook; Con: needs at least the free Player; CDF has some limitations compared to a native notebook; possible security issues (for example here). See some advice on when to save to .nb/.cdf.
• PDF. Pro: probably anyone can read it. Con: none can run it directly; there are many issues with exporting (mostly with graphics, see here, and here); copy-pasting from PDF might be problematic (typesetting, cells, etc.).
• Pseudocode. Pro: anyone can read it, almost like plain text; it probably gives the easiest way to allow for someone to port the code to other languages. Con: cannot be run; needs extra effort to convert existing code to pseudo; might not be straightforward (see a converter here); only works for reasonable code volumes; converting back to working code is equally hard;

Please feel free to add to this post as you see fit.

-

I am also just finalizing a paper with the Supplementing part which I will try to submit in the form of a CDF file to be downloadable from the journal site. It is not a paper somehow related to programming, but just a regular paper in physics. I hope, though not sure, of course, that the journal will accept the Supplementing in this form, as it is not granted that the journal will accept the paper at all (not due to the format of the Supplementing).

Anyway, the Supplementing is prepared in a form of a CDF file. Here I list few rules I followed. The aim of these rules is to enable reading and getting maximum from my document for the reader who is unaware of Mathematica.

1. In order to give the reader a hint, of what he should do to read the Supplementing I included a special reference in the text. It is of the same sort as the references to cited literature in the end of the paper. This one, however, informs the reader that some material necessary for understanding he finds in the Supplementing, and that he needs to install the CDF Player to open it. I also write in this reference that the Player is freely downloadable from the Wolfram site and give the precise address of the page from where to download the CDF Player.

2. I start the text in Supplementing by the instruction on reading this document. In this instruction I very briefly explain what are interactive elements that the reader might meet in the document and bring examples of few of them, such as buttons of different sort that I use.

3. I use several interactive demonstrations, built on the basis of Manipulate, or of a comparable sort. Visually they are arranges analogously to figures. This means that the demonstration has the option Alignment->Center and below such a demonstration the reader finds a demonstration number and a text. Instead of Fig. 1 used for figures I write ID. 1 for the interactive demonstration. In the text I give a brief explanation of how to operate the demonstration in question, such as: "Move sliders to change parameters, pick up the locator (here I copy-paste the locator image) by the left mouse button" and so on. The target of all these explanations is a reader who does not use Mathematica and sees all these elements for the first time.

In fact that's all concerning simplifying reading for one unfamiliar with Mathematica. There are, however, few more hints about it.

A) The form should be CDF, rather than NB, in order to enable anyone who believes it to be necessary to download a free CDF Player and to read the paper. The .nb paper is not the option for this reason.

B) I feel that the Supplementing in the CDF form is only justified, if the interactive demonstrations are crucial for understanding the text. I would not do this otherwise, though the paper might be much more beautiful, if presented in the cdf form. However, the necessity to download and install the player may repel a lot of potential readers. If the interactive demonstrations are not really necessary, I feel that it is better to make it in the PDF form.

C) A minor thing, though useful: in such a document instead of sending the reader to some reference (such as a reference to some formula staying in another part of the document, to a literature source in the end of it, or to an image) one can bring the reference (formula, reference or image) to the reader. This strongly simplifies reading. There are several ways of doing it, but this is probably better to discuss separately. You might also wish to have a look on the discussions held in MathGroup (http://forums.wolfram.com/mathgroup/) on this subject during the last few years, especially ideas formulated by David Park there.

Just a concluding remark. We are doing such a thing among very first ones. What we will produce may accelerate a mass appearance of such type of documentation. It may also inhibit it, if we are unlucky and the documentation quality is poor. I feel that there is a certain responsibility about it.

Have fun.

-