November
========

November is Copyright (C) 2008-2009, the November contributors (as listed in
AUTHORS).

LICENSE INFORMATION
-------------------

November is free software; you can redistribute it and/or modify it under the
terms of the Artistic License 2.0.  (Note that, unlike the Artistic License
1.0, version 2.0 is GPL compatible by itself, hence there is no benefit to
having an Artistic 2.0 / GPL disjunction.)

CONTRIBUTING
------------

We'll hand out commit bits liberally. If you want to contribute, create an
account on github.org and send your github handle to Johan
(johan.viklund@gmail.com).  Patches are ok too, if you prefer those.  See
docs/COMMITTERS if these thoughts intrigue you.

PREREQUISITES
-------------

You'll need Parrot and Rakudo. Check them out from the Parrot svn repository
and follow the instructions in the checkout. Note that the latest 'stable
release' of Parrot/Rakudo often isn't new enough, since we tend to use features
developed after the latest release.

See instructions on the Rakudo web site:

 <http://rakudo.org/how-to-get-rakudo>

You'll also need the projects listed in deps.proto, presently only
HTML::Template. It is preferrable to build HTML::Template before building
November.

$ pwd
/tmp
$ git clone git://github.com/viklund/november.git
$ git clone git://github.com/masak/html-template.git
$ export RAKUDO_DIR=$PARROT_DIR/languages/rakudo
$ export PERL6LIB=$RAKUDO_DIR:/tmp/november/lib:/tmp/html-template/lib
$ cd html-template/
$ perl Makefile.PL
$ make
$ cd ../november/
$ perl Makefile.PL
$ make

The package installer 'proto' (at <http://github.com/masak/proto>) does all of
the above for you automatically:

$ ./proto install november   # installs Rakudo/Parrot, November & all its deps

REPOSITORY LAYOUT
-----------------

/            Perl 6 wiki implementation
│
├─data/      File database contents for an empty wiki instance
│
├─skins/     Default skins for the Perl 6 implementation
│
├─t/         Tests for the Perl 6 implementation
│
├─p5w/       Perl 5 reference implementation
│
├─docs/      Developer documentation for both p5w and p6w
│
├─talks/     Presentations and links to videos about November
│
└─logotype/  Graphics files for the November logotype

RUNNING NOVEMBER
----------------

Before building November you have to set the PARROT_DIR, RAKUDO_DIR and
PERL6LIB environment variables to include the lib/ subdirectory of the
November repository. In bash, that would look like this:

  $ export PARROT_DIR=/path/to/parrot
  $ export RAKUDO_DIR=/path/to/rakudo
  $ export PERL6LIB=/path/to/repository/of/november/lib

After that, you can build as usual.

  $ perl Makefile.PL
  $ make             # not required; speeds up startup times
  $ make test        # not required; requires Test::Harness v3.00 or higher

* Running November on the command line
  
  This will generate the Main_Page on STDOUT:

    $ ./test_wiki.sh

  To specify which page to view you need to specify the path, as follows:

    $ ./test_wiki.sh
    $ ./test_wiki.sh /view/Another_Page
    $ ./test_wiki.sh /all
    $ ./test_wiki.sh /recent
    $ ./test_wiki.sh /view/Main_Page

  The above first and last commands are equivalent, since 'view' is the 
  default action, and 'Main_Page' is the default page for the 'view' action.

  The other actions we have so far are 'edit', 'log_in', 'log_out'.

* Running November through a web server

  We have only tested the following on the Apache web server. You need to put
  these files and directories in some directory where Apache can execute it
  (your cgi-bin/ dir for example):

    wiki.sh
    wiki
    lib/Config.pm
    lib/CGI.pm
    lib/Dispatcher.pm
    lib/Dispatcher/Rule.pm
    lib/HTML/Template.pm
    lib/HTML/Template/Grammar.pm
    lib/November.pm
    lib/November/Storage.pm
    lib/November/Storage/File.pm
    lib/Session.pm
    lib/Tags.pm
    lib/Text/Escape.pm
    lib/Text/Markup/Wiki/Minimal.pm
    lib/Text/Markup/Wiki/Minimal/Grammar.pm
    lib/Text/Markup/Wiki/MediaWiki.pm
    lib/URI.pm
    lib/URI/Grammar.pm
    lib/Utils.pm
    skin/

  Then put these directories somewhere else. Preferably someplace where apache
  can't serve them over the net. And yes, skin/ should be in both places,
  which is not optimal. We're working on that.

    data/
    skin/

  Edit the Config.pm file and set the $.server_root variable to the directory
  under which both skin/ and data/ are accessible (remember to include a
  trailing slash). $.web_root has to be '' for the moment, we don't yet
  support having November anywhere else, but hang in there.

  If you have compiled November you can copy the .pir files instead of the .pm
  files. Make sure that the files and directories below data/ are readable
  and writable by the web server.

  To set up Apache to handle all request by November, you can use mod_rewrite:

    RewriteRule ^/([^\.]*)$ /cgi-bin/wiki.sh [PT]

  If you are using Apache for other purposes as well, you might want to do
  the rewriting differently.

  After this, you can direct your browser to the wiki:

    http://localhost/

CONTACT
-------

Google group: november-wiki@googlegroups.com
IRC channel: #november-wiki over at irc.freenode.org