Paper for MathWikis-2011
From projects
My submission for the ITP 2011 Workshop on Mathematical Wikis in the Netherlands in August.
This paper is also archived on arXiv.org now.
WorkingWiki: a MediaWiki-based environment for collaborative research
Abstract.
WorkingWiki is a software extension for the popular MediaWiki platform that makes a wiki into a powerful environment for collaborating on publication-quality manuscripts and software projects. Developed in Jonathan Dushoff’s theoretical biology lab at McMaster University and available as free software, it allows wiki users to work together on anything that can be done by using UNIX commands to transform textual “source code” into output. Researchers can use it to collaborate on programs written in R, python, C, or any other language, and there are special features to support easy work on LaTeX documents. It develops the potential of the wiki medium to serve as a combination collaborative text editor, development environment, revision control system, and publishing platform. Its potential uses are open-ended — its processing is controlled by makefiles that are straightforward to customize — and its modular design is intended to allow parts of it to be adapted to other purposes.
1 Introduction
[This section will be brief and hopefully not pointless. These notes will be removed once there is text.]
2 WorkingWiki
[This section describes what WW is and does.]
WorkingWiki (3) is a software extension for the popular MediaWiki system that makes a wiki into a powerful environment for collaborating on publication-quality manuscripts and software projects.
The WorkingWiki extension allows you to store “source files” in your wiki and develop, test, run and publish them easily, along with the products of computations using those source files. Examples include a project of five LaTeX files and six EPS images that compile together into a single PDF file, or an R script that includes two other R source files and produces a CSV data file and several EPS figures. The WorkingWiki extension keeps track of when the source files have changed and when to redo the processing to update the output, and how to display the various file formats involved. The output files and images can be displayed in wiki pages along with the source code, and can be used as inputs to further computations.
Example: collaborating on a LaTeX document
It’s very common for a group of scientific authors to write a paper by emailing each other copies of .tex files daily or hourly. This is inconvenient â in order to look at the paper you have to save the file into a directory and compile it â and unreliable â it’s easy to get mixed up and lose someone’s edits, or overwrite them with someone else’s copy of the file. One solution is to use a revision control system such as Subversion (1) or Git (2) to manage the source code, but if any authors are unwilling to take on the work of learning to use the tool, they’re likely to fall back on emailing the file or just dictating changes to someone else. WorkingWiki addresses this problem by providing basic revision control features together with easy editing. Once the .tex files, .bib files, and images are in the wiki, it’s easy for everyone to edit and see the updated results, and the wiki keeps track of all the changes and their authors, and makes it easy to review or undo them. It also provides a convenient place to discuss changes, without having to put comments into the manuscript itself, and can be used as a website to present the research to the public.
Example: collaborative, reproducible lab science
A research team can use WorkingWiki to archive experimental data (using the wiki’s history features to record who uploaded which data points when); develop their data-processing scripts collaboratively in the wiki; construct the scripts that produce figures and tables in the wiki; create the manuscript that presents the results in the wiki; and finally export the manuscript as a .tar.gz file ready to submit to a scientific journal. The wiki can then be used to publish the data, source code, and manuscript to the world as is. This process captures all the material needed to understand and reproduce the research project, with its revision history intact, and in a form that is easy to annotate and publish online. A research team developing simulation programs rather than using experimental data can use WorkingWiki in the same way.
WorkingWiki is developed principally for research groups, but is likely to have a variety of other uses as well for mathematicians, scientists, and software developers.
3 How WorkingWiki is used
[Some detail, to give readers a clearer picture of what WW can and can’t do.]
WorkingWiki operates on source files that are stored in standard wiki pages. Source files are collected into projects. When an output file is called for in a wiki page or by other means, WorkingWiki does its work by invoking make to create or update the file from the source files in its project before displaying it. In this way, users can edit their code (or their data files, or .tex documents, or files of any type) by editing the wiki, and run the code and view the output (the typeset version of your paper, the latest version of your figures, the textual output of your program) just by previewing or saving the page.
WorkingWiki provides some features of an integrated development environment: it coordinates compiling (if necessary) and running the code when relevant source files have changed, and displaying the results.
It provides some features of a revision control system: it uses MediaWiki’s history features to record author, date/time, and content of every change to the files and the wiki pages they are connected to, and it allows viewers to export the source code to their workstations and work on it offline.
WorkingWiki’s separate “project engine” component provides a job management system on the server. Lengthy computations can be run as background jobs and integrated into the wiki’s output when ready.
[Briefly outline the software’s internal design, including the separation of wiki interface code from the “project engine” back end, and how the back end could be useful in other wiki projects unrelated to MediaWiki.]
It integrates editing and running code with wiki editing. Source and product files can be mixed freely into wiki pages’ text. Editing is fully collaborative. The effects of changes to source files can be fully previewed before saving to the wiki. The WorkingWiki-extended wiki is a simple, elegant way to present a research team’s work to the world.
WorkingWiki has special features for translating LaTeX documents to HTML, for display directly in the wiki page. Using Bruce Miller’s LaTeXML software, WorkingWiki allows you to edit complete LaTeX documents collaboratively on the wiki, view the typeset output in the wiki page, and export the documents’ source files to your workstation when ready to submit or circulate. Contents of a LaTeX document visible in the wiki page, including figures, citations and equations (optionally using MathML), as well as in the standard PDF format. The editing history of all files is maintained, including authorship of each change.
WorkingWiki’s LaTeX handling works with documents that involve multiple files, stored on multiple wiki pages. LaTeX \include, \bibliography, \includegraphics, and like commands are supported. Filenames do not need to match page names.
WorkingWiki is extensively customizable, supporting collaborative development and use of computer programs in any language. Images and other files created by computer programs can be included directly in LaTeX documents and read by other programs, and are updated automatically when the programs or source data files are changed. The development environment can be customized by adding default make rules, and in many other ways.
4 Uses of WorkingWiki
[Move some of the above points about IDEs, revision control, etc. down into here.]
WorkingWiki supports reproducible and open research by allowing researchers to collect all the files involved in a research project â data files, source code, documentation, publications â in an accessible place where collaborators can develop them together, and the public can be allowed to download the entire project, to verify results and try their own experiments.
5 Examples of WW projects
[Feature a few things that we have actually been doing with it]
6 WorkingWiki and math wikis
Since all processing is coordinated by makefiles, it would be straightforward to use WorkingWiki to develop documents using OMDoc, sTex, or other LaTeX-related environments. It can also be used to develop, store, and process documents in automated proof systems, or using any other tool that can be invoked from a UNIX command line to process files.
I will demonstrate WorkingWiki’s major features, present some mathematics and biology research projects our group is pursuing using WorkingWiki, and demonstrate the use of WorkingWiki for “open lab notebooks”.
I will explore some ideas about how WorkingWiki may be useful to the semantic data and computational theorem proving communities.
References
-
Version control with subversion,first edition, O’Reilly.Note: \urlhttp://svnbook.red-bean.com/External Links: ISBN 978-0-596-00448-4, Link.Cited by: 2.
-
2
Git: the fast version control system,Note: \urlhttp://git-scm.com/Cited by: 2.
-
3
Note: \urlhttp://lalashan.mcmaster.ca/theobio/projects/index.php/WorkingWikiCited by: 2.
