WorkingWiki/FAQ

From Projects
Jump to: navigation, search

What is WorkingWiki?

WorkingWiki is a web-based collaboration tool. It has a number of important features that any wiki has:

  • History: the edit history of each page is stored. This allows each member of a project to quickly find out what other members have done by tracking changes and comparing versions of each page. It also serves as version control so old versions of pages can be restored if something goes wrong.
  • Remote access: Since projects are accessed through the web you can access your work from anywhere you can get an internet connection. This makes working from home as easy as at the office/lab. This also allows supervisors to help their students even when traveling.
  • Information sharing: Multiple people can work on/view the project at once. Once completed, all information pertaining to a project can be made publicly available easily to allow others to replicate and scrutinize all parts of the project.

But unlike most wikis, WorkingWiki also lets you write programs and run them on a Linux server. Jobs are run on the server and results displayed on the wikipage.

The combination lets you share your work, including program code and LaTeX documents, work on it collaboratively, and keep track of its editing history.

How are files stored on the wiki?

There are two types of files on the wiki: source files and target files. Source files are provided by you for use by the computer. Target files are produced by the computer for you. Both kinds are referred to as project files.

To create a source file simply surround the text with source file tags on your wiki page, like this:

<source-file filename="my-filename.txt">
Stuff in the source file
</source-file>

Source files are text files but can have a variety of suffixes including: .c, .csv, .pl, .py, etc... If you wish to use a non-text file as a source file please see below for information about uploading files.

All other project files are produced by the computer using the make rule you provide (see: "what is a makefile?"). If you wish to display them on a wikipage simply use:

<project-file filename="output-filename.txt"/>

How do I upload a file?

There are several ways to upload a file:

  1. If you don't want the file to be part of your project (and hence not part of the bundle you get with Export source files), use the Upload file link in the sidebar toolbox.
  2. If you do want the file to be part of your project then you can use the Import files link in the Manage Project interface (get there by clicking on the project name in the lefthand "projects" bar). At this point you have two choices:
    1. If you want to be able to edit the (text) file by hand on the wiki, make sure that the Destination page is the name of a wiki page, e.g. MyProject/somethingnew.tex.
    2. If the file is not human-readable (e.g., .pdf files) the Destination page should be prefixed by Image:(or, on newer wikis, File:), and should not contain any illegal characters (like "/"); e.g. Image:MyProject$somethingnew.pdf or File:MyProject$somethingnew.pdf.

WorkingWiki will try to choose an appropriate destination page name for you based on the file type, but you may have other preferences – for instance, with .csv files, which you may want to put on a mainspace page (and have a history) or to put on a File page, if they are big.

  1. Alternatively, you can add a source file to a wiki page, by simply surrounding the text source-file tags, like this:
<source-file filename="my-filename.txt">
and copy-paste the contents here
...
</source-file>

After you save the page, you will be given a link to add the source file to your project. This is equivalent to the second method above.

How do I edit a file?

How big can my file be?

Big files don't do well embedded in pages; if you have trouble, put it in the file space (see #How do I upload a file?)

You should be able to import very large files to the file space. If you have trouble, talk to the site administrator.

How do I create a new wiki page?

If you create a link to a page that does not currently exist a page with the appropriate name is automatically created, simply follow the link to begin editing the page.

Alternatively type the name of the page you wish to create into the wiki's search box. If a page with that title does not already exist it will provide you with a link to create and start editing the page.

How do I create a new project?

Projects don't have to be named after pages, but they usually are. If you add a source file (see above) on a page that does not have a project named after it, the project will be created.

Alternatively, you can type the name of your desired project into the text-box below the already existing project links at the left hand of the wikipage. This will create a new project and take you to the Manage Project page for the new project. Note: a project without any source files is automatically deleted.

There are complications that arise with subpages (for example, this page is a subpage of WorkingWiki), and with projects that are not named after pages. See the documentation for more information.

How do I run an R script?

How do I use LaTeX?

It should be as simple as: add a source file to your project that has a name ending in ".tex". If it needs other files, for images to appear in figures, bibliographies, etc., add those files to the project as well.

WorkingWiki will make a browser-friendly version of the document to display in the wiki page, and it'll provide you a link to the PDF version of the document. If something goes wrong making either of these, you'll see a link to a log file where you can look to see what went wrong.

When you change the .tex file or any of the other files it uses, the output documents will get updated automatically.

For more advanced tips about using LaTeX (and LaTeXML, for display in the wiki page), see Latex tricks.

How do I include a bibliography for a LaTeX document?

Is _________ installed on the wiki?

How do I run __________ ?

By providing the exact commands you would use on a Linux machine in a makefile.

What is a makefile?

My job takes more than 3 minutes, what do I do?

If your job takes more than 3 minutes the wikipage will time-out and kill your job so it can load. To get around this you need to make it a background job, simply modify your make commands as so:

<source-file filename="Makefile">
quick_output.txt : quick_program
	commands
ifndef FOREGROUND_ONLY
slow_output1.txt : slow_program ...
	commands ...
slow_output2.txt : slow_program ...
	commands...
endif
</source-file>

And then add 'make="background"' as an argument to the respective project files as so:

<project-file filename="slow_output1.txt" make="background" linktext="run background job"/>

This will turn your project file into a link on your wikipage and a background job will be created and run as soon as you click the link. The text of the link can be modified by using the "linktext='Run Job'" argument in your project file. Once running a box will appear on the Manage Project page as well as the top of the wiki page informing you of the status and actions you may take on your background job. It will update every time either page is refreshed. !Beware! refreshing the Manage Project page immediately after creating a background job will result in creating another background job.

A background job allows the wiki to load pages and continue functioning normally while you run your job.

Can I use a source-file in more than one project?

Yes. If you provide an explicit project name in your source-file tag:

<source-file filename="X" project="Y"> ... </source-file>

then that source file can only be used by that project. But if you leave out the project name:

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

then it can be a source file in multiple projects (though it has to have the same filename in all places). Add it to each project by opening that project's ManageProject page and using the form for adding source file locations.

If the file is uploaded to a File: (or Image:, in old wiki installations) page instead of being wrapped in a source-file tag, you can always add it to multiple projects, and in that case it can also have different names in different projects.

I'm using a large file in many projects and don't want to copy it all the time what should I do?

You should upload your large file to the File: (or Image:) space and include it in your projects using the ManageProject page.

Can I use a project-file from project A in project B?

You can make project A accessible to project B, by including it as a prerequisite project. You then access that directory using the make variables provided by WW.

Can I make multiple output files in a single makefile?

Yes, no problem. If you are make-oriented, you might want to just have a single Makefile for your project.


What is a good workflow for working in an editor and previewing etc.?

  • workflow:
    1. edit via hotkey (<command>-E) (the command will depend on your browser and operating system, for firefox on linux it is alt-shift)
    2. immediate preview via hotkey (<command>-P)
    3. IAT hotkey
    4. edit
    5. save in editor
    6. Alt-TAB to shift focus to browser window
    7. preview hotkey
    8. Alt-TAB to shift focus back to editor
    9. etc..
    10. close editor when done
    11. don't forget to save the wiki page!!! (Alt-Shift-S or other)
  • or use the Monobook.js hack to skip step #2