WorkingWiki/Documentation

From projects

"WorkingWiki: If you can make it anywhere, you can make it here."

Projects and Files

The WorkingWiki extension manages files within the wiki environment. When WorkingWiki does a computation, it collects the source files it needs from their locations in the wiki and saves them into a working directory together; then it uses Unix commands to process them; then it retrieves the output from that directory and displays it in the wiki page.

The contents of WorkingWiki source files can be stored in MediaWiki's File pages (also known as Image pages on older wikis, or Media pages), or embedded in regular wiki pages using XML-style "source-file" tags, as discussed below. WorkingWiki can do any processing on source files that can be described using a makefile, also discussed below. For example, you can embed a .tex file in a wiki page, and use WorkingWiki to process that file into PDF and HTML output and include those output files in the wiki page when it displays it to you, or you can maintain R programs in your wiki and use WorkingWiki to run them and show the images and data files that they create.

Projects

In WorkingWiki, files belong to projects. A project corresponds to a working directory on the server. Any project in the wiki can be looked at or edited using WorkingWiki's Special:ManageProject page. On any wiki page that includes WorkingWiki files, you can reach the corresponding Special:ManageProject pages from links in the "projects" box on the sidebar.

A project is made up of project files, some of which are source files. Project files that are not source files are created by make, using rules that tell it how to process the source files. When WorkingWiki needs to make and display a project file, it does the necessary processing:

• create the behind-the-scenes working directory if needed.
• find all the source files where they're stored in the wiki, and save them to the working directory as needed.
• run make to create the target file from the source files, according to the rules in WorkingWiki's makefiles and any makefiles that are present in the project.
• report any errors that may have arisen, and display the target file if possible.

Source files

A source file is a project file that is created by the wiki user. Wiki users put source files on the wiki in two ways: by creating source-file tags on textual wiki pages, and by uploading images or other files to file pages.

source-file tags

A source file can be embedded in the text of a wiki page by enclosing the file contents between XML-style "source-file" tags, like this example:

<source-file filename="three-people.dat" project="My Project">
# Name Height Eye-colour
Groucho 5'7" Brown
Chico 5'8" Brown
Harpo 5'10" Blue
</source-file>

The "filename" attribute is the name the file will have in the project's working directory, and the "project" attribute names what project the file belongs to. In most simple cases you can leave out the project attribute and allow the wiki to use the default.

Image pages

Any file uploaded to an File page (an Image page, in older versions of MediaWiki) can be included in a project as a source file, and added to the project through the Special:ManageProject interface.

For instance, you might want to store a source file that will be called "test.jpg" at Image:ProjectName$test.jpg. (Including the project name and connecting "$" is not required, but is recommended in case the same filename arises in multiple projects.) On your project's ManageProject page, first enter the source file name (test.jpg) that will be used in the project, and in the Page field enter Image:ProjectName$test.jpg (or File:ProjectName$test.jpg), then click the "set" button to save the change. (If you follow the naming convention here, you can just accept WW's suggested name instead of typing in the Page field. If WW suggests something unexpected, it means that you already have a copy of the file in your project.)

Then the file can be uploaded by clicking on the provided link. (If the file extension is not allowed by the wiki, someone with access to the web server may need to change the wiki's configuration to allow it.)

Note that the file does not need to be an image or graphic to be uploaded to an Image: page. Large text files such as data sets that are too long to be stored on a regular wikipage, or that would make a wikipage disorganized or unnecessarily complicated, can be stored on File pages.

Source files in projects

A project needs to be able to find all its source files. They should all appear in the list of source files on the Special:ManageProject page for the project. When you add a new source file to a wiki page that shares the project's name, the WorkingWiki extension offers to add it to the project automatically. When you add source files by importing, using the "Import Files" link on the project's ManageProject page, WW adds them to the project automatically.

You can also add a file to a project from the Manage Project page before adding it to the wiki. Simply type the name of the file that you want to add under Source filename and accept (or change) the default location. WW will then provide you links to upload the missing file. You can see the Manage Project page associated with this page (click on the link on the left sidebar under "projects") for an example.

Source files can be anywhere on the wiki. You can add a file in any location to your project using the Manage Project page. If you place a source file intended for a specific project on some other page, you can also use the project attribute to tell WW which project it belongs to (preventing it from being used by other projects).

If you upload a file using MediaWiki's regular "Upload file" feature, it is not added to any projects automatically. You can add it to your project manually before or after uploading, or use the Import Files link on the Manage Projects page to combine the two steps (see above).

If you do need to add a file by adding the Source filename on the project's ManageProject page, you should make sure the location is right by checking the link on the ManageProject page afterward, because page names are sensitive to spelling, capitalization and spacing. The link should be blue, and if you have similarly named files, you might want to follow it.

Project files

Source files and files that are made from them are all project files, that is, files that belong to a project. Any project file can be included in a wiki page using the project-file tag, for example:

<project-file filename="population-growth.eps" project="Demographic Simulations"/>

or

<project-file filename="three-people.dat" project="My Project"/>

When it sees this tag on a wiki page, WorkingWiki will assemble the latest version of all the source files in the project's working directory, run make in case the project file needs updating, and display the up-to-date contents of the project file in place of the project-file tag.

Notice the "/" at the end of that tag. The project-file tag doesn't work without that closing slash.

Along with the contents of a project file, a "[log]" link is also displayed, which points to the output of the make command that produced the file, in case there are problems in the make process.

For more on how to use project-file tags, see How project files are displayed, below.

Project management

Projects are managed using the Special:ManageProject page. Every textual page that involves a project includes a link to that project's ManageProject page in the "projects" box on the sidebar. This page can also be reached by entering the project's name into the search field in the "projects" box.

This page provides controls for inspecting and changing the project. At the top are links to a listing of the current contents of its working directory, to the project's raw project description page, and to an export of the project, in the form of a .tar.gz file either containing all the project's source files or containing everything in the working directory, for working on the project away from the wiki. On the second line are a link to clear out the working directory for a clean start, one to sync all the source files into the working directory, and one pointing to a page for uploading files from your computer into the project.

Next down, the ManageProject page's list of source file definitions should include all the source files the project needs and the wiki pages where they are located. If the system isn't making the target files correctly, check this list to make sure it's complete and correct.

Beside each listing is a button to sync the file into the working directory (to give you fine control over the make operations) and one to remove the file from the working directory, from the project, and/or from the wiki altogether. The source file "set" form, below the list, allows you to add source files to the list, and to change the locations of existing ones. It's sometimes useful to use this form to add source files that aren't actually there yet, and then follow the links from the list to add them to their pages. When there are source files listed that aren't in the wiki yet, there is also a button provided that you can use to upload some or all of the missing files. If the sync button is greyed out, you are in a Manage Project page that was generated from a preview page: manual syncing doesn't work in preview sessions, for technical reasons. Instead, the source files are synced automatically each time you preview the page you're working on.

Below the list of source files is a control for making arbitrary targets. This can be used to remake a particular file conveniently, or to make a target like "all" that doesn't correspond to a file. If the make operation succeeds and a file exists with the target name, that file will be displayed.

Below that, there may also be lists of prerequisite projects and archived project file locations. These interfaces are very similar to the one for source files. Prerequisite projects are other projects whose files are used by make rules in this project, and archived project files are specially-treated target files that are automatically stored in the wiki so that their history can be tracked.

Makefiles

All the operations that WorkingWiki does to transform source files into target files are controlled by rules defined in makefiles. WorkingWiki includes makefile rules defining its behaviour for standard cases such as LaTeX documents. Wiki administrators can add additional makefiles to define rules that apply to all projects.

Makefiles take the form:

target(s): dependencies
	commands..
	commands...
target(s): dependencies
	commands...

Each project may also include one or more makefiles. They are included in a project just like any other source files. If the project includes a source file named "Makefile", "makefile", or "GNUMakefile", that file is read when running make in that project's working directory. The order of precedence for makefile rules is the project's makefile first, then any custom site makefiles installed by the system administrator, then WorkingWiki's default rules.

Note that lalashan's wikis have a rule in their site makefiles that includes all files whose name ends in ".mk" as well as the above makefiles. This allows you to add make rules easily by adding multiple .mk files to a project. These files are read just after the project's main makefile. (Currently only .mk files in the main project directory are read, and they are read in alphabetical order.)

Technical notes: The WorkingWiki makefiles are stored at resources/makefile-before and resources/makefile-after, in the WorkingWiki source code directory. They provide variable definitions and pattern rules, respectively, to be read before and after the projects' makefiles. Site-specific makefiles, if they exist, should be located at resources/site/makefile-before and resources/site/makefile-after. Additional site-specific makefiles can be placed in the resources/site directory; add an include directive in one of the standard site makefiles for each of the other makefiles. Makefile code should not refer to these directory paths explicitly: use $(RESOURCES) and $(SITE_RESOURCES).

Files in the resources directory, including the makefiles, can be viewed within the wiki using the GetProjectFile interface:

• makefile-before
• makefile-after
• site/makefile-before
• site/makefile-after

[Note up till June 11, 2010 there were only 2 makefiles, not 4.]

In the future we might be able to edit these files using the wiki interface: see Talk:WorkingWiki#Makefiles for details.

Importing and exporting projects

The ManageProject page provides "Export" links, which create a .tar.gz file containing a copy of the working directory containing all the project's source files.

The reverse operation — importing a project's files — is implemented by a custom uploading interface on the Special:ImportProject page, which is reached by the "Import project" link in the "projects" box in the sidebar on every page.

The ImportProject interface can also be used to create a wiki project by uploading an existing directory of files. It accepts files of type .tar.gz, .tgz, .tar, and .zip. It is not possible to upload the contents of a directory directly, so the directory needs to be archived into a single file of one of these types in order to upload.

Once the package is uploaded, the Special:ImportProjectFiles page appears, with a form to assign each file to a project file name and to the page where it should be stored.

Generally only source files should be uploaded in this way: all uploaded files are assumed to be source files by default. If other files are present in the package, just select the "Skip this one" option for those files. If the project includes archived project files, though, the ImportProjectFiles interface also supports uploading new versions of them, so that you can export the project, run your programs, and re-upload particular versions of the output files that you want to publish.

As alternatives to the full ImportProject interface, the ImportProjectFiles page can be reached directly, to upload individual files, in two ways. Each ManageProject page provides an "Import files" link above the source files; and when the list of source files includes files that aren't found on the wiki, ManageProject inserts an "upload missing files" button that produces an ImportProjectFiles page with its form fields pre-filled for those files.

If you are using a javascript-enabled browser, the filenames and destination pages will be filled in and updated to default values made from the project name and uploaded file name. They can be changed by hand. Both regular wiki pages and File pages can be specified, though you will be warned if you attempt to upload a binary file to a text page.

If there are more than 20 files, the ImportProjectFiles interface will be broken into multiple pages. Make sure all the files on a page are uploaded to your satisfaction before going to the next page. When the final page is completed, the temporary directory where the contents of the package are stored will be erased and no more uploading will be possible.

See WorkingWiki/Configuring Uploads for details on how to configure what file types Special:ImportProjectFiles prefers and accepts.

It should work seamlessly to export a project, work on it on your personal computer, and later return your changes to the wiki using the import page. If this fails, please report it as a bug. Be advised though that this will not warn you if someone else has made changes since the export, and those changes will simply be overwritten by yours. Check the relevant page histories (or maybe just the RecentChanges page) and proceed carefully. [Unfortunately, this cycle is no longer working since it is now exporting prerequisite projects along with the main one and ImportProject can only handle a single project. This will require some major changes in the code before it is fixed. Instead, after exporting and improving a project, bundle up its directory without the parent directory, .workingwiki directory, and other things in the export, and upload that bundle into ImportProject.]

How project files are displayed

One of the main functions of a wiki is to transform the wikitext of each page into HTML code to appear in the web browser, and WorkingWiki is responsible for making project files appear in HTML form. How it does this varies for different kinds of files. It converts LaTeX documents into HTML using makefile rules that invoke LaTeXML. Image files are displayed inline on the page as is, if they are compatible (PNG, GIF, JPG, SVG), or converted to PNG format using convert if needed (EPS, PS). HTML files are passed through as is, and files whose extension is .wikitext are parsed and displayed as wiki content. PDF and DVI files are represented by a link to the file, and other files are displayed as source listings using the syntax highlighter.

These default behaviours can be overriden by using a display attribute: for instance, to display a .tex file as source code rather than as its compiled output, you might want to write

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

The options for display are display="none" (don't display anything), display="source" (display the verbatim text of the file), display="link" (display a link to the file), or a target filename in the form display="filename" (the target file filename will be made and displayed in place of the source file).

The default display behaviours are equivalent to default display attributes: X.tex displays as X.latexml.xhtml, X.eps displays as X.png, X.pdf displays as "link", etc. There are corresponding make rules in WorkingWiki's internal makefile to make these targets.

The default display rules are the same for <source-file> and <project-file> tags, except that project-file tags don't substitute a different filename. The display attribute can be used on both source-file and project-file tags.

There is also an advanced htmldisplay attribute, for use when there's a need to specify alternative display content for plain HTML browers as opposed to those that accept XHTML+MathML. WorkingWiki does this alternative processing internally for LaTeX documents processed via LaTeXML: it probably isn't needed for anything else.

In conjunction with display="link", you can also use linktext="XXX YYY" to make XXX YYY be the text of the link. If linktext isn't specified, it defaults to the filename.

As an alternative to display="link", you can use the Special:GetProjectFile page to make more sophisticated links to project files (including source files). The link syntax is [[Special:GetProjectFile/project=Y/filename=X|link text]]. Special:GetProjectFile can be called with make=yes or make=no to control whether make is used when the link is followed, but this syntax does not support making the file at the time the page containing the link is displayed (see below).

In conjunction with display="source", you can specify lang="LLL" to specify what language to use for syntax highlighting, in case it doesn't guess correctly. For instance, if you are using some special file type that should be displayed as if it were a makefile, you could use lang="make". The language code is typically the same as the file extension for files of that language, and there are some extra values that are recognized such as "make".

Remaking

Default behaviour: By default, project files included by means of <project-file.../> tags are updated before displaying, using make. Files displayed as source code and image files displayed inline are remade (that is, make is called to update the file if needed) before inserting their content into the page; with display="link", the file is remade when inserting the link into the page, not when the link is followed; with display="none" it is remade, and with display="filename" the target specified by the display attribute is made instead of the one specified by the filename attribute.

The make attribute: To override these default behaviours, making at the time the page is displayed can be controlled explicitly by the make attribute: in the case <project-file ... make="yes"/>, the relevant target will be remade, and with make="no" it will not be remade.

The make attribute is only recognized for project-file tags, not for source-file tags, and make is not invoked when a source file is displayed, except in the display="filename" case.

Temporarily disable making: There are two ways to disable making, for instance while you are working on something that is depended on by various time-consuming targets and don't want to wait for them over and over before you're done editing. Placing the keyword __DISABLE_MAKE__ within the text of a wiki page instructs WorkingWiki to skip all make operations for project files located below the keyword on the page. The complementary keyword __ENABLE_MAKE__ can be used to re-enable making for subsequent parts of the page. You can also temporarily disable making for an entire page by adding "disable-make=true" to the query part of its URL.

Timeouts: WorkingWiki has a timeout feature when making a file. It times out after 3 minutes (unless your administrators have set a different time limit). In any case, you probably don't want to wait for more than a few seconds for your web page to refresh. Slow targets can be made in the background, using the background jobs feature.

The alternative links

Many project files are displayed with one or more links in the right margin, something like [log] or [log,pdf], formatted to look like the [edit] links that MediaWiki uses. By default, WorkingWiki displays a log link if it used make before displaying the project file, that is if it's a project-file tag without make=false, or a source-file tag with display=other-filename. The log link points to the file where WW stores the output of the make command for the project file. A pdf link appears when a .tex file is displayed as HTML or XHTML.

You can customize this behaviour in two ways. Change the target of a link by inserting an attribute such as pdflink="my-file.latex.pdf". If you want to change the list of links, use an altlinks attribute: altlinks="log,pdf,dvi" for instance, if you want to present a dvi version of your paper to users. That can then be customized by dvilink="my-file.dvi" or the like. If you just add to the altlinks list, a default link target is used, and if you just add dvilink or the like, the corresponding link is added to the altlinks list.

Special:GetProjectFile

The Special:GetProjectFile page is used internally by WorkingWiki to serve binary files from projects, such as images and pdf files, to display text files including log files, and to produce directory listings. It can also be invoked as the target of a wiki link to display a project file. For text files, it produces a source listing in a wiki page, and for images and other binary types it simply serves the file directly. WorkingWiki uses this URL to deliver the images embedded in the web pages, to serve pdf files, and to display the logfile of make's output.

The standard URL for this special page is, for instance,

http://somewhere/somewiki/index.php/Special:GetProjectFile?filename=X&project=Y&make=false

The variant format

http://somewhere/somewiki/index.php/Special:GetProjectFile/filename=X/project=Y/make=false

is also supported, to make it more convenient to use in handmade wiki links. So in a wiki page, you can either use an absolute link: [http://lalashan.mcmaster.ca/theobio/somewiki/index.php/Special:GetProjectFile?filename=X&project=Y&make=false here is the file] or a wiki-style link using the variant syntax: [[Special:GetProjectFile/filename=X/project=Y/make=false| here is the file]]. The variant syntax doesn't work if a filename or project name contains a slash.

Special:GetProjectFile runs make to update the file before displaying it, unless the make=false argument is included in the URL. In the make=false case, if the file requested is a source file, it is refreshed from the contents of the wiki before outputting it; any other file is displayed as it is found in the working directory.

The display argument can be used to direct it to show the file in various ways. The following values are accepted:

• display=download: send the file contents directly to the client, without embedding it in a wiki page. If there is an error, display the error message in a wiki page. This is used for pdf files, for instance.
• display=raw: the same as download except that if there is an error, an HTTP error page is sent. This is used for images embedded in wiki pages and latex documents.
• display=source: list the contents of the file as source code.
• display=image: the file is an image, and should be displayed in the wiki page. (This and some of the others are defaults for the appropriate file types, and are less useful for explicit use.)
• display=link: this is a binary file that can't be displayed in a wiki page, so just provide a link to download the file.
• display=html: the file contains html that should be displayed as is. In this case Special:GetProjectFile tries to guess whether it's a snippet of html (in which case displays within the wiki page) or a complete web page (in which case displays it using download).

There are a couple of other special-purpose arguments:

• resources=true: add this in place of a project name for one of the wiki's internal files. (It usually also works to just leave out the project and not add this, but it sometimes fails inside preview or background jobs.) For instance, to display one of the internal makefiles:

  http://lalashan.mcmaster.ca/theobio/projects/index.php?title=Special:GetProjectFile&filename=makefile-after&resources=true

• htmlfallback=true: when displaying a file whose name ends in .xhtml, this argument tells GetProjectFile to display the corresponding .html file instead for any browsers or users that can't safely receive XHTML. This is because there are compatibility problems between newer browsers that support equations rendered with MathML and older browsers that can't, which require us to provide two versions of certain HTML files. This feature allows us to construct a link like

Special:GetProjectFile/project=Multivariate_modeling/filename=multiv.standalone.xhtml/make=false/display=download/htmlfallback=true,

which provides a latex document (actually a Sweave document, in this case) as a standalone document that has equations as images for anonymous viewers and people without an up-to-date Firefox browser, and has the MathML equations for people who can receive them.

Any of the above arguments that accept true/false values also accept n, no, f, 0 and an empty value for false, and anything else for true.

Default project names

If a source-file or project-file element appears without a project attribute, its project name for the purpose of displaying it is by default the name of the page where it appears. If no project is found by that name, and the page is a subpage, the name of the parent page is also tried. A source-file without an explicit project name can be included by multiple projects.

The full system of defaults is a bit more complex than the above. See WorkingWiki/Defaults for the bloody details.

LaTeX document processing

WorkingWiki has general rules in its internal makefile to compile LaTeX documents to PDF form in the standard way, and also to make them into HTML for display in the wiki page. LaTeX-to-HTML conversion is done by an excellent third-party tool called LaTeXML. LaTeXML supports most LaTeX documents, though there are some exceptional constructions and packages that it doesn't handle. We have a LaTeXML Notes page, for sharing tips about using LaTeXML on the wikis.

WorkingWiki displays a .tex source file, by default, by running (for X.tex) make X.latexml.xhtml in the project working directory. That's for MathML users: to get the benefit of MathML output you have to select the "MathML if possible" option in your "Appearance" preferences, and use a compatible browser. To display in non-MathML cases it uses make X.latexml.html. The default rules should be sufficient.

Following the "pdf" link at the top right of the latexml content invokes Special:GetProjectFile to make and download X.pdf, also using WorkingWiki's default make rules. Here, too, the default rules should be sufficient. The "log" link points to the log resulting from making the LaTeXML output. The log from making the pdf file is presented if there are any problems making the pdf. Otherwise, it can be found in the working directory listing, via the ManageProject page.

The .pdf target for a .tex is compiled using latex. To use pdflatex, add pdflink="X.pdflatex.pdf" to your source-file tag's attributes (assuming your file is called X.tex). .latex.pdf and .xelatex.pdf targets are also available (though xelatex isn't currently installed on lalashan).

Our LaTeX Example demonstrates some useful features, like \marginnote for attaching comments within a document in progress.

Inline LaTeX

Inline LaTeX commands ($$...$$ and <latex>...</latex>) are translated into elements like <source-file filename="(something).tex-inline" standalone="yes">...</source-file> before processing. The standalone attribute causes the source-file to be assigned to a unique project by itself, so there isn't any confusion or overlap with other project files. The .tex-inline extension is processed like .tex but a little differently, suitable for a small snippet of latex rather than a whole document.

These LaTeX files are processed using the article.cls, amsmath.sty, amssymb.sty, and latexml.sty packages.

Archived project files

Generally a project-file tag on a wiki page is a placeholder, instructing the wiki software to display the current contents of the appropriate file in the project's working directory. However, there is also a feature to archive project files' contents on the wiki, so that you can track their changes and refer back to old versions of the files. When you mark a project-file location as archived, WorkingWiki will upload the file's contents to that location in the wiki every time it is changed at the end of a make operation.

In order to be updated when the working directory contents change, this location needs to be recorded in the project: this is done by adding the filename and page name to the list of archived project files on the project's ManageProject page.

An archived project file on a text page is simply a non-empty project-file element:

<project-file filename="X" project="P">
This is the most recent content of file X.
</project-file>

Once you add the archiving location to the project, this project-file element will be appended automatically to the wiki page if there is not already a project-file element for that file on that page (empty or otherwise). If there is one, it will be updated to include the current content of the file.

Project files can also be archived at Image: locations, by naming that page on the ManageProject page.

Changing the archived content in a project-file element or Image page on the wiki has no effect on the files in the working directory: your changes will just be overwritten the next time the file changes in the working directory. The flow of information is one-way, from working directory to archived location. This is like the one-way flow of source file contents, from source-file locations in the wiki to the files in the working directory, but in the opposite direction.

Note that archiving project files does not make the wiki more efficient by allowing display of stored project files instead of remaking. Project files are still remade in the working directory when needed, and displayed using the working copies. Make does nothing if a target doesn't need updating, and wiki pages are cached so that they don't need to be re-evaluated every time they are viewed, regardless of how the project files are stored. Archiving is only for the purpose of maintaining an archive.

Displaying old versions of source and project files

(Not yet implemented)

Dependencies between projects

Sometimes, a project needs to make use of files in another project. For this problem, we support inter-project dependencies.

In order to keep track of projects from multiple sources (from multiple wikis as well as from outside revision control systems), the WorkingWiki/ProjectEngine package assigns complex directory names to projects, making it inconvenient to mention them in makefile rules. In addition, during a preview or background make operation, some projects may be located in a special temporary location while others are left in their permanent places. In order to allow projects to find each other, we provide their locations to make in environment variables.

In order to be included as an environment variable, each project accessed by a given project needs to be listed as a prerequisite project on its ManageProject page. This accomplishes several things: the project's source files will be brought up to date with the contents stored in the wiki before any make operations; it will be included when the dependent project is exported; and its location will be provided to make in an environment variable. By default, the location of a project called XYZ is assigned to environment variable PROJECT_DIR_XYZ, which can be referred to in makefiles as $(PROJECT_DIR_XYZ) [note: that's the default for generic working wikis; on lalashan's wikis, project XYZ on wiki "theobio/PQR" is assigned to PROJECT_DIR_PQR_XYZ]. That variable name can be changed (for long, complex project names, or ones that contain punctuation that garbles the makefile) on the ManageProject page where the project is listed as a prerequisite.

The inter-project dependencies feature supports external projects, meaning those stored on other wikis, as well as git and svn repositories. (Currently the other wiki must be on the same host, but that is liable to change in the future.) To include these, instead of a simple project name, you have to use the Uniform Resource Identifier associated with the external project. These are similar to the URLs that refer to web pages. To register dependency on an external project, add its URI to the list of prerequisites. A project stored on a wiki whose base location is http://host.domain.com/location/wikiname, whose project name is PQR, is assigned the URI pe-ww:http://host.domain.com/location/wikiname:PQR. "pe-ww:" is the URI prefix for all WorkingWiki projects. so for instance, to use project R_Plotting_Routines here on lalashan's "projects" wiki, you would add pe-ww:http://lalashan.mcmaster.ca/theobio/projects:R_Plotting_Routines as a prerequisite project; then, using the variable name listed for the project, refer to $(PROJECT_DIR_projects_R_Plotting_Routines)/filename in your makefiles (or edit the variable name to something simpler).

[But actually we have added a shortcut form "pe-theobio:" for projects on lalashan's theobio family of WorkingWiki sites; so you can actually do the above by entering "pe-theobio:projects:R_Plotting_Routines". It will be expanded to the long form automatically.]

A Subversion project located at, say, svn://host.domain.com/location is referred to as pe-svn:svn://host.domain.com/location. A Git project is encoded the same way, but with the prefix pe-git:.

Once an external project's URI is listed as a prerequisite, that project will be loaded into a working directory that is made available to make jobs and export operations in the same ways as a local one. External projects can also be used directly: they do not have source files, but can be used with project-file tags and the ManageProject interface to do make and retrieve operations on their files.

The project description

WorkingWiki stores its project data in a special data structure on wiki pages in the ProjectDescription: namespace. There may be times when it's necessary to edit these directly, but that should be rare, and should be considered a bug to be reported. The description for each project X is stored on page ProjectDescription:X.

Any changes made to the project description data go into effect immediately, including being visible the next time the Special:ManageProject page for the project is loaded.

The syntax of the project description data is like this:

<project-description>
<project name="WorkingWiki/Documentation">
  <source-file filename="Makefile" page="WorkingWiki/Documentation"/>
  <source-file filename="A"/>
  <depends-on project="R_Plotting_Routines" project-dir-var="PROJECT_DIR_projects_R_Plotting_Routines"/>
  <option name="use-default-makefiles" value="1"/>
</project>
</project-description>

There is one source-file element for each source file. The page attribute may be omitted when the file is in an easily deduced location (while hand editing the project description, or by blanking the page field in the ManageProject page's "set" form before submitting), but it's simpler and causes less potential confusion to just include it. The source-file element tells the software where to find the content of the source file, to save into the working directory before any make operation. This element is not the same as the source-file tag that is used in wiki pages, and the two should not be confused.

The project-file element with appears attribute records where a project-file tag appears on a wiki page. This is used to mark those pages for re-parsing when the project files change, so the next viewer will see the latest version of the project file. There can be more than one of these elements for the same project file in the same project description: one for each page where the project file appears. As in the source-file case, this is entirely distinct from the project-file tag used in wiki pages, despite having the same name.

The project-file element with archived attribute is like the one with appears attribute, but signifies that the project file is archived on the page named by the archived attribute, not just displayed there.

The depends-on element records a prerequisite project, and every depends-on element in one project has a corresponding depended-on-by element in the other project involved. Its "project-dir-var" and "readonly" correspond to the variable name and "do not copy" settings on the ManageProject page.

The only option in use so far is use-default-makefiles, which of course corresponds to the "Use default makefiles" checkbox on the ManageProject page.

The project element inside the project-description element is pretty redundant, but makes rendering the project description easier when the ProjectDescription: page is viewed.

There is also a different format used to describe external projects:

<project-description>
<project name="pe-git:/usr/src/test-git-project">
  <external location="pe-git:/usr/src/test-git-project"/>
</project>
</project-description>

This description may include additional elements such as options and depends-on, if it is edited using ManageProject (e.g. http://host/wikiname/index.php/ManageProject?project=pe-git:/usr/src/test-git-project), but it can not contain source-file elements, since external projects' source files are not stored in the wiki.

Bug tracking

WorkingWiki bugs are tracked on the SourceForge site for the project. Please report bugs either by listing them there (Register/log in; Add New; Add Artifact) or by emailing the extension's author: worden.lee@gmail.com.

The best bug reports answer a few crucial questions, thoroughly and carefully:

• what did you do? what text did you change, what links did you click, on what page?
• what happened that seemed wrong?
• how can I reproduce this bad behaviour for myself?

If you want to, include why you think it went wrong, but please clearly separate facts from interpretations. See How to report bugs effectively for more suggestions, if you're interested. Thanks!