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.
Author: dom
Date: 2008-06-08 00:37:18 +0100 (Sun, 08 Jun 2008)
New Revision: 1164
Modified:
trunk/Changes
Log:
release date
Modified: trunk/Changes
===================================================================
--- trunk/Changes 2008-06-07 23:23:32 UTC (rev 1163)
+++ trunk/Changes 2008-06-07 23:37:18 UTC (rev 1164)
@@ -3,7 +3,7 @@
More detailed changelogs can be found at
<http://dev.openguides.org/log/trunk>.
-0.62
+0.62 8 June 2008
Allow wiki page links (simple: [[Foo]], title: [[Foo|bar]]) in
change summaries.
Ensure that all modules we ship are versioned.
Author: dom
Date: 2008-06-08 00:23:32 +0100 (Sun, 08 Jun 2008)
New Revision: 1163
Modified:
trunk/lib/OpenGuides.pm
trunk/lib/OpenGuides/Build.pm
trunk/lib/OpenGuides/Config.pm
trunk/lib/OpenGuides/RDF.pm
trunk/lib/OpenGuides/Search.pm
trunk/lib/OpenGuides/Test.pm
trunk/lib/OpenGuides/Utils.pm
trunk/wiki.cgi
Log:
update version numbers and copyright years
Modified: trunk/lib/OpenGuides/Build.pm
===================================================================
--- trunk/lib/OpenGuides/Build.pm 2008-05-26 14:14:15 UTC (rev 1162)
+++ trunk/lib/OpenGuides/Build.pm 2008-06-07 23:23:32 UTC (rev 1163)
@@ -3,7 +3,7 @@
use strict;
use vars qw( $VERSION );
-$VERSION = '0.01';
+$VERSION = '0.02';
use Module::Build;
use OpenGuides::Config;
Modified: trunk/lib/OpenGuides/Config.pm
===================================================================
--- trunk/lib/OpenGuides/Config.pm 2008-05-26 14:14:15 UTC (rev 1162)
+++ trunk/lib/OpenGuides/Config.pm 2008-06-07 23:23:32 UTC (rev 1163)
@@ -3,7 +3,7 @@
use warnings;
use vars qw( $VERSION );
-$VERSION = '0.02';
+$VERSION = '0.03';
use Carp qw( croak );
use Config::Tiny;
@@ -342,7 +342,7 @@
=head1 COPYRIGHT
- Copyright (C) 2004-2007 The OpenGuides Project. All Rights Reserved.
+ Copyright (C) 2004-2008 The OpenGuides Project. All Rights Reserved.
The OpenGuides distribution is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
Modified: trunk/lib/OpenGuides/RDF.pm
===================================================================
--- trunk/lib/OpenGuides/RDF.pm 2008-05-26 14:14:15 UTC (rev 1162)
+++ trunk/lib/OpenGuides/RDF.pm 2008-06-07 23:23:32 UTC (rev 1163)
@@ -5,7 +5,7 @@
use OpenGuides::Utils;
use vars qw( $VERSION );
-$VERSION = '0.10';
+$VERSION = '0.11';
use Time::Piece;
use URI::Escape;
@@ -283,7 +283,7 @@
=head1 COPYRIGHT
-Copyright (C) 2003-2007 The OpenGuides Project. All Rights Reserved.
+Copyright (C) 2003-2008 The OpenGuides Project. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
Modified: trunk/lib/OpenGuides/Search.pm
===================================================================
--- trunk/lib/OpenGuides/Search.pm 2008-05-26 14:14:15 UTC (rev 1162)
+++ trunk/lib/OpenGuides/Search.pm 2008-06-07 23:23:32 UTC (rev 1163)
@@ -1,6 +1,6 @@
package OpenGuides::Search;
use strict;
-our $VERSION = '0.11';
+our $VERSION = '0.12';
use CGI qw( :standard );
use Wiki::Toolkit::Plugin::Locator::Grid;
@@ -831,7 +831,7 @@
=head1 COPYRIGHT
- Copyright (C) 2003-2007 The OpenGuides Project. All Rights Reserved.
+ Copyright (C) 2003-2008 The OpenGuides Project. All Rights Reserved.
The OpenGuides distribution is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
Modified: trunk/lib/OpenGuides/Test.pm
===================================================================
--- trunk/lib/OpenGuides/Test.pm 2008-05-26 14:14:15 UTC (rev 1162)
+++ trunk/lib/OpenGuides/Test.pm 2008-06-07 23:23:32 UTC (rev 1163)
@@ -4,7 +4,7 @@
use strict;
use vars qw( $VERSION );
-$VERSION = '0.03';
+$VERSION = '0.04';
use CGI;
@@ -210,7 +210,7 @@
=head1 COPYRIGHT
- Copyright (C) 2004-2007 The OpenGuides Project. All Rights Reserved.
+ Copyright (C) 2004-2008 The OpenGuides Project. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
Modified: trunk/lib/OpenGuides/Utils.pm
===================================================================
--- trunk/lib/OpenGuides/Utils.pm 2008-05-26 14:14:15 UTC (rev 1162)
+++ trunk/lib/OpenGuides/Utils.pm 2008-06-07 23:23:32 UTC (rev 1163)
@@ -2,7 +2,7 @@
use strict;
use vars qw( $VERSION );
-$VERSION = '0.10';
+$VERSION = '0.11';
use Carp qw( croak );
use Wiki::Toolkit;
@@ -499,7 +499,7 @@
=head1 COPYRIGHT
- Copyright (C) 2003-2007 The OpenGuides Project. All Rights Reserved.
+ Copyright (C) 2003-2008 The OpenGuides Project. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
Modified: trunk/lib/OpenGuides.pm
===================================================================
--- trunk/lib/OpenGuides.pm 2008-05-26 14:14:15 UTC (rev 1162)
+++ trunk/lib/OpenGuides.pm 2008-06-07 23:23:32 UTC (rev 1163)
@@ -14,7 +14,7 @@
use vars qw( $VERSION );
-$VERSION = '0.61';
+$VERSION = '0.62';
=head1 NAME
@@ -2243,7 +2243,7 @@
=head1 COPYRIGHT
- Copyright (C) 2003-2007 The OpenGuides Project. All Rights Reserved.
+ Copyright (C) 2003-2008 The OpenGuides Project. All Rights Reserved.
The OpenGuides distribution is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
Modified: trunk/wiki.cgi
===================================================================
--- trunk/wiki.cgi 2008-05-26 14:14:15 UTC (rev 1162)
+++ trunk/wiki.cgi 2008-06-07 23:23:32 UTC (rev 1163)
@@ -5,7 +5,7 @@
use sigtrap die => 'normal-signals';
use vars qw( $VERSION );
-$VERSION = '0.61';
+$VERSION = '0.62';
use CGI qw/:standard/;
use CGI::Carp qw(croak);