Manual – OpenGuides

Context Navigation

This page is an attempt to hash out a new section for openguides.org that will serve to explain the steps necessary for installing and operating the OpenGuides software and running a site, from a general technical overview to issue of style, licensing, interoperation with other sites and so on. Please add comments and modify as you think is necessary until we as a whole feel happy with it, at which point I (Earle) can put it onto openguides.org.

Installing the software

There are two ways to install OpenGuides: either automatically, using CPAN.pm or CPANPLUS.pm, or manually. We'll examine each in turn.

Installing with CPAN.pm/CPANPLUS.pm

Installing manually

Databases

Postgres or MySQL or SQLite?

Indexes

Search::InvertedIndex? or Plucene?

cgi-wiki-setupdb

When you installed CGI::Wiki, it should have come with a Perl script called cgi-wiki-setupdb into [FIXME - where? different if installed with CPAN.pm?]. You will need to use this script to initialise your OpenGuides database. [FIXME perldoc ./cgi-wiki-setupdb]

Local installs

See the custom_lib_path option in wiki.conf [FIXME - More data please?]

Troubleshooting

Permissions

Look and feel

What should you name your Guide?

First appearances: the front page

Toolbar vs. no toolbar

Styling

The stylesheet

Custom templating

Other Guides and you

Content

Basic page editing

Developing structure: locales and categories

The locales system is a method of identifying two things:

where a thing is, and
where a thing is near.

It's designed to cope with the fact that locales are fuzzy things, and hard to precisely pin down.

The Locales field is exactly analogous to the Categories field - the only difference lies in the meaning. Apart from that, the two operate in exactly the same manner. By entering a locale name into the Locales field, you indicate that the page you're viewing is located in that locale. Simple. Any number of locales may be put into the field, as locales tend to overlap, meaning that a place may well be in several places at once. For an example, we're going to use Tottenham Court Road in London. Tottenham Court Road exists simultaneously in the locales West End, Bloomsbury and Fitzrovia. Other things may exist in one, two or also all three of those locales. Or none at all (in the case of pages that are not about places).

It can also be useful to create a hierarchy of locales. For example, in London, Locale Bloomsbury is part of Locale Central London. Other locales may be in Locale West London, Locale East London, and so on. These meta-locales are themselves in Category Locales, as are all locale pages. So by doing this, you can "dig down" from the most general to the most specific level.

Let's take a moment to clarify the notion of "locale". Another London example: Brick Lane. What is Brick Lane? Well, it's a road. But it also gives its name to a surrounding district. So Brick Lane the road is in Brick Lane the locale. In other words, the Brick Lane page has "Brick Lane" entered in its Locales field and Roads in its Categories field. Making fine distinctions like this allows us to increase the granularity of the information on an OpenGuides site, and make things easier to find.

Metadata 101

What is metadata?

Metadata is defined as data about data. In an OpenGuides context, this means data about the subject of the page.

When you create a new page, you'll be presented with a form containing a number of fields: [...]

Macros

@SEARCHBOX

Creates a search box.

@INDEX_LINK [Category|Locale] name

Creates a link to the basic list of every node in the category name.

@INDEX_LIST [Category|Locale] name

Similar to @INDEX_LINK but embedds the list into the current page.

@RSS url

Creates a list of up to ten of the most recent items from the RSS feed at url.

Administration

Protecting your wiki configuration

In a .htaccess file in your wiki's directory, or in your Apache configuration:

 <FilesMatch "^wiki.conf">
 order allow,deny
 deny from all
 </FilesMatch>

This will prevent any file whose name starts with wiki.conf from being readable by web visitors. Note that if the program you use to edit your config file has a different convention for naming backup copies (you do use an editor that makes backups, right?) - i.e., it doesn't append something to the name like ~ or .bak - then you will have to write a different pattern in the FilesMatch? directive, or the file will be readable to web users. For more on FilesMatch?, see http://httpd.apache.org/docs/mod/core.html#filesmatch .