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 .
Keeping things tidy with redirects
Deleting pages
Limitations of the software
Scope
What can a Guide cover?
Similar projects
Licensing issues
To license or not to license?
Attachments (1)
- locales_example.png (6.3 KB) - added by 15 years ago.
Download all attachments as: .zip