WorkingWiki/Tutorial

From Projects
Jump to: navigation, search

A short WorkingWiki demo video
It's easy to start using WorkingWiki for simple cases, and gradually advance to more complex projects. This tutorial walks you through some standard cases for using WorkingWiki easily.

Note: This tutorial is about "plain" WorkingWiki - it shows how to write LaTeX papers and make simple scripts. To learn to use the custom framework for R scripts that we've developed at McMaster, see also http://lalashan.mcmaster.ca/theobio/mmed/index.php/WorkingWiki_Tutorial.


One case: start a LaTeX project from scratch

Suppose you want to use LaTeX to write a paper collaboratively with your team. Just start with a simple LaTeX file, the way you would if you were working by yourself without the wiki. Create a wiki page for the paper and place your LaTeX code on the page, surrounded by source-file tags, like this:

<source-file filename="my-filename.tex">
\documentclass{article}
...
</source-file>

It doesn't matter what filename you choose, as long as it ends with .tex.

After you add this file to the page and save, the wiki will ask you whether it should add the file to a project. The project name will probably be the same as the name of the page you are editing. Go ahead and say yes. See below for more on projects.

Once the file is installed in its project, the next time you load its wiki page, the WorkingWiki extension will save this file into a working directory, compile the latex and render it into HTML (using MathML for any math content if your preference settings allow it and your browser supports it, or using images for the math otherwise), and display the result on the wiki page, along with a link you can follow to make a pdf version of the document. To make changes to the latex source, just edit the wiki page like any other.

Combining multiple files into a project

As the paper becomes more complex, you may want to add figures that involve image files, a .bib file for bibliographic citations, etc. These files will need to be saved into the same working directory as the main .tex file before compiling it. This requires two steps: add each file to the wiki, and put all these files into a project together. A project is a set of files that are compiled together in a single working directory.

You already have a project with one file in it, and you can add more files to it as they come up. One way to do this is using its project management page: on the left sidebar of the page where your tex file is, there should be a box labeled 'projects', with a link to the page for your project. On that page you can add more source files, whether they are textual files embedded in wiki pages using the source-file tags, or image files uploaded to the wiki (or text files uploaded as if they were images, whatever). Fill in the filename and its wiki page location and click 'set'. All the source files listed on the project management page will be saved to the working directory before any compilation operation.

Files can be added to the wiki on any page. You can combine adding your textual files to the wiki with adding them to the project by using project= in the source-file definition:

<source-file filename="whichever-file.tex" project="projectname">
...
<source-file>

If you are using the simple case of letting WorkingWiki create a project for you with the same name as the page you're editing, you can leave out the project="projectname". (There are some other specially supported locations as well.)

Either way, when you add this source file to a page and save it, you will be given a "Click here" link to add the file to the project.

To add an uploaded image file (one on a File: or Image: page, that is) to a project, you have to use the project management page. You can combine the two steps by using the "Import project files" link on the project management page rather than the standard "Upload file" link, or by adding your image filenames to the project before uploading them, then clicking the 'upload missing source files' button that will appear just below the list of source files.

The LaTeX Example page provides a sample project that makes a LaTeX document from multiple files. Click "edit" (or "view source", if you're viewing this as a read-only wiki) to see the wiki text of the page with source-file tags, and click the project name in the sidebar to see how the project is organized.

Mark subsidiary files to avoid inappropriate compilation

Currently, the WW extension tries to compile any file whose name ends in .tex into an HTML version for display. When a file is not a complete document, only something to include in some other .tex document, you want to stop it from trying to compile, because it won't work by itself. Disable that step for those files by using the display attribute:

<source-file filename="subsidiary-file.tex" display="source">
 ...
</source-file>

You can also use display attributes just to control the look of your page. Your source files will be saved to the working directory the same regardless of any display option. Other options are display="link", which will display only a link to the contents of the file, and display="none", which will make the source file invisible on the page. There is more about the display attribute in the documentation.

Another case: uploading an existing LaTeX project

If you are already working on a paper and you want to put it on your wiki to share the work with other people, you don't want to spend more time than you have to pasting files into wiki pages and uploading images one by one. We have a custom interface to help with this job. Package your existing project directory into a .tar.gz or .zip file, then click the 'Import project' link in the 'projects' box in the sidebar. The Special:ImportProject page appears, allowing you to upload your package file. Once that's uploaded you arrive at the Special:ImportProjectFiles page, to assign each of the packaged files' project file names and page locations. Click 'Skip this one' for any files that are made by the computer and anything else you don't want to import — importing is only for source files ("archived project files" are an exception, for more advanced applications). Check all the destination pages carefully to make sure they are the pages you want before submitting. When you do submit the form, the file contents will be saved onto the wiki pages and the project will be updated to include the new files.

An alternative way to import project files is to use the ImportProjectFiles page directly to upload individual files from your computer. You can reach that page by the "Import Files" link at the top of your project's ManageProject page, or you can add your filenames and page names using the 'set' form on the ManageProject page, then use the 'Upload missing files' button there to invoke the ImportProjectFiles page with the relevant info preloaded.

Or, if you prefer, paste the source files into the wiki pages yourself, and then follow the wiki's suggestions to add each of them to the project after you save.

There is also a command-line tool for uploading that you can use if you have administrative access to the wiki's server: once you have the project files in a directory on the server computer, with as few extraneous files as possible, then run

sudo -u apache php (wikidirectory)/maintenance/importProjectFiles.php --conf=(wikidirectory)/LocalSettings.php --projectname=(projectname) (projectdirectory)

substituting the wiki's installation directory, the desired project name, and your project directory, respectively. The importProjectFiles script will ask you a series of questions about how to import each file. As with the wiki interface, you can use this script to add or replace files in an existing project, or create a new project.

Working with scripts

The WorkingWiki extension can support various kinds of scripts as source files as well as LaTeX files. On lalashan we currently support R and perl scripts, and a few other languages. Source code files and output files can be embedded in wiki pages, and output files are automatically updated as needed.

To include a program's output in a wiki page, use project-file:

<project-file filename="xyz.out" project="projectname"/>

Notice the closing "/>" rather than just ">". When it finds this tag on a wiki page, WW will save all the source files to the project's working directory, then attempt to make the requested file and place its contents on the page. This is done by invoking make to create the file. There are a number of default make rules, for instance to make a .pdf file from a .tex file of otherwise the same name, and to make .png files from other graphics formats. For more particular targets, you will need to provide a makefile. Include the makefile the same as any other source file:

<source-file filename="Makefile">...</source-file>

At WorkingWiki/Script Examples are a couple of examples of a simple project that runs a script. The script output can be an image, or a text file, or various other formats, or multiple files. You would simply insert <project-file .../> for each output file you want to make and display, and make sure there are make rules for each of them.

Note that your wiki administrators may provide more make rules than the standard ones that come with WorkingWiki. Here at lalashan, for instance, we have extensive rules for R scripts and some other things.

Inline LaTeX commands

Since we have machinery for rendering LaTeX into MathML, we might as well have a convenient way to do it, similar to MediaWiki's <math> tag. WorkingWiki offers three shortcuts for this. Probably the most important is $$(latex math)$$. This is a simple way to write math within a line of wikitext. $$ assumes LaTeX math mode, and all four $ signs have to be on the same line of wikitext.

For instance, if you write $$\frac{a}{a+b}$$ in any page on a WorkingWiki-enhanced wiki, it will appear as aa+b.

The other two shortcuts are {$(latex math)$} and <latex>(latex text)</latex>. The former interprets its contents in math mode, and the latter interprets in text mode. Unlike $$(latex math)$$, these two constructions can span multiple lines. So writing

<latex>
\begin{align*}
 (x+y)^3 &= (x+y)(x^2 + 2xy + y^2) \\
         &= x^3 + 3x^2y + 3xy^2 + y^3
\end{align*}
</latex>

produces

x+y3 =x+yx2+2xy+y2
=x3+3x2y+3xy2+y3
on the wiki page, and writing

{$\frac{a^2 + ab + b^2 + ac + bc + c^2 + ad + bd + cd + d^2}
{a^2 + b^2 + c^2 + d^2}$}

produces a2+ab+b2+ac+bc+c2+ad+bd+cd+d2a2+b2+c2+d2.

As with all of WorkingWiki's LaTeX processing, these expressions are displayed using MathJax.

If you have a browser whose native MathML rendering is good and you would rather use that, select the MathML option in your wiki account preferences.