WorkingWiki/Tips and Tricks
From projects
A forum for sharing helpful ways of getting WorkingWiki to do what you want. Please edit at will.
Contents |
LaTeX files
For tips about using LaTeX with WorkingWiki, see the Latex tricks page.
How to use multiple makefiles
WorkingWiki out of the box just emulates the standard behavior of GNU Make: if there is a single makefile in your project directory, called "GNUmakefile", "makefile" or "Makefile" (in that order), it uses it along with WorkingWiki's general rules. So the straightforward way to write make rules for your project is to put them in "Makefile" (or one of the other 2 filenames, if you prefer).
But it may be easier to make several small makefiles, for instance so you can locate make rules in the same parts of the wiki as the files they affect.
One way to do this is to put an include directive in "Makefile":
include Makefile.*
for instance. If you put this in your main makefile, it will read all the rules in files whose name starts with "Makefile.".
The lalashan wikis do this for you, so you don't have to: all source files whose names end in ".mk" are read in by the site-wide makefile. So you can just put make rules into as many ".mk" files as you want.
It's All Text, and keyboard shortcuts
Use It's All Text to edit the wiki pages in your favorite editor.
It's All Text may work more smoothly if you get in the habit of previewing pages (you can use Alt-Shift-P) immediately after editing (with Alt-Shift-E). This brings you to the "submit" version of the page; once there, you can preview again, and resume editing in the same edit window. If you don't preview first, your edit window will open on the "edit" version of the page; after previewing, you can get back there with the back arrow to keep using the same edit window. The "edit" and "submit" look different to IAT, and saving to one will not update the other. You can save to the wiki with (Alt-Shift-S); afterwards remember to edit and preview if you want to keep using your "submit" edit window.
Note that firefox does not get your edits until you save in your editor, and then wait up to a couple of seconds (you will see your edit window turn yellow). It is possible to send your edits to the wiki before It's All Text has sent them to firefox. This is not what you want, so look for the yellow flash, or make sure not to be too fast.
Emacs mode comments
The emacs editor decides what editing mode to use, i.e. what programming language is in use in a file, in two ways: by looking at the file's extension, and by looking for a special comment in the first line of the file. Since It's All Text doesn't generally open a wiki page under a filename that matches one of the source files within or even the name of the page, it's useful to put a comment to control the mode. It doesn't have to be part of a source-file — for instance, I have a page that begins like this:
<!-- -*- bibtex -*- --> This is my general-purpose bibliographic database. This file is made from my [[master.bib]] by removing + signs from the keys because LaTeXML doesn't work with + signs in there. — [[User:WuLi|WuLi]] 20:59, 14 May 2009 (UTC) * note the problem with + signs is fixed now — [[User:WuLi|WuLi]] 21:14, 27 Aug 2009 (UTC) <source-file filename="master-noplus.bib"> ...
Redoing actions on Special:ManageProject
On the Special:ManageProject page, when you do an operation on the project by pressing a button (sync, add, make, etc.), the Special:ManageProject page is reloaded with an action request added to its URL, which causes it to do the action. So reloading the page causes it to redo the action. If you want to reload the page without redoing whatever action, you can go to the 'neutral' version of the page by clicking the project name in the sidebar, or the 'special' tab at the top.
Renaming
Renaming a project requires going under the hood a little.
- First rename the project description page. If you are renaming project X to project Y, you need to rename the wiki page ProjectDescription:X to ProjectDescription:Y. You can get to the ProjectDescription page by following the "Project description" link at the top of its project management page.
- Then edit the ProjectDescription page, changing
<project name="X">to<project name="Y">. - Then you need to edit all the
source-fileandproject-filetags belonging to the project that are in regular wiki pages, changingproject="X"toproject="Y".
A lot of times, when you rename a wiki page with project files on it, the page is associated with a project that shares its name. So you may want to rename the project (following the above steps) at the same time that you rename the page. But additionally:
- For any source files located on the moving page, change their locations in the project description, from the old page name to the new page name, either by using the 'set' form on the ManageProject page for the project, or while editing the ProjectDescription page directly. If you edit directly, change
page="P"topage="Q"wherever it appears (if you are renaming page P to Q). If you findarchived="P"in there, change that to Q as well.appearsattributes can be ignored.
Uploading and memory limits
Special:ImportProjectFiles can crash when the files to upload overflow its available memory. When this happens you see a blank white page instead of the upload results. (I'd like to catch this error, so it will at least tell you what went wrong, but there may be no good way. –LW) You can work around this situation by using your browser's Back button to go back to the submission form, and click 'Skip this one' on some of the files. When you've successfully submitted some files, you can re-enable some of the others and continue. (This may fail for image files in some cases, in which case you have to go back to the beginning...)
- If a file is just plain too big to upload to a text page, you can often upload it to an image page successfully.
The project sidebar
If a page is connected to a project but doesn't have actual project files on it, you might want the project to appear in the sidebar. You can do this by placing a tag like <project-file project="My Project Name" filename="nofile" display="none" make="false"/> on your page. The filename attribute is required, but it doesn't matter what filename you use because it's ignored (nofile has no special meaning above). I don't recommend using filename="", because it could cause trouble if you accidentally let WW try to do some operation involving the filename.
Advanced makefile debugging
I'm facing a weird situation where my project's makefiles work as intended when I export them and run them by hand, but not in the wiki. So while I'm trying to figure out what's going on, I think I'll leave some notes here for future voyagers.
-
make -dis sometimes useful - at least it tells you what rules it's finding and which it decides to use. But there's a lot it doesn't do, like tell you why it's considering some rules and not others. - This seems like an interesting resource, with some creative tricks for diagnosing what a makefile thinks it's doing.
- Somewhere on the internet I saw mention of a "makedebug" utility that's like a make debugger. But now I'm having trouble finding it.
