Author: kake Date: 2008-06-21 17:55:10 +0100 (Sat, 21 Jun 2008) New Revision: 1169

Added: branches/new-install-process/SETUP Modified: branches/new-install-process/INSTALL Log: Documentation updates that I forgot to commit (ta Aidy).

Modified: branches/new-install-process/INSTALL =================================================================== --- branches/new-install-process/INSTALL 2008-06-16 01:31:05 UTC (rev 1168) +++ branches/new-install-process/INSTALL 2008-06-21 16:55:10 UTC (rev 1169) @@ -1,403 +1,42 @@ OpenGuides installation instructions ====================================

+OpenGuides installation has two steps - installing the modules, and setting +up a Guide. Module installation is described in this file, and setting up +a Guide is described in SETUP.

-If while following the instructions below or while trying to use your -OpenGuides install you see an error that you don't understand, please -consult the TROUBLESHOOTING file.

-For details about installing multiple OpenGuides sites on a single -server, or installing OpenGuides into a directory that isn't where -your system Perl library is, see further down this file. +* Basic installation of modules

-* Basic installation +The OpenGuides distribution _should_ be installable with CPAN.pm or +CPANPLUS.pm - i.e., the CPAN shell - and this is probably the simplest +way to do it unless you already know you prefer manual installation.

+If you do prefer manual installation, then: + Unpack the distribution (using for example 'tar' or 'WinZip'), and set -your working directory to be the top level of the distribution. +your working directory (using for example 'cd') to be the top level of +the distribution.

-If you have an existing "wiki.conf" configuration file and you wish -to keep using the values in that, copy it to this directory. - Now execute the following commands:

-perl Build.PL -perl Build -perl Build test -perl Build install + perl Build.PL + perl Build + perl Build test

-The very first of these commands asks a number of questions regarding -the installation. +These will prepare your system for installation of the modules, and run some +tests to make sure that everything is OK. If everything is not OK, then please +report a bug. If everything is OK, i.e. all the tests report success, then

+ perl Build install

- "Skip OpenGuides configuration?" +should install the modules for you. If you get error messages saying +you don't have the correct permissions, then you need to do something +along the lines of 'sudo perl Build install', or install the modules +in a directory that you do have permission to write to (see below), or +ask your sysadmin to do the installation for you.

-Answer "n" to this question unless you really know what you're doing. -It's mainly there for developers. (If you already have a configuration -file, and wish to use it without the build script asking you this -question, run Build.PL with the option --force. This will also skip -the "Continue with install?" question.)

- - "What type of database do you want the site to run on?" - -Answer "postgres", "mysql", or "sqlite". - - - "What's the name of the database that this site runs on?" - "...the database user that can access that database?" - "...the password that they use to access the database?" - -You should create (or ask your ISP/sysadmin to create) a database -specifically for the use of OpenGuides. If you have more than one -OpenGuides installation, for example if you run guides for more than -one city, each installation will need its own database. - - - "...the machine that the database is hosted on? (blank if local" - -If the database is running on a local machine with username/password -authentication then just press RETURN to skip this question. If it -is running on a local machine with IDENT authentication then you may -need to answer "localhost" to this question. If it is running on a -remote machine then enter the full hostname of that machine. - - - "What do you want the script to be called?" - -The default is for the main script to be called "wiki.cgi", but -you may prefer to name it after your city - "leeds-guide.cgi" for -example. Note that your webserver may be configured to only allow -execution of scripts ending in, for example, ".cgi" - - - "What directory should I install it in?" - -You need to pick a directory for the OpenGuides software to be -installed in. This must be one known to the webserver as containing -CGI scripts. You will need to have write permission on this directory -when you come to run "perl Build install"; unless this is a private -directory belonging to you then this might require an 'su' or 'sudo' -to root under Unix. - - - "What directory should I install the templates in?" - "Where should I look for custom templates?" - -Normally these will be in the install directory, but they can be anywhere. -Custom templates are intended to be user-modified, so you might want to -put them somewhere in /etc. - - - "What URL does the install directory map to?" - -Give the full address needed to access the installation directory with -a web browser - for example http://london.openguides.org/ - - - "Do you want me to munge a custom lib path into the scripts?" - -If you have installed some or all of the required Perl modules (or indeed -the OpenGuides modules themselves) into a private directory, you will -need to tell the scripts where to find these modules. Enter the paths -to search here just as you would enter them in a 'use lib qw( ... );' -in a Perl script. - - - "Do you want to use Plucene for searching?" - -This question is no longer asked, but documentation here is retained for -the benefit of people upgrading. - -If you are changing to Plucene from Search::InvertedIndex, you will -need to do two things: - - either delete your old indexes (they're just files in the index - directory) or use a different index directory - - reindex your entire wiki (see reindex.pl in the examples/ - directory of this distribution) - - - "What directory can I use to store indexes in for searching?" - -You need a directory to store files used as indexes for the site. The -user that your script will run as will need write permission on this -directory. Under some webserver configurations this might be a -dedicated user - 'nobody' or 'www-data' for example, but for many -multi-user systems this will just be yourself. - - - "Do you want to enable page deletion?" - "Please specify a password for the site admin." - -The default is to disable page deletion. If you choose to enable the -page deletion mechanism then you will need to add a password to your -wiki.conf by answering the question above or manually using a line such as - admin_pass = putyourpasswordhere -Users who know this password will be able to delete unwanted pages - -along with all their history - from your wiki. -*** USE WITH CAUTION. DELETED PAGES CANNOT BE RECOVERED. *** - - - "What's the URL of the site's stylesheet?" - -Supplying an answer to this question is optional. There are example -stylesheets in the examples/ directory - note that these will not be -automatically installed. - - - "What's the wiki called?" - -This is a title which will appear at the top of every page. If you have -more than one OpenGuides installation at the same site then each should -have a unique name, since this name is used to manage user preferences. - - - "Do you want the navigation bar included on the home page?" - -Answer "y" or "n". - - - "Do you want the ten most recent changes included on the home page?" - -Answer "y" or "n". - - - "Do you want the Random Page link to avoid returning a locale page? - "Do you want the Random Page link to avoid returning a category page? - -Answer "y" or "n". The defaults are "n", which means that Random Page is as -likely to return a category or locale page as anything else. If the category -and locale pages on your Guide are generally just lists of things in that -category/locale, you probably want to pick "y" here. If, on the other hand, -your category/locale pages generally have substantial content of their own, -you may prefer to choose "n". - - - "Do you want the content to appear above the navbar in the HTML?" - -Answer "y" or "n". The default is "n", for reasons of backwards -compatibility with existing stylesheets, but the recommended answer is -"y", as this will help search engines to find the most relevant parts -of your pages. - - - "What should the home page of the wiki be called?" - "How would you describe the wiki?" - -Self-explanatory. - - - "What city is the wiki based in?" - "What country is the wiki based in?" - -If the wiki will not be city or country specific you can leave either or -both of these blank. - - - "Contact email address for the wiki admin?" - -Self explanatory. - - - "What language will the site be in? (Please give an ISO language code.)" - -eg "en" for English, "it" for Italian. -See http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt - - - "What's the name of the node or page to use for the text formatting - rules link?" - "What URL do you want to use for the text formatting rules" - -From 0.19, OpenGuides allows users to choose whether or not to have a -permanent link to the text formatting rules node or page in their navbar. -You need to put the name of that node or URL in here for it to work, though. -You might want to call the node "Text Formatting Examples", -"Text Formatting Rules", "House Style" or whatever. - -Note that these the latter question will override the former, so if you -want to use a local node make sure to leave the latter blank. - - "Make node titles link to node backlinks (C2 style)?" - -This refers to turning titles into links which bring up a list of referring -pages. This was the convention with older wikis ("C2" refers to the original -wiki at http://c2.com/cgi/wiki), but is not intuitive. - - "Do you have a Google Maps API key to use with this guide?" - -If you want Google Maps integration, you need to register with Google to get -an API key. Visit http://www.google.com/apis/maps/signup.html and follow the -instructions. Paste the great long string into the console window where you -are installing. See README.GMAPS for more information. - - "What is the longitude of the centre point of a map to draw for your guide?" - "What is the latitude of the centre point of a map to draw for your guide?" - -It's probably a good idea to pick some notionally central point for your -guide. For example, Carfax for Oxford, Charing Cross for London. As a -convenience, you may paste in a Google Maps URL for the centre longitude -question and the (long,lat) will be parsed out from the URL. - - "What default zoom level shall we use for Google Maps?" - "What default zoom level shall we use for Google Maps in the search results?" - -The defaults are probably appropriate in most cases. - - "Would you like to display a Google Map on every node that has geodata?" - -Answer "y" or "n". Note that an answer of "y" will only take effect if you've -supplied a Google Maps API key above. Note further that users can choose to -turn this off in their preferences. - - "Forcibly treat stored lat/long data as if they used the WGS84 ellipsoid?" - -Default this answer if you don't know what it means. - - "Do you have a Google Analytics key to use with this guide?" - -If you'd like to use Google Analytics to track the traffic on your guide, -visit http://www.google.com/analytics/ to sign up for a key. The answer to -this question is the string in quotes in the HTML fragment they ask you to -paste into your HTML, something along the lines of _uacct = "UA-1234567-1" -- it's the UA-1234567-1 part that you need to put in here. If you've -forgotten your key, go to Analytics Settings, click "Edit" under Settings, -then click "Check Status" in the top right-hand corner of the box with grey -stripes. - - - "What licence will you use for the guide?" - -We strongly recommend that you think at the outset about the licence your -guide will use, for maximum usefulness. In particular for a guide that will -be on the OpenGuides network, we recommend the -"Creative Commons Attribution-ShareAlike 2.5" licence. - - "What is the URL to your licence?" - -If you used our recommendation above the URL you will want here is: -http://creativecommons.org/licenses/by-sa/2.5/ - - "What is the URL to your local page about your licensing policy?" - -You should probably include a page on your wiki about your local licensing -policy, but you can leave this blank for now if you don't have one yet. - - "What module would you like to use for spam detection? (optional)" - -The module you choose should have a method called "looks_like_spam", which -accepts a hash with content and metadata as keys, and returns true or false -to the question of whether the edit should be considered to be spam. - - "What directory should we install static content (CSS, images, javascript) - to?" - -OpenGuides comes with some static content which will be installed -automatically. - - "What is the URL corresponding to the static content?" - -You will need to configure the above directory in your web server, then -input the URL the content will be visible at here. - - "Should we send email notifications when a moderated node is edited?" - -For spam avoidance, you can configure certain nodes to require moderation. -To ensure that such edits are noticed, OpenGuides can email you. - - "Distance calculation methods available are: - 1) British National Grid - 2) Irish National Grid - 3) UTM ellipsoid - Which would you like to use?" - - (and if you choose UTM ellipsoid) - "Which ellipsoid would you like to use? (eg 'Airy', 'WGS-84')" - -See http://www.vterrain.org/Projections/ for how this all works. -A UTM (Universal Transverse Mercator) ellipsoid maps latitude and -longitude to eastings and northings on a square grid, which allows -more accurate distance calculations within the guide. The British and -Irish National Grids are scaled and parametrised versions of UTM -ellipsoids (Airy 1830 in the British case, Modified Airy in the Irish). - -Please note that at the moment there is no provision for changing your -mind later about which ellipsoid to use, but it shouldn't be too hard -to write a conversion script so don't worry too much about picking the -wrong one. However do note that once you've entered some location -data you should not change this value in the config file without running -some kind of converter. - -If you decide to use the British or Irish National Grid, your users -will be able to choose between entering location data as lat/long -or as grid co-ordinates. - -You must have Geography::NationalGrid::GB installed to use the British -National Grid, Geography::NationalGrid::IE to use the Irish National -Grid, and Geo::Coordinates::UTM to use a UTM ellipsoid. - -If you want to use a UTM ellipsoid, WGS-84 is the best choice, as it -will allow you to use the Google Maps support with the minimum of fuss. - -* Dependency errors - -If, after you have answered these questions, the build script complains -about missing dependencies, don't panic! Simply install them from CPAN and -then try again. Note that a wiki.conf file will have been written out at -this point, so if you retain it you won't have to answer all the questions -again. - -* Custom templates and CSS - -Once you have installed OpenGuides you may wish to edit templates that -provide site-specific design. These templates are stored in the directory -custom-templates/ by default and are described in the file CUSTOMISATION. - -The id and class tags used for the CSS in OpenGuides are specified in -README.CSS. - -* Security - -The installer will try to create (or modify an existing) a .htaccess file -to protect wiki.conf, which contains sensitive data (ie passwords). -However we cannot tell whether apache (or any other web server you may be -using) is using this file, so you should check that it functioning and that -you cannot access wiki.conf over HTTP. - -You should also configure wiki.conf with the minimum permissions required -so that local users cannot read the file. This is difficult to automate, -but the file should be probably be mode 0640, owned by root or an admin -user, and set to the group the web server runs with. - -* Web server configuration - -In order to let your web server serve up OpenGuides correctly, you will -have to tell it to recognise your installation directory as one -containing CGI scripts. However you can make your URLs nicer by -employing mod_rewrite as well. The following Apache configuration -directives show how: - - Alias /myguide /usr/lib/cgi-bin/myguide - <Directory /usr/lib/cgi-bin/myguide> - Options FollowSymLinks Indexes ExecCGI - RewriteEngine on - RewriteBase /myguide/ - RewriteRule ^$ wiki.cgi [L] - </Directory> - Redirect /cgi-bin/myguide/ http://www.example.com/myguide/ - -You will of course need to make the appropriate substitutions for -your site. You also need to make sure that mod_rewrite is enabled in -your web server before adding such a configuration. The final step in -this URL tidying is to tell OpenGuides that the main CGI script can be -assumed to be called from the root of the install directory; do this by -setting the script name to be empty in wiki.conf: - - # what do you want the script to be called? - script_name = - -Currently the Build script does not support this value, so you will -have to make sure that you fix this up after an upgrade. - * Custom install locations

If you wish to install the OpenGuides modules in a private directory, @@ -415,46 +54,6 @@

perl Build.PL config='sitelib=/path/to/my/modules/'

-If any or all of the modules required by the OpenGuides scripts are in -a private directory, then you'll need to tell the scripts where to find -them. See the section above about munging in a custom lib path. - ----------------------------------------------------------------------- - -Important note for those using SQLite: - -The user your CGI is running as must have write access to not only the -database file itself, but the directory that the file is in, in order -that it can write a lockfile. If it doesn't have write access to the -database file, you'll see errors like "Unhandled error: [DBD::SQLite::db -do failed...". - ----------------------------------------------------------------------- - -* Multiple installations - -If you want to run multiple OpenGuides sites on one machine, you can use -some tricks to make life easier. This isn't currently part of the official -install routine, but will generally work. In the rest of this section we -will assume that you already have a working OpenGuides install for a -single site. - -Make a directory for the new site, and populate it with a set of symlinks -to the main installation directory (ie. for wiki.cgi, supersearch.cgi, -newpage.cgi, preferences.cgi, and the templates directory). wiki.conf -will not be a symlink, since this will differ from the original site. -In this case, simply copy the wiki.conf from the original install and -modify it in the obvious way; most importantly, by giving it a different -database name (we'll create the database in a moment). Don't forget to -set up a separate directory for indices for the new site. - -Normally, the database is created by the installation process described -above; however since we only want one copy of the modules and CGI -programs, it isn't appropriate to run them again. So we will make use of -the utility program "cgi-wiki-setupdb" which is included with the -Wiki::Toolkit distribution. Documentation for this command can be found in -its man page; run this with the appropriate arguments to create the -new database. - -Once the key step of setting up the database has been performed, and the -web server configured appropriately, the new site should be ready to go! +If you do choose this option, then when you come to set up a Guide you'll +need to make sure that the scripts know where to find your modules. See +the documentation on custom lib paths in SETUP.

Added: branches/new-install-process/SETUP =================================================================== --- branches/new-install-process/SETUP (rev 0) +++ branches/new-install-process/SETUP 2008-06-21 16:55:10 UTC (rev 1169) @@ -0,0 +1,421 @@ +OpenGuides setup instructions +============================= + +OpenGuides installation has two steps - installing the modules, and setting +up a Guide. Module installation is described in INSTALL, and setting up +a Guide is described in this file. You need to install the modules before +you can set up a Guide. + + +* Basic setup + +Guide setup is done using the script + + openguides-install + +which should have been installed somewhere suitable when you installed +the modules. If it isn't in your path, then you could try the +"locate" or "find" commands to figure out where it is. If it doesn't +seem to be anywhere on your system, then you may be using an old version +of OpenGuides - upgrade to the latest version, and then try again. + +When you run this script, it will ask you a number of questions. Once +you've answered them all, the script will write out a configuration file +containing all your answers, and then install the CGI scripts, templates, +any static content (e.g. CSS), and the configuration file in the places +you told it to. + +These questions are described below in the section entitled "Setup questions". + + +* Important note for those using SQLite: + +The user that your Guide is running as must have write access to not only +the database file itself, but the directory that the file is in, in order +that it can write a lockfile. If it doesn't have write access to the +database file, you'll see errors like "Unhandled error: [DBD::SQLite::db do +failed...". + + +* Custom templates and CSS + +Once you have set up a Guide, you may wish to edit certain of the templates +that provide site-specific design. These templates are stored in the +directory custom-templates/ by default and are described in the file +CUSTOMISATION. + +The id and class tags used for the CSS in OpenGuides are specified in +README.CSS. + + +* Security + +The openguides-install script will try to create an .htaccess file (or +modify any existing one) in order to protect wiki.conf, which contains +sensitive data (specifically, passwords). However we cannot tell whether +apache (or any other web server you may be using) is using this file, so +you should check that is it functioning and that you cannot access +wiki.conf over HTTP. + +You should also configure wiki.conf with the minimum permissions required +so that local users cannot read the file. This is difficult to automate, +but the file should be probably be mode 0640, owned by root or an admin +user, and set to the group the web server runs with. + + +* Web server configuration + +In order to let your web server serve up OpenGuides correctly, you will +have to tell it to recognise your installation directory as one +containing CGI scripts. However you can make your URLs nicer by +employing mod_rewrite as well. The following Apache configuration +directives show how: + + Alias /myguide /usr/lib/cgi-bin/myguide + <Directory /usr/lib/cgi-bin/myguide> + Options FollowSymLinks Indexes ExecCGI + RewriteEngine on + RewriteBase /myguide/ + RewriteRule ^$ wiki.cgi [L] + </Directory> + Redirect /cgi-bin/myguide/ http://www.example.com/myguide/ + +You will of course need to make the appropriate substitutions for +your site. You also need to make sure that mod_rewrite is enabled in +your web server before adding such a configuration. The final step in +this URL tidying is to tell OpenGuides that the main CGI script can be +assumed to be called from the root of the install directory; do this by +setting the script name to be empty in wiki.conf: + + # what do you want the script to be called? + script_name = + +Currently the installation script does not support this value, so you will +have to make sure that you fix this up after an upgrade. + + +* Setup questions + +When you run the openguides-install script, it will check the current +directory to see if it can find a wiki.conf file. If it doesn't find one, +it will check that you want to continue with the installation. If you choose +yes, then a number of questions will follow; these are described below. + + + "Skip OpenGuides configuration?" + +Answer "n" to this question unless you really know what you're doing. +It's mainly there for developers. + + + "What type of database do you want the site to run on?" + +Options here are "postgres", "mysql", or "sqlite". If you choose an option +that you don't have the appropriate database driver for, then the script will +tell you this and exit. + + + "What's the full filename of the SQLite database this site runs on?" + +You will only be asked this question if you chose sqlite in the previous +question. Enter the full path, e.g. /home/kake/data.db, even if the file +is/will be in the current directory. You do not have to create this file +in advance; the setup process will do this for you. + + + "What's the name of the database that this site runs on?" + "...the database user that can access that database?" + "...the password that they use to access the database?" + "...the machine that the database is hosted on?" + +You will only be asked these questions if you chose mysql or postgres in +the question about the type of database. + +You should create (or ask your ISP/sysadmin to create) a database +specifically for your Guide. If you wish to run more than one Guide, then +each one will need its own database. The final two questions are optional. +If your database user doesn't need a password to access the database, then +just press RETURN to skip the question about passwords. Similarly, if the +database is running on a local machine with username/password +authentication then just press RETURN to skip the question about the +machine that the database is hosted on. If it is running on a local +machine with IDENT authentication then you may need to answer "localhost" +to this question. If it is running on a remote machine then enter the full +hostname of that machine. + + + "What do you want the script to be called?" + +The default is for the main script to be called "wiki.cgi", but +you may prefer to name it after your city - "leeds-guide.cgi" for +example. Note that your webserver may be configured to only allow +execution of scripts ending in, for example, ".cgi" + + + "What directory should I install it in?" + +You need to pick a directory for the OpenGuides software to be +installed in. This must be one known to the webserver as containing +CGI scripts. You will need to have write permission on this directory +when you come to run "perl Build install"; unless this is a private +directory belonging to you then this might require an 'su' or 'sudo' +to root under Unix. + + + "What directory should I install the templates in?" + "Where should I look for custom templates?" + +Normally these will be in the install directory, but they can be anywhere. +Custom templates are intended to be user-modified, so you might want to +put them somewhere in /etc. + + + "What URL does the install directory map to?" + +Give the full address needed to access the installation directory with +a web browser - for example http://london.openguides.org/ + + + "Do you want me to munge a custom lib path into the scripts?" + +If you have installed some or all of the required Perl modules (or indeed +the OpenGuides modules themselves) into a private directory, you will +need to tell the scripts where to find these modules. Enter the paths +to search here just as you would enter them in a 'use lib qw( ... );' +in a Perl script. + + + "Do you want to use Plucene for searching?" + +This question is no longer asked, but documentation here is retained for +the benefit of people upgrading. + +If you are changing to Plucene from Search::InvertedIndex, you will +need to do two things: + - either delete your old indexes (they're just files in the index + directory) or use a different index directory + - reindex your entire wiki (see reindex.pl in the examples/ + directory of this distribution) + + + "What directory can I use to store indexes in for searching?" + +You need a directory to store files used as indexes for the site. The +user that your script will run as will need write permission on this +directory. Under some webserver configurations this might be a +dedicated user - 'nobody' or 'www-data' for example, but for many +multi-user systems this will just be yourself. + + + "Do you want to enable page deletion?" + "Please specify a password for the site admin." + +The default is to disable page deletion. If you choose to enable the +page deletion mechanism then you will need to add a password to your +wiki.conf by answering the question above or manually using a line such as + admin_pass = putyourpasswordhere +Users who know this password will be able to delete unwanted pages - +along with all their history - from your wiki. +*** USE WITH CAUTION. DELETED PAGES CANNOT BE RECOVERED. *** + + + "What's the URL of the site's stylesheet?" + +Supplying an answer to this question is optional. There are example +stylesheets in the examples/ directory - note that these will not be +automatically installed. + + + "What's the wiki called?" + +This is a title which will appear at the top of every page. If you have +more than one OpenGuides installation at the same site then each should +have a unique name, since this name is used to manage user preferences. + + + "Do you want the navigation bar included on the home page?" + +Answer "y" or "n". + + + "Do you want the ten most recent changes included on the home page?" + +Answer "y" or "n". + + + "Do you want the Random Page link to avoid returning a locale page? + "Do you want the Random Page link to avoid returning a category page? + +Answer "y" or "n". The defaults are "n", which means that Random Page is as +likely to return a category or locale page as anything else. If the category +and locale pages on your Guide are generally just lists of things in that +category/locale, you probably want to pick "y" here. If, on the other hand, +your category/locale pages generally have substantial content of their own, +you may prefer to choose "n". + + + "Do you want the content to appear above the navbar in the HTML?" + +Answer "y" or "n". The default is "n", for reasons of backwards +compatibility with existing stylesheets, but the recommended answer is +"y", as this will help search engines to find the most relevant parts +of your pages. + + + "What should the home page of the wiki be called?" + "How would you describe the wiki?" + +Self-explanatory. + + + "What city is the wiki based in?" + "What country is the wiki based in?" + +If the wiki will not be city or country specific you can leave either or +both of these blank. + + + "Contact email address for the wiki admin?" + +Self explanatory. + + + "What language will the site be in? (Please give an ISO language code.)" + +eg "en" for English, "it" for Italian. +See http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt + + + "What's the name of the node or page to use for the text formatting + rules link?" + "What URL do you want to use for the text formatting rules" + +From 0.19, OpenGuides allows users to choose whether or not to have a +permanent link to the text formatting rules node or page in their navbar. +You need to put the name of that node or URL in here for it to work, though. +You might want to call the node "Text Formatting Examples", +"Text Formatting Rules", "House Style" or whatever. + +Note that these the latter question will override the former, so if you +want to use a local node make sure to leave the latter blank. + + "Make node titles link to node backlinks (C2 style)?" + +This refers to turning titles into links which bring up a list of referring +pages. This was the convention with older wikis ("C2" refers to the original +wiki at http://c2.com/cgi/wiki), but is not intuitive. + + "Do you have a Google Maps API key to use with this guide?" + +If you want Google Maps integration, you need to register with Google to get +an API key. Visit http://www.google.com/apis/maps/signup.html and follow the +instructions. Paste the great long string into the console window where you +are installing. See README.GMAPS for more information. + + "What is the longitude of the centre point of a map to draw for your guide?" + "What is the latitude of the centre point of a map to draw for your guide?" + +It's probably a good idea to pick some notionally central point for your +guide. For example, Carfax for Oxford, Charing Cross for London. As a +convenience, you may paste in a Google Maps URL for the centre longitude +question and the (long,lat) will be parsed out from the URL. + + "What default zoom level shall we use for Google Maps?" + "What default zoom level shall we use for Google Maps in the search results?" + +The defaults are probably appropriate in most cases. + + "Would you like to display a Google Map on every node that has geodata?" + +Answer "y" or "n". Note that an answer of "y" will only take effect if you've +supplied a Google Maps API key above. Note further that users can choose to +turn this off in their preferences. + + "Forcibly treat stored lat/long data as if they used the WGS84 ellipsoid?" + +Default this answer if you don't know what it means. + + "Do you have a Google Analytics key to use with this guide?" + +If you'd like to use Google Analytics to track the traffic on your guide, +visit http://www.google.com/analytics/ to sign up for a key. The answer to +this question is the string in quotes in the HTML fragment they ask you to +paste into your HTML, something along the lines of _uacct = "UA-1234567-1" +- it's the UA-1234567-1 part that you need to put in here. If you've +forgotten your key, go to Analytics Settings, click "Edit" under Settings, +then click "Check Status" in the top right-hand corner of the box with grey +stripes. + + + "What licence will you use for the guide?" + +We strongly recommend that you think at the outset about the licence your +guide will use, for maximum usefulness. In particular for a guide that will +be on the OpenGuides network, we recommend the +"Creative Commons Attribution-ShareAlike 2.5" licence. + + "What is the URL to your licence?" + +If you used our recommendation above the URL you will want here is: +http://creativecommons.org/licenses/by-sa/2.5/ + + "What is the URL to your local page about your licensing policy?" + +You should probably include a page on your wiki about your local licensing +policy, but you can leave this blank for now if you don't have one yet. + + "What module would you like to use for spam detection? (optional)" + +The module you choose should have a method called "looks_like_spam", which +accepts a hash with content and metadata as keys, and returns true or false +to the question of whether the edit should be considered to be spam. + + "What directory should we install static content (CSS, images, javascript) + to?" + +OpenGuides comes with some static content which will be installed +automatically. + + "What is the URL corresponding to the static content?" + +You will need to configure the above directory in your web server, then +input the URL the content will be visible at here. + + "Should we send email notifications when a moderated node is edited?" + +For spam avoidance, you can configure certain nodes to require moderation. +To ensure that such edits are noticed, OpenGuides can email you. + + "Distance calculation methods available are: + 1) British National Grid + 2) Irish National Grid + 3) UTM ellipsoid + Which would you like to use?" + + (and if you choose UTM ellipsoid) + "Which ellipsoid would you like to use? (eg 'Airy', 'WGS-84')" + +See http://www.vterrain.org/Projections/ for how this all works. +A UTM (Universal Transverse Mercator) ellipsoid maps latitude and +longitude to eastings and northings on a square grid, which allows +more accurate distance calculations within the guide. The British and +Irish National Grids are scaled and parametrised versions of UTM +ellipsoids (Airy 1830 in the British case, Modified Airy in the Irish). + +Please note that at the moment there is no provision for changing your +mind later about which ellipsoid to use, but it shouldn't be too hard +to write a conversion script so don't worry too much about picking the +wrong one. However do note that once you've entered some location +data you should not change this value in the config file without running +some kind of converter. + +If you decide to use the British or Irish National Grid, your users +will be able to choose between entering location data as lat/long +or as grid co-ordinates. + +You must have Geography::NationalGrid::GB installed to use the British +National Grid, Geography::NationalGrid::IE to use the Irish National +Grid, and Geo::Coordinates::UTM to use a UTM ellipsoid. + +If you want to use a UTM ellipsoid, WGS-84 is the best choice, as it +will allow you to use the Google Maps support with the minimum of fuss.