Changes between Initial Version and Version 1 of Manual

Nov 18, 2005, 2:58:33 PM (16 years ago)
Dominic Hargreaves

Import from old wiki


  • Manual

    v1 v1  
     1This page is an attempt to hash out a new section for 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
     5== Installing the software ==
     9There are two ways to install OpenGuides: either automatically, using or, or manually. We'll examine each in turn.
     13=== Installing with ===
     15=== Installing manually ===
     17=== Databases ===
     19==== Postgres or MySQL or SQLite? ====
     21=== Indexes ===
     23==== Search::InvertedIndex or Plucene? ====
     25=== cgi-wiki-setupdb ===
     29When you installed CGI::Wiki, it should have come with a Perl script called ''cgi-wiki-setupdb'' into [FIXME - where? different if installed with]. You will need to use this script to initialise your OpenGuides database. [FIXME perldoc ./cgi-wiki-setupdb]
     33=== Local installs ===
     39See the custom_lib_path option in wiki.conf [FIXME - More data please?]
     43=== Troubleshooting ===
     45==== Permissions ====
     49== Look and feel ==
     53=== What should you name your Guide? ===
     55=== First appearances: the front page ===
     57==== Toolbar vs. no toolbar ====
     59=== Styling ===
     61==== The stylesheet ====
     63==== Custom templating ====
     65=== Other Guides and you ===
     69== Content ==
     71=== Basic page editing ===
     73=== Developing structure: locales and categories ===
     77The locales system is a method of identifying two things:
     81* where a thing is, and
     83* where a thing is near.
     85It's designed to cope with the fact that locales are fuzzy things, and hard to precisely pin down.
     87The 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).
     91It 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.
     93Let'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.
     95=== Meta-data 101 ===
     97What is ''meta-data''?
     99Meta-data is [ defined] as ''data about data''. In an OpenGuides context, this means data ''about'' the subject of the page.
     101When you create a new page, you'll be presented with a form containing a number of fields: [...]
     103=== Macros ===
     107Creates a search box.
     109@INDEX_LINK [Category|Locale] ''name''
     111Creates a link to the basic list of every node in the category ''name''.
     113@INDEX_LIST [Category|Locale] ''name''
     115Similar to @INDEX_LINK but embedds the list into the current page.
     117@RSS ''url''
     119Creates a list of up to ten of the most recent items from the RSS feed at ''url''.
     121== Administration ==
     123=== Keeping things tidy with redirects ===
     125=== Deleting pages ===
     127=== Limitations of the software ===
     129== Scope ==
     131=== What can a Guide cover? ===
     133=== Similar projects ===
     135== Licensing issues ==
     137=== To license or not to license? ===