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
Postgres or MySQL or SQLite?
Search::InvertedIndex? or Plucene?
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]
See the custom_lib_path option in wiki.conf [FIXME - More data please?]
Look and feel
What should you name your Guide?
First appearances: the front page
Toolbar vs. no toolbar
Other Guides and you
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.
What is metadata?
When you create a new page, you'll be presented with a form containing a number of fields: [...]
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.
Creates a list of up to ten of the most recent items from the RSS feed at url.
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 .