Changes between Initial Version and Version 1 of Manual


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

Import from old wiki

Legend:

Unmodified
Added
Removed
Modified
  • Manual

    v1 v1  
     1This 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.
     2
     3
     4
     5== Installing the software ==
     6
     7
     8
     9There are two ways to install OpenGuides: either automatically, using CPAN.pm or CPANPLUS.pm, or manually. We'll examine each in turn.
     10
     11
     12
     13=== Installing with CPAN.pm/CPANPLUS.pm ===
     14
     15=== Installing manually ===
     16
     17=== Databases ===
     18
     19==== Postgres or MySQL or SQLite? ====
     20
     21=== Indexes ===
     22
     23==== Search::InvertedIndex or Plucene? ====
     24
     25=== cgi-wiki-setupdb ===
     26
     27
     28
     29When 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]
     30
     31
     32
     33=== Local installs ===
     34
     35
     36
     37
     38
     39See the custom_lib_path option in wiki.conf [FIXME - More data please?]
     40
     41
     42
     43=== Troubleshooting ===
     44
     45==== Permissions ====
     46
     47
     48
     49== Look and feel ==
     50
     51
     52
     53=== What should you name your Guide? ===
     54
     55=== First appearances: the front page ===
     56
     57==== Toolbar vs. no toolbar ====
     58
     59=== Styling ===
     60
     61==== The stylesheet ====
     62
     63==== Custom templating ====
     64
     65=== Other Guides and you ===
     66
     67
     68
     69== Content ==
     70
     71=== Basic page editing ===
     72
     73=== Developing structure: locales and categories ===
     74
     75
     76
     77The locales system is a method of identifying two things:
     78
     79
     80
     81* where a thing is, and
     82
     83* where a thing is near.
     84
     85It's designed to cope with the fact that locales are fuzzy things, and hard to precisely pin down.
     86
     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).
     88
     89http://openguides.org/img/locales_example.png
     90
     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.
     92
     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.
     94
     95=== Meta-data 101 ===
     96
     97What is ''meta-data''?
     98
     99Meta-data is [http://foldoc.doc.ic.ac.uk/foldoc/foldoc.cgi?query=metadata defined] as ''data about data''. In an OpenGuides context, this means data ''about'' the subject of the page.
     100
     101When you create a new page, you'll be presented with a form containing a number of fields: [...]
     102
     103=== Macros ===
     104
     105@SEARCHBOX
     106
     107Creates a search box.
     108
     109@INDEX_LINK [Category|Locale] ''name''
     110
     111Creates a link to the basic list of every node in the category ''name''.
     112
     113@INDEX_LIST [Category|Locale] ''name''
     114
     115Similar to @INDEX_LINK but embedds the list into the current page.
     116
     117@RSS ''url''
     118
     119Creates a list of up to ten of the most recent items from the RSS feed at ''url''.
     120
     121== Administration ==
     122
     123=== Keeping things tidy with redirects ===
     124
     125=== Deleting pages ===
     126
     127=== Limitations of the software ===
     128
     129== Scope ==
     130
     131=== What can a Guide cover? ===
     132
     133=== Similar projects ===
     134
     135== Licensing issues ==
     136
     137=== To license or not to license? ===