Soks 0.0.7 → 1.0.0

data/templates/default/attachment/print_stylesheet.css

@@ -1,7 +1,2 @@
-#Menu {
-	display: none;
-}
-
-#command {
-	display: none;
-}
+/* Thanks to Pavel Sykora for fixing this */
+#menu, .command { display:none !important; }

data/templates/default/caches/readme.txt

@@ -0,0 +1 @@
+This folder contains various caches for the wiki, to speed up restarts.  If you are having problems, try deleting everything in here before starting soks again.

data/templates/default/content/Api%20for%20classes%20to%20modify%20the%20wiki.textile

@@ -22,3 +22,5 @@ Examples of helpers that use this api:
 * rss2wiki
 * mail2wiki
 * wiki2html
+
+Tag: Include this page in the distribution

data/templates/default/content/Author.textile

@@ -4,9 +4,12 @@ Soks was written by Tom Counsell.  He can be reached at tamc@rubyforge.org.
 
 h2. Thanks to
 
-* Bil Kleb for new page categories, meta page improvements and other suggestsions.
+* Pavel Sykora for a fix to the print stylesheet.
+* Bil Kleb for new page categories, meta page improvements and many other suggestsions.
 * Sebastien Clediere for a patch to fix uploads on windows and other bugfixes
 * Giovanni Ferro for a patch to allow soks to be used from a memory stick
 * _why for the RedCloth library
 * Austin Ziegler for the Diff:LCS library
 * Matz and ruby-core for the ruby language
+
+Tag: Include this page in the distribution

data/templates/default/content/Automatic%20Summaries.textile

@@ -1,77 +1,40 @@
 h1. Automatic Summaries
 
-In lib/helpers/default-helpers.rb you will find an AutomaticSummary class.  This uses the [[api => api for classes to modify the wiki ]] to watch for changes to the wiki, and if the page that is changed matches a given regexp, adds it to a summary page.
+In lib/helpers/default-helpers.rb you will find an AutomaticSummary class, and its subclasses AutomaticList and AutomaticDetailedList.  This uses the [[api => api for classes to modify the wiki ]] to watch for changes to the wiki, and if the page that is changed matches a given regexp, adds it to a summary page.
 
-You can use it by creating a line in your soks-wiki/start.rb file of the form @AutomaticSummary.new( wiki, settings )@ where settings can be (defaults shown):
+You can use it by creating a line in your soks-wiki/start.rb file of the form @AutomaticSummary.new( wiki, settings ) { |page| page.name =~ /Something you are interested in/ }@ where settings can be (defaults shown):
 
 <pre>
 <code>
 DEFAULT_SETTINGS = {
-	 	:regexp_for_title => /.*/, # These three regexps act as an AND
-		:regexp_for_author => nil, 
-		:regexp_for_content => nil,
 		:max_pages_to_show => nil,
-		:pagename => 'Summary',
+		:description => 'This summary was created automatically',
 		:author => 'AutomaticSummary',
-		:lines_to_include => nil, # If nil then justs puts a link, otherwise includes X number of lines from the page in the summary
-		:only_new_pages => false, # Otherwise includes changes
+		:lines_to_include => 10,
 		:sort_pages_by => :created_on, # Could be :revised_on or :score or :name or :name_for_index, or :author
 		:reverse_sort => false,
-		:include_metadata => false, # If true includes author and time in summary
-		:summarise_revisions => false, # If true, then can contain several revisions for same page
+		:event => :page_created, # Only summarises new pages. :page_revised would summarise changed pages
 		:remove_deleted_pages => true, # If false will keep references to deleted pages
+		:summarise_revisions => false, # If true will list revisions rather than pages
+		:merge_revisions_within => false, # If set to a number, repeats with the same author within that many seconds will be merged
 	}
 </code>
 </pre>
 
 h2. Examples
 
-Two examples of its use, included in the default-helpers.rb file, are the Site Index and the Recent Changes page:
+Four examples of its use, included in the default start.rb file are:
 
 <pre>
 <code>
-AutomaticSummary.new( wiki, {
- 	:regexp_for_title => /.*/ # Match all pages
-        :pagename => 'Site Index',
-	:author => 'Automatic Site Indexer',
-	:only_new_pages => true,
-	:sort_pages_by => :name_for_index,
-} )
+	AutomaticDetailedList.new( wiki, 'Known bugs' ) do |page|
+		page.name =~ /^Bug:/i && page.name !~ /^Bug: Type a title here/i
+	end
+	
+	AutomaticList.new( wiki, 'Instructions and Howtos' ) { |page| page.name =~ /^How to /i }
+	AutomaticSummary.new( wiki, 'Latest News', :max_pages_to_show => 1, :reverse_sort => true) { |page| page.name =~ /^News:/i }
+	AutomaticSummary.new( wiki, 'All News', :reverse_sort => true) { |page| page.name =~ /^News:/i }
 </code>
 </pre>
 
-<pre>
-<code>
-AutomaticSummary.new( wiki, { 
- 	:regexp_for_title => /.*/ # Match all pages
-        :pagename => 'Recent Changes',
-	:author => 'Automatic Recent Changes',
-	:only_new_pages => false,
-	:sort_pages_by => :revised_on,
-	:include_metadata => true,
-	:summarise_revisions => true,
-	:reverse_sort => true,
-	:remove_deleted_pages => false,
-})
-</code>
-</pre>
-
-You might also use it to construct a basic blog class:
-
-<pre>
-<code>
-AutomaticSummary.new( wiki, {
- 	:regexp_for_title => /^Blog:.*/ # Match all pages starting with blog
-        :pagename => 'Recent Blog Entries',
-	:author => 'Automatic Blog Watcher',
-        :max_pages_to_show => 10 # Only show the ten most recent blogs
-        :lines_to_include => 20 # Show the first 20 lines of each blog entry
-	:only_new_pages =>true,
-	:sort_pages_by => :created_on,
-	:include_metadata => true,
-	:reverse_sort => true,
-})
-</code>
-</pre>
-
-If you have any other ideas or examples, please add them here
+Tag: Include this page in the distribution

data/templates/default/content/Automatic%20linking%20between%20pages.textile

@@ -1,7 +1,7 @@
 h1. Automatic linking between pages
 
-Any reference to the title of another page in the wiki will be automatically linked.  e.g. home page is linked to the home page.
-
-The links are made left to right, top to bottom, with the longest possible link made at any given time.
+Any reference to the title of another page in the wiki will be automatically linked.  e.g. home page is linked to the home page.  The longest possible links are made first.
 
 The easiest way to create a new page (if your browser supports it - I can only positively say that Safari does) is to highlight the text you want to link from and press ctrl-n. 
+
+Tag: Include this page in the distribution

data/templates/default/content/{bug%3A%20competing%20edits.textile → Bug%3A%20Competing%20edits.textile}

@@ -1,9 +1,16 @@
+h1. Bug competing edits
+
 I had a case today where I was evidently editing a page at the same time someone else was.  He won and my edits were trashed upon save.  (Or at least this is what I surmise happened.)
 
 Is this possible?  --Bil
 
 Umm, trashed on save?  I hope not.  I hope that if you look at the 'show all changes' for the page it will show both edits in the history?  I *seriously* want to know if they are not.
 
+p(. I was paying more attention this time.  Two of us were editing the same page.
+I saved my changes, and they showed up on the page.
+Next, he saved his changes, and my changes were removed (but still available
+via the "show all changes"). --Bil
+
 As for a solution.  There seem to be two routes:
 # Put a 'lock' on the page, so that only one person can see the edit view at once.
 # Try and merge competing edits.
@@ -11,3 +18,5 @@ As for a solution.  There seem to be two routes:
 I would prefer to merge, but don't know how to implement...
 
 --tamc2
+
+Tag: Include this page in the distribution

data/templates/default/content/Bug%3A%20Does%20not%20make%20use%20of%20if%2Dmodified%2Dsince%20r.textile

@@ -1 +1,3 @@
 Currently tells the browser to not cache any page.  This is wasteful of bandwidth and increases server load.  Should handle the if-modified-since request headers to return 'not modified' messages instead.
+
+Tag: Include this page in the distribution

data/templates/default/content/Bug%3A%20E%2Dmail%20addresses%20with%20hyphens%20not%20recognised.textile

@@ -0,0 +1,17 @@
+The email:
+
+first-second@somewhere.com 
+
+results in the link
+
+==mailto:second@somewhere.com==
+
+The workaround is to type
+
+=="first-second@somewhere.com":mailto:first-second@somewhere.com==
+
+like
+
+"first-second@somewhere.com":mailto:first-second@somewhere.com
+
+Tag: Include this page in the distribution

data/templates/default/content/Bug%3A%20Email%20adresses%20in%20page%20titles%20cause%20incorrec.textile

@@ -0,0 +1,3 @@
+Seems like having an email adress in a page title causes problems with linking to that page.
+
+Tag: Include this page in the distribution

data/templates/default/content/Bug%3A%20GEM%20limits%20title%20lengths.textile

@@ -1 +1,3 @@
-It seems that Ruby GEM limits filename lengths, which means there is a limit on title lengths.  I am unclear what the limit for filename length is? and how this varies by platform?
+It seems that Ruby GEM limits filename lengths, which means there is a limit on title lengths.  It appears to be done so that the files work correctly on the windows platform. 
+
+Tag: Include this page in the distribution

data/templates/default/content/Bug%3A%20Memory%20leak.textile

@@ -0,0 +1,13 @@
+There appears to be a memory leak. 
+
+Not sure what triggers it, and whether it occurs in any versions appart from the one in the CVS.
+
+Spotted on this site (www.soks.org) where over a period of a couple of weeks, memory use grew from 47M to 102M.  This is a problem for this site as only 64M of virtual memory is available, and so the larger size causes a slow down through swapping.
+
+Will investiagate, and would appreciate other reports if anyone has a similar experience.
+
+--tamc2
+
+This hasn't repeated after that first time.  It may have just ben a temporary blip.  I'd appreciate any other reports --tamc2
+
+Tag: Include this page in the distribution

data/templates/default/content/Bug%3A%20Pages%20that%20link%20here%20may%20not%20appear%20on%20r.textile

@@ -0,0 +1,13 @@
+The pages that link here sidebar may not appear if you:
+# Run a soks wiki
+# Shutdown the wiki gracefully so that it saves its caches
+# Modify a wiki page off-line (everything is ok if you add a page)
+# Restart the wiki and it succesfully reloads its caches
+
+There are two workarounds:
+# Either delete the caches before restarting in step 4 above
+# Or edit any page in the wiki after restart.  The pages that link here sidebar will then reappear.
+
+Not sure yet as to the cause of this bug, but it doesn't seem to be a showstopper so I'm going to release v1-0-0 anyway. --tamc
+
+Tag: Include this page in the distribution

data/templates/default/content/Bug%3A%20Textile%20mishandles%20paragraphs.textile

@@ -31,3 +31,7 @@ A paragraph
 A paragraph not kept separate
 
 # Blah
+
+This is possibly a bug with Redcloth rather than soks.
+
+Tag: Include this page in the distribution

data/templates/default/content/Bug%3A%20Unanticipated%20Rollbacks.textile

@@ -19,3 +19,5 @@ If it happens, could you let me know:
 Thanks
 
 tamc2
+
+Tag: Include this page in the distribution

data/templates/default/content/Bug%3A%20notextile%20does%20not%20prevent%20page%20inserts.textile

@@ -1 +1,3 @@
 Page inserts like @[ [insert other page]]@ should not insert another page if they are surrounded by notextile tags (or code, or pre?).  
+
+Tag: Include this page in the distribution

data/templates/default/content/Home%20Page.textile

@@ -1,6 +1,6 @@
 h1. Congratulations, you have installed SOKS 
 
-Welcome to Soks.  It is yet another wiki, written in ruby.  Please bear in mind that it is alpha, and therefore do not trust your mission critical sites to it.  Please feel free to use and adapt, the soks licence is free and liberal (although if you feel like contributing towards a new mac for the author that would be apreciated).  
+Welcome to Soks.  It is yet another wiki, written in ruby.  Please bear in mind that it is beta. Feel free to use and adapt, the soks licence is free and liberal (although if you feel like contributing towards a new mac for the author that would be apreciated).  
 
 p{background:yellow;padding:10px;}. A limited selection of help and bug reports are included here.  For more information, and to share experiences, please visit http://www.soks.org. If you are upgrading, you may wish to look at the list of changes.
 
@@ -18,3 +18,5 @@ h2. Feedback
 * To keep track of developments, you may wish to subscribe to the mailing list at http://rubyforge.org/projects/soks.
 
 [[insert picture of a pair of soks]]
+
+Tag: Include this page in the distribution

data/templates/default/content/How%20to%20administrate%20this%20wiki.textile

@@ -2,7 +2,7 @@ h1. Adjusting the settings
 
 Take a look at the start.rb file in your wiki folder.  This can be used to change the settings such as port and url of this site, and to enable more advanced features such as calendars and automatic summaries.
 
-h2. To restart your wiki
+h2. To start your wiki
 
 The soks-create-wiki.rb script will have created a folder in the directory in which you ran it (by default the folder is 'soks-wiki'). In that folder is a script 'start.rb' run it.
 <code>
@@ -10,16 +10,28 @@ cd soks-wiki
 ruby start.rb
 </code>
 
+h2. To stop your wiki
+
+If you've started the wiki as above, then hold down the ctrl key and press c.
+
+If you have run the wiki as a daemon, or using nohup, then you will need to find the process id of the wiki.  This can be found by @top@ or @ps -e | grep ruby@.  In the first instance, try @kill -INT 123@ where 123 is the number found from top or ps.  That will try and make the wiki gracefully shut down.  If that doesn't work @kill -KILL 123@ will force the wiki to halt immediately.
+
 h2. To make your site accessible beyond localhost
 
-Open start.rb in your directory. Un-comment the lines
+Open start.rb in your directory. Find the line:
 
 <code>
-# :url => 'http://localhost:8000',
-# :port => 8000,
+view = View.new( wiki, "http://localhost:8000", "#{root_directory}/views" )
 </code>
 
-and replace them with the url and port you wish the wiki to run on.
+and replace the url with the url and port you wish the wiki to run on.
+
+Then replace
+<code>
+server = WEBrick::HTTPServer.new(:Port => 8000 )
+</code>
+
+with the port you wish the wiki to run on.
 
 h2. To password protect your wiki.
 
@@ -31,17 +43,15 @@ Edit template/start.rb in the directory where soks was installed.
 
 h2. To change how often the wiki checks the content directory for any changes.
 
-Open start.rb and add this to your CUSTOM_SETTINGS hash:
-<code>:check_files_every => 60, # Seconds</code>
-
-h2. To add a calendar and upcoming events page:
-
-Open start.rb and uncomment:
+Open start.rb and change this line:
 <code>
-# calendar = AutomaticCalendar.new( wiki ) # Adds a series of calendar pages to the wiki
-# AutomaticUpcomingEvents.new( wiki, calendar ) # Creates a page with the next weeks events drawn from the calendar pages
+wiki.check_files_every = :min
 </code>
 
+Acceptable values are nil (never), :sec, :min, :hour, :day
+
 h2. To add a page that summarises other pages:
 
 See Automatic summaries
+
+Tag: Include this page in the distribution

data/templates/default/content/How%20to%20change%20the%20way%20this%20wiki%20looks.textile

@@ -4,7 +4,7 @@ If you develop any improvements to the layout and style of this wiki, and are wi
 
 h2. Changing the logo on the right
 
-The logo can be changed by replacing logo.tif in the in the attachment folder of the wiki you have created ( soks-wiki/attachment/logo.tif by default)
+The logo can be changed by replacing logo.jpg in the in the attachment folder of the wiki you have created ( soks-wiki/attachment/logo.tif by default)
 
 h2. Changing the color scheme
 
@@ -28,3 +28,5 @@ Note that you must restart soks for changes to the template to take effect.
 h2. Changing the default styles for NEW wikis 
 
 To change the style and layout of new wikis created using the soks-create-wiki.rb command, then edit the 'template' directory of wherever you installed soks.
+
+Tag: Include this page in the distribution

data/templates/default/content/How%20to%20export%20a%20site%20from%20this%20wiki.textile

@@ -1,5 +1,25 @@
 h1. How to export a site from this wiki
 
+h2. How to export as html
+
+Modify your start.rb file to include:
+<pre>
+<code>
+require 'helpers/wiki2html'
+Wiki2Html.new( wiki, view, 
+:views_to_copy => ['view','meta','rss'],
+:extension => '.html',
+:destination_dir => '/Users/tamc2/Sites',
+:destination_url => 'http://localhost/~tamc2')
+</code>
+</pre>
+
+Where desitination_dir should be the directory you wish to export the html to, and destination_url should be the base_url you wish to use in the exported pages (could be just '/').
+
+When you restart the wiki it will then maintain an html copy of the wiki in that directory.
+
+h2. How to export the raw data
+
 The contents of this site are stored in flat files in the 'contents' folder of this wiki (soks-wiki/contents by default).  They are the ones with the .textile ending.  Should be pretty easy to transfer them to wherever you need.
 
 The authors, and change history of each page are stored in the same folder with a yaml extension. These are yaml'd files that contain many documents.  Each document contains a single revision. Each revision is an array of [ revision number, changes, author, creation time ].  The changes is an array of change groups.  Each change group is an array of changed lines.  There may be several documents with the same revision number.  The last document with a particular revision number is the 'definative' one.
@@ -58,3 +78,5 @@ Hello%20World.yaml might contain
       - What a beautiful world
     - 
 </pre>
+
+Tag: Include this page in the distribution

data/templates/default/content/How%20to%20get%20the%20latest%20Soks%20from%20cvs.textile

@@ -19,3 +19,5 @@ Steps:
 # @cvs -z3 -d:pserver:anonymous@rubyforge.org:/var/cvs/soks checkout soks@
 # Soks will now download...
 # @cd soks@ and play.
+
+Tag: Include this page in the distribution

data/templates/default/content/How%20to%20hack%20soks.textile

@@ -59,3 +59,5 @@ The WikiServlet deals with file uploads by separately writing the uploaded file
 h4. soks-helpers.rb
 
 These are a series of classes that may be optionally loaded by a wiki's start.rb script. They receive notifications of page changes from the View object and can use this information to update other pages in the wiki. See automatic summaries for a little more detail.
+
+Tag: Include this page in the distribution

data/templates/default/content/How%20to%20import%20a%20site%20from%20instiki.textile

@@ -11,3 +11,5 @@ h1. How to import a site from instiki
 # Start the wiki <code>ruby soks-wiki/start.rb</code>
 
 Your instiki content should then appear.  Note that all the links still work, but that all the pages have their WikiWord names.
+
+Tag: Include this page in the distribution

data/templates/default/content/{How%20to%20import%20data%20to%20this%20wiki.textile → How%20to%20import%20data.textile}

@@ -1,6 +1,6 @@
-*The basic question:* How can I import data into Soks?  (both pages and attachments)
+h1. How to import data into a Soks wiki
 
-h2. Scenario
+*The basic question:* How can I import data into Soks?  (both pages and attachments)
 
 I have a table worth of information that I would like to load into my Soks wiki.  Each row of the table will become a page and each row has a PDF file associated with it.
 
@@ -38,8 +38,4 @@ A third alternative would be to use DRb (e.g. write @require 'drb'@  @DRb.start_
 
 fn1.  Changes detected by looking at the file's timestamp, not its content.
 
-----
-
-Puzzled by Textile's non-rendering of the paragraph break between my signature above and Tom's "Yes.  Comments:" --Bil
-
-I've had a little look and seems to be an interaction between the pre tag and the following list.  Corrected here and noted at Bug: Textile mishandles paragraphs.  I think it is Redcloth, so will report there.
+Tag: Include this page in the distribution

data/templates/default/content/How%20to%20install%20Soks.textile

@@ -29,3 +29,5 @@ ruby Soks-x.x.x/bin/soks-create-wiki.rb
 </pre>
 
 ...and then surf to http://localhost:8000
+
+Tag: Include this page in the distribution

data/templates/default/content/How%20to%20password%20protect%20your%20wiki.textile

@@ -4,40 +4,50 @@ You can specify what authentication to be used based on a regular expression mat
 
 Open @start.rb@ in your wiki directory. Un-comment and edit the authenticators section and edit the array.  The format is [  [ first regexp to match against title, authenticator to use ],  [ second regexp to match against title, authenticator to use ] ... ]. For example:
 
-* The following matches against all the standard 'non editing commands' and doesn't ask for any authentication:
+h2. No authentication
+
+The following matches against all the standard 'non editing commands' and doesn't ask for any authentication:
 
 <code>[ %r{/(view|rss|print|find|meta)/.*}, WEBrick::HTTPAuth::NoAuthenticationRequired.new ]</code>
 
-* The following doesn't permit any file or picture uploads:
+h2. No uploads
+
+The following doesn't permit any file or picture uploads:
 
 <code>[ %r{/upload/.*}, WEBrick::HTTPAuth::NotPermitted.new ]</code>
 
-* The following asks for a site wide password to edit or save changes to the home page:
+h2. Site wide password
+
+The following asks for a site wide password to edit or save changes to the home page:
 
 <code>[ %r{/(edit|save)/home page}, WEBrick::HTTPAuth::SiteWidePassword.new('password','You need to enter the site wide password to edit the home page') ]</code>
 
-* The following uses the standard WEBrick authentication system on any page whose name starts with private. The standard WEBrick authentication uses a database of usernames and passwords.  See [[ Gnome's Guide => http://shogo.homelinux.org/~ysantoso/webrickguide/html/html_webrick.html ]] for details.
+h2. Per-user passwords
+
+The following uses the standard WEBrick authentication system on any page whose name starts with private. The standard WEBrick authentication uses a database of usernames and passwords.  See [[ Gnome's Guide => http://shogo.homelinux.org/~ysantoso/webrickguide/html/html_webrick.html ]] for details.
 
 <code>[ %r{/(view|edit|save)/private.*},WEBrick::HTTPAuth::BasicAuth.new( :UserDB => htpasswd, :Realm => realm ) ]</code>
 
-* The following is the default. For any page it just asks for a username, but the password can be left blank.
+The following is the default. For any page it just asks for a username, but the password can be left blank.
 
 <code>[ %r{.*}, WEBrick::HTTPAuth::AskForUserName.new( 'No password, just enter a name') ]</code>			
+BasicAuth isn't very secure as it transfers passwords over plaintext. If you can cope with some incompatability with very old browsers, DigestAuth is more secure. To implement DigestAuth:
 
-* BasicAuth isn't very secure as it transfers passwords over plaintext. If you can cope with some incompatability with very old browsers, DigestAuth is more secure. To implement DigestAuth:
 # run this command: @htdigest -c /path/to/your/soks-wiki/htdigest "name of your realm" yourusername@ and enter your password. On gentoo, the full path is @/usr/sbin/htdigest2@
 # Add this line into start.rb, inside the authenticators= block: @[ %r{/(view|edit|save)/private.*},WEBrick::HTTPAuth::DigestAuth.new( :UserDB => WEBrick::HTTPAuth::Htdigest.new('/path/to/your/soks-wiki/htdigest'), :Realm => "name of your realm") ]@
-# Uncomment this line: @:authenticators => authenticators@ 
--- Skorgu
 
-Note a big bug is that viewing attached images and files is NOT password protected.  This will be fixed in version 0.0.6.
+h2. Multiple authentication systems
+
+To further-complicate your login woes, there is a nifty trick you can pull with the way Soks does its authentications. Because it creates a separate instance of the authenticator for each regexp, you can stack 'em :) Say you want to restrict viewing to those who have an account, but you don't want everyone to be able to edit. The first step is to create two htdigest files. One will have those who can read, the other those who can write. When you make these files, ensure that the realms are identical. Now assign the htdigest.write to the (edit|save) bits, and the htdigest.read to the (view|print|etc) bits. The annoying bit is that users who can edit need to be added to both files, but it makes up for it by users not having to login again when they want to edit. 
 
 ----
 
-Is there any means to changing the authentication on the fly like how the editable "sidebar page" works?  (Have a "master" page that is access controlled, on which one would put other page links that would then become access controlled.) --Bil
+h2. Suggestions / The future
 
-----
+Is there any means to changing the authentication on the fly like how the editable "sidebar page" works?  (Have a "master" page that is access controlled, on which one would put other page links that would then become access controlled.) --Bil
 
 Can someone point me to an example (or outline the steps) to having the user names checked for validity by an LDAP server ?  (Note: I asked a similar question on the Webricken mailing list.) --Bil
 
 Not used LDAP myself, but the example at http://dataspill.org/posts/show/4 seems to show how one might communicate with the LDAP server to check valididty.  This would need to be inserted into a WEBrick authenticator. If you just duplicate the code of an existing WEBrick authenticator (e.g. 1.8/webrick/httpauth/basicath.rb) you should be able to do a few tweaks to the authenticate method to get what you want.  --tamc2
+
+Tag: Include this page in the distribution