Tag: wiki

Worldbooking

I’ve been using TiddlyWiki for my wiki construction needs for a few weeks now. This post is about making a world book with it.

First Steps

Review my getting started instructions from the sharing wiki.

The first thing to do is always to get a blank TiddlyWiki file. I usually grab one from the TiddlyWiki site to be sure of having the latest, but backing up a local copy and cloning it would be reasonable also.

Next, move it to Dropbox or other storage location and rename appropriately. I’m going to using as an example a world of plant-based superpowers, so I called the file SuperPlants.html.

Open this file up in Firefox.

Configuration

Let’s give the file an identity that matches its name.

  1. click on the “control panel” link on the Getting Started tiddler, or click on the settings cog in the right hand panel. You should see a tiddler called “$:/ControlPanel”
  2. select the Info tab and Basics sub-tab.
  3. enter a title for the wiki. In my example, I called it “~SuperPlants” – the tilde character prefix prevents the wiki-link name from being rendered as a link.
  4. enter a sub-title. In my example, I wrote “a vegetative setting for superpowered adventures”
  5. in the “Default Tiddlers” box, type the names of pages you would like to be displayed when you first load or reload the page. In my example, I put in the following two lines:
    [[Plant World]]
    [[Plant Powers]]
    Note the double square brackets around these titles. Usual wiki syntax would omit the space call these pages “PlantWorld” and “PlantPowers”, but I like my pages to be real compound terms and those square brackets force linking to happen anyway.

You can also change the colour scheme, but the main thing is to click on the red save icon (the arrow pointing down into an open box) which will persist your changes.

Your Starting Pages

This world book will ultimately form a web, but it will start as a tree.

For each of the pages you wrote into the “Default Tiddlers” box, do the following:

  1. click on the “+” button
  2. type in the name of the page to be created. For example, Plant World. Note that you do not include the [[square brackets]] here
  3. type in the text for starting the page. Usually, this will include more links to other pages you want to write.
  4. click the tick to the right of the page title to save the page content.

The text for Plant World that I typed in was:

In the greenhouse world of the future, plants have mutated and grown at the expense of animal species - including humanity. Hubristic notions of the anthropocene have been washed away in a tide of chrophyll: the true extinction event was the scouring of the land and seas by new plants that thrived in the warm, carbon dioxide-rich atmosphere.

There are pockets of humanity still around:

* [[Mountain Men]] - hardy souls that climbed the highest peaks because there is still a treeline.
* [[Troglodytes]] - they took to the caves, because where there is no light plants cannot survive.
* [[Technocrats]] - sealed in domes and steel cities they fight to maintain the technology that defines humanity.
* [[Orbiteers]] - survivors of space colonies, living meagre lives in the airless wastes outside the warmed atmosphere.

Note that the different human survivor pockets are again enclosed in double square brackets.

Follow the Links, Make the World

Filling in the world book is as simple and as complicated as clicking on each link to create the page linked to, then typing out more text with links to new ideas.

Tips:

  • don’t try to do it all at once. If you have a large page to write, you may be better off writing a bit at a time and adding more ideas later. You can always come back and edit the page later by clicking on the pencil icon.
  • use page naming conventions you will remember. For example, either use wiki-link syntax (no spaces, embedded capitals to mark word boundaries) or normal title format for page titles. Don’t forget to enclose normal format titles in double square brackets.
  • use the “Recent” tab on the right to see which pages you’ve written lately to remind yourself of the names.
  • use the search box to find relevant pages. This does search the tiddler text as well as the titles.
  • look at the help on wiki text. There’s a link to the help with each edit form under the “wiki text” llink.

How I Am Using This Right Now

The SuperPlants example was just that: an example, incompletely worked through, but I am using exactly this kind of world book structure in the following projects at the moment:

  • Songs of Atlantis – the dungeon crawl setting for my boys
  • Song – building a world book for Song to capture the current state of it so I can update the manuscript to match.

… but I’ll be using it for lots of things.

Leave a Comment

Sharing wiki, part 2

I wrote last week that I couldn’t share a TWiki instance between machines. In the comments, Brian Enigma pointed me at TiddlyWiki*.

This tool is about as close as I can get to what I want:

  • I can share the data via a cloud drive
  • I can setup a distinct file for each cluster of data
  • bonus: I can view the wiki contents on any device I can install Firefox and the cloud drive onto**

Setting Up

The setup instructions for TiddlyWiki are pretty simple:

  1. install Firefox
  2. install the TiddlyFox plugin
  3. load the wiki file into Firefox

If this is the first time you’ve used TiddlyWiki you can download a blank file from the site, or open up an existing file such as this one: world-book.

Once it’s loaded up, go to the Control Panel icon (the cog) and look around for things to change.

  • name
  • subtitle
  • colour scheme

Workflow

The workflow for making a world book with TiddlyWiki is the same as for any wiki: make a root page and type in links to pages you want to create.

I will write more about using this particular tool for building up a world book another time. In the meantime, experiment with this file: world-book

Glitches

This has been going pretty well for me so far after a few hours of use, but I’ve tripped over a few issues.

  • editing colour schemes is fiddly.
  • synchronisation of the saved file content is seamless from the computer, but pulling it down onto the phone. Forcing the page to reload is not as easy as I would like either.
  • Dropbox supports access to previous versions of the file, but the whole file is versioned: there’s no reverting an individual wiki entry
  • linking to existing pages requires remembering the names of those pages. There are tools in the UI which help (in fact, more than in TWiki…) but there’s still a lot of error potential

Still, this is a usable little tool with lighter requirements and simpler setup. It won’t do for a collaborative wiki, but for individual data where there’s only one author but multiple authoring locations it seems pretty likely.

At least I don’t feel like I need to take six months off writing to develop DataFrame any more.

[*] which is a name I love just because of the tiddlywinks reference.

[**] I can do this on my phone, but not on my Kindle Fire since there’s no Firefox available on there (at least not through the Amazon app store).

Leave a Comment

Wiki, the Unsharing

I was hoping that this would be a triumphant post where I explained how to share a wiki installation between multiple computers, but I couldn’t make it work.

So this post is a series of markers on what I tried and where it failed.

I was operating on a TWiki instance I had running on my day job Mac.

Making Wiki Work Again

In my instructions for installing TWiki on Mac OS X, I noted that they are for versions 10.6 and 10.7. My day job Mac is now running v10.9, and the wiki didn’t work any more.

First of all, Apple removed control of web sharing in v10.8. To activate it again, download this plugin.

Unzip it and move it somewhere sensible (I put it in /Applications/Utilities) then run it. You will be asked whether to install it for all users or just the logged in user – for a single-user computer it doesn’t really matter which.

Then click on the big slider switch, and you should be back in business.

Secondly, TWiki uses RCS for versioning of the pages, but Mac OS X v10.9 doesn’t include RCS any more.

Fortunately, it is available through package managers like MacPorts and Homebrew.

  1. install the package manager of your choice. I use Homebrew because it doesn’t require sudo.
  2. install RCS, eg brew install rcs
  3. configure TWiki to use the newly installed RCS rather than the one which is now missing.

The Easy Bit: Making the Wiki Run on a Shared Drive

  1. copy the TWiki data – copied the entire twiki directory to the cloud drive. Important here to preserve permissions.
  2. pointed the web server directory at the cloud drive – made a symbolic link to point the existing TWiki install location at the cloud drive.
  3. modify cloud drive permissions – need to loosen permissions on the cloud drive to allow the web server to read it.

With this approach, you don’t even need to restart Apache. I was browsing and editing wiki pages on the original computer in short order.

The Hard Bit: Making the Wiki Run on a Different Computer

Again, I was operating on an existing TWiki installation on another Mac.

  1. wait for the cloud drive to sync – need the current TWiki data!
  2. repeat the same trick with pointing the web server directory at the cloud drive – again, used a symbolic link
  3. loosen the cloud drive permissions – again, need to allow the web server to access the cloud drive

This got me to the point where I could browse the wiki, but modifying it would not work. I ended with these classes of failures:

  • incompatible data – I couldn’t log in with the wiki user from the original machine.
  • permissions issues – Dropbox could not sync all the files because the permissions were too close for it to read them. This particularly applied to working files (session data, error messages). I could modify those permissions so that Dropbox would actually finish its sync, but any new files are created with the tighter permissions.

So, overall, an interesting experiment but not a good result.

What Next?

I still like wikis as tools for worldbuilding, but I need to share the wiki across multiple computers with inconstant network access which means I need to find a different wiki implementation than TWiki, which makes me a little sad.

Or I may actually have to write DataFrame.

2 Responses

Sharing Wiki, part 1

After last week’s post, Making Wiki, you may have a Twiki installation on your computer. But what if you have more than one computer and you want to use the wiki on all of them?

This is something I am still working on, especially since one of my machines has lost its wiki install after an OS upgrade.

Publish

Let’s look at how you are accessing the wiki: through a web browser, pointing at localhost. “localhost” is the shortcut address for “the machine this application is running on.”

The most reliable way of sharing the wiki between machines is to have one machine host the wiki, then others on the network access it by entering the address of the hosting machine into a web browser.

So if I had a machine ithaqua which was hosting the wiki, on another machine I would navigate to “http://ithaqua/twiki/bin/view/Main”. Or, if I don’t have name propagation setup, I might need to enter the IP address of ithaqua instead.

This method only works if the accessing machine can access the hosting machine, which is only likely be true when they are on the same network*. The accessing machine also needs to have network access when it is reading the wiki contents. Since much of the time I would be accessing the wiki is on the bus when I have no network access, I don’t use this solution.

Share

The second way to share the wiki is to share the wiki data files.

Two approaches are viable here: putting the files into a revision control system, and using a cloud drive to backup the files.

Revision Control

Revision control systems are tools to keep a history of a group of files. They are used extensively in software development, but they are relevant to any task where many files change frequently. There are many such tools, but the one which is preferred for this application is git**.

TWiki has a plugin for storing its pages in git. Using git is preferable over other systems because it automates so much of the merge drama.

git needs a repository to hold the page store in, and this could either be on the host machine or on a separate server somewhere.

At this point I would usually start in on instructions about this approach, but I have had very poor luck in getting it to work. It seems to be a particular problem with version matching the git installation on one machine with the git installation on another. If you can get it working then it would be largely seamless, and it would allow editing offline.

Cloud Drive

What I think is the most likely approach is to modify the wiki config to store its data on a cloud drive, such as Dropbox or Google Drive. In this case I suspect there are some permissions issues to address (ie the web server must be given write access to the user’s data directory) but this seems likely to be easier to set up than git.

However, this portion is still a work in progress since, as I mentioned at the top, I only have one machine with a working TWiki install on it, and that’s the one without most of the data (the data is safe).

Which Is Best?

Each approach has its pros and cons.

Publishing the TWiki from one central machine using the web server is the best for ensuring wiki integrity. Indeed, with more than one user I would say that it’s the only viable option because it’s the only way to be sure of handling editing conflicts. This approach utterly fails when you consider network visibility and offline editing.

My heart tells me to use the git approach, especially since I have the benefit of a public server I can use as a repository, but I have not been able to set it up successfully on either machine, so I can’t recommend it.

Which leaves the use of a cloud drive, which won’t handle merge conflicts as well as git would but has the benefit of using network storage that is already configured.

Now I just have to get both wikis working at the same time!

[*] this is less of a concern if the host is on the public internet, although that introduces many other challenges.

[**] I admire Linus Torvalds immensely, but I really dislike this name.

Leave a Comment

Making Wiki

This post is about installing TWiki on OS X. It’s a pretty technical post, and rather longer than usual, but that is the price for accurate information.

These notes were tested on versions 10.6 and 10.7.

Why?

Wikis are great places to put research notes, and to make connected networks of pages on closely related topics. If you’re writing a novel, a wiki on the subject can turn into a comprehensive encyclopaedia or world book for your story.

You can create a wiki instance for your topic in cloud services like Wikia, but the information is going to be public there. So, you might find a wiki installed on your own computer may be helpful*.

Why TWiki?

TWiki is a lightweight wiki which is nonetheless powerful and flexible. There are many options for a wiki, but for personal use TWiki** has the following benefits:

  • file-based – many other wikis use a database to store the pages, which is one more layer of complexity that I at least don’t want to deal with on a day to day basis.
  • performs well – I used to recommend Kwiki because it was trivial to setup, but it was both much slower and lacked the features of TWiki. (Kwiki doesn’t seem to be maintained any more, anyway)
  • active – TWiki has an active community, so the software is still being updated. There are lots of options for additional feature modules if you want them.

So, that’s why you might want to install a wiki. On to what you need to install TWiki in particular.

Preqrequisites

You’re going to be doing some command line stuff, and some administrator stuff. You need to know –

  1. how to access Terminal, and how to type commands accurately. Command-line commands are precise and often rely on specific punctuation.
  2. what the admin password is on your machine (what you type when you do system updates)
  3. how to use a text editor – vim and emacs are powerful but we’re not doing anything complicated here so I’ll give the key presses for nano because it’s easy to navigate. If there is another text editor you feel comfortable with then feel free to use that instead.

These notes (which I first posted on Facebook, but I can’t find them anymore there) are effectively a targetted extract from these installation notes:

The changes should only affect the local web server on your Mac, but you’ll be using sudo on the command line which is a powerful tool: be sure you are typing commands correctly.

One last caveat: check the locations and contents of things. As noted in the header, these are notes on OS X 10.6 and 10.7 – older or newer versions may have things in different locations, and obviously other OSs will have things in completely different places***.

Command Line Commands

In these instructions you’re going to be using the command line. Commands you type are presented like this –

$> cd /tmp

… which means to type “cd /tmp” and then hit return.

Instructions

  1. turn on web server
    • open System Preferences
    • select “Sharing” (last icon on the “Internet & Wireless” line)
    • make sure the “Web Sharing” checkbox is ticked.
    • let’s just check that worked:
      1. open a web browser
      2. type http://localhost in the address field
      3. you should see a page. Default may be just “It works!”.
  2. download package from twiki.org
    1. you can enter your contact details or choose to skip the form
    2. download the “tgz” bundle
    3. expectation is that it will turn up in your Downloads directory
    4. eg Downloads/TWiki-6.0.0.tgz
  3. open Terminal – it’s in /Applications/Utilities, or type Cmd+Space to bring up Spotlight search and type “terminal”
  4. unpack the Twiki bundle in a sensible place. Let’s use /tmp
    $> cd /tmp
    $> tar -zxvf ~/Downloads/TWiki-6.0.0.tgz
    You should see lots of files being unpacked onto your system.
    $> ls
    You should see a directory called “twiki”
  5. move to web server directory
    You don’t want to run Twiki from /tmp, so we’re going to put it with the web server.
    $> cd /Library/WebServer/Documents
    $> ls
    You should see a few files including “index.html.en”.
    $> sudo mv /tmp/twiki .That ‘.’ on the end of the line means “here”, the current working directory. The “sudo” command will ask for your admin password.
  6. configure Twiki
    • fix directory permissions
      $> sudo chown -R www:www twiki
    • create Twiki config file
      $> cd twiki/bin
      $> sudo cp LocalLib.cfg.txt LocalLib.cfg
      $> sudo nano LocalLib.cfg
      Look for the line which starts “$twikiLibPath” and change it to read –
      $twikiLibPath = "/Library/WebServer/Documents/twiki/lib";
      Then type Ctrl+X, Y, and hit return to confirm the filename.
  7. configure web server
    TWiki is set up, but we need to tell the web server to load TWiki when asked to.First, get the config we need.

    • visit this page:
      http://twiki.org/cgi-bin/view/TWiki/ApacheConfigGenerator
    • enter the following value in “Full file path to your twiki root directory” –
      /Library/WebServer/Documents/twiki
    • click “No PHP installed” on the “Prevent execution of attached files as PHP scripts” radio button
    • click “Update config file”
    • click “Highlight text”, then copy (Cmd+C)
    • Now, put the configuration somewhere the web server will find it.
      $> cd /etc/apache2
      $> sudo nano other/twiki.conf
      Paste the config text (Cmd+V)
      Save and exit: type Ctrl+X, Y, return.
      $> ls other
      You should see a file “twiki.conf”, amongst others.
    • Now we need to test the config, and restart the web server.$> /usr/sbin/apachectl configtest

      You may see a warning “Could not reliably determine the server’s fully qualified domain name”, but just ignore that. Fix any other errors though.

      $> sudo /usr/sbin/apachectl restart

      TWiki should now load

    • even though we’re not quite done with config, let’s test that TWiki is there. Put this address into a web browser –
      http://localhost/twiki/
      You should see “Welcome to TWiki” and some links.
  8. configure TWiki
    • in a web browser, go to: http://localhost/twiki/bin/configure
    • enter and confirm a password for administration of the TWiki
      • note: this is separate from your Mac OS password. Use something else.
    • click “next” button
    • click “next” on the following page too.
      • you may see some warnings in “General path settings” and it is worth reviewing the guesses that the TWiki installer makes, but it guesses right in my experience.
    • click “Save”
      That’s the initial config. There are still a couple of things to fix up.
    • enter the TWiki admin password you just created.
    • click on “Store settings”, which will probably have errors
      • where it says “Error: /bin/grep was not found on your path”, add “/usr” onto the front of the text field.
      • there are two of these grep paths. Don’t touch any of the other parts of the command string.
    • click next
    • click Save
    • click “go to twiki front page”
  9. setup Twiki user
    Nearly there!

    • your Twiki install is functional, but in order to create pages you need to create a Twiki user.
    • click “Register” next to the “Twiki users” control
    • fill in the form. TWiki names are usually in the form “FirstnameLastname”
    • hit Submit
    • click on your WikiName link to go to your profile page.

Now you can go ahead and start creating pages:

  • type a wiki topic into the Jump field
  • create a topic home page
  • type in wiki links for things you want to turn into new pages, then click on them in the finished page.

[*] I will be talking about sharing wikis across multiple computers in a later post.

[**] and indeed Foswiki, which I had somehow missed and which is the spiritual successor to TWiki.

[***] Linux I might be able to help with depending on the distro; for Windows you’re on your own.

Leave a Comment

Wikis: building a world book

an icy branch

an icy branch

This is part of a continuing series about wikis and how they are useful to writers.

World books

A world book is the description of the setting for a story which a writer creates during the writing process. It could be a literal book, some journal or sketchbook containing notes and drawings. That still works in this modern age, but finding information in a hand-written document like that is going to be a challenge.

Wikis as world books

Wikis are editable web pages with easily created links to new content, so building a world book with one is conceptually simple:

  1. make a page for a subject in your world
  2. write some things down about it
  3. make links for subjects you want to make new pages about
    • people
    • locations
    • artifacts
  4. save the page
  5. click on a link which has no content yet – the wiki will create a new page for it
  6. go to step 2

Once the pages start to accrete, you will quickly find rich details emerging from the interaction of the subject pages.

A public demonstration of this kind of world book creation is the Encyclopædia Morningtonia, a collaboratively created exploration of the lore and personalities of Mornington Crescent.

Read the book

The most important thing about any world book is that it should be read and updated. It’s not a static document, but a record of your explorations of the world. Reading it will remind you what’s cool about your world, and spark ideas for stories and more details.

Tips and tricks

  • create a sub-wiki for the world you’re documenting – the wiki tool I use is Twiki (for reasons to be explored in a later post) and you can create new webs, although the same concept can be applied in other wiki tools too. Isolating a work’s wiki means isolating its name space, so that Amos Fosdyke in your mining drama won’t be confused with Amos Fosdyke, the romantic lead in your Mornington Crescent tournament erotica.
  • use Recent Changes – this is a collection of the pages that have changed most recently. Important memory cues include when and in what order things happened, so seeing which pages were written together may provide ideas for more things to put into your world.
  • look for incomplete links – wikis will often include a search for links which do not have a page to point at. Use those incomplete links to see where more details may be required.
  • use tags and labels – most wikis have a labelling feature akin to tags (tags being free-form text labels). Use these to mark pages as belonging to different categories, eg flora, fauna, locations, groups and group memberships.
  • write index pages – tagging will get you a fair way in grouping your pages, but a useful tool to structure your reading is to make index pages: lists of links which collect in a structured way related subjects.
    For example, you might have an index for all the characters who support the theme of loss in your story, or a chronological list of locations as they are to be used in your story.

Where things break down

Wikis have two primary failure modes:

  1. searchability – adding content to wikis is very easy, and you can quickly end up with an unnavigable mass of pages. This is why so many of the tips I mention above are to do with applying structure to the information, and encouraging grooming of the content. Search features get you some of the way, but having multiple routes of entry and navigation around the content will help you make use of it so much more effectively.
  2. duplication and linking to the wrong thing – when you’re writing a page, it can be very easy to make an error in a link name. “What was the name of the MC’s father?” you might ask yourself, and thus end up with two pages with different names containing the same content. Fixing this kind of duplication is one of the reasons it is important to keep reading the world book even while writing more of it so you can spot these inconsistencies early. Tagging and reviewing recent changes will help too.

In addition to those primary modes, renaming pages can present problems – sometimes a character’s name will change, for example. More powerful wikis support name changes of pages pretty well, but those wikis are also the ones that are hardest to set up in the first place.

Wikis really are very useful though, and they’re worth playing with just to see what they can do for you.

Leave a Comment