Merge branch 'selfdoc'

contrib/autocomplete/main.php

@@ -4,6 +4,9 @@
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
  * Description: Auto-complete for search and upload tags
+ * Documentation:
+ *  Just enable and things should start autocompleting as if
+ *  by magic. That is, if this extension actually worked...
  */
 
 class AutoComplete implements Extension {

contrib/ban_words/main.php

@@ -4,6 +4,19 @@
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
  * Description: For stopping spam and other comment abuse
+ * Documentation:
+ *  Allows an administrator to ban certain words
+ *  from comments. This can be a very simple but effective way
+ *  of stopping spam; just add "viagra", "porn", etc to the
+ *  banned words list.
+ *  <p>Regex bans are also supported, allowing more complicated
+ *  bans like <code>/http:.*\.cn\//</code> to block links to
+ *  chinese websites, or <code>/.*?http.*?http.*?http.*?http.*?/</code>
+ *  to block comments with four (or more) links in.
+ *  <p>Note that for non-regex matches, only whole words are
+ *  matched, eg banning "sex" would block the comment "get free
+ *  sex call this number", but allow "This is a photo of Bob
+ *  from Essex"
  */
 
 class BanWords implements Extension {

contrib/bulk_add/main.php

@@ -4,6 +4,13 @@
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
  * Description: Bulk add server-side images
+ * Documentation:
+ *  Upload the images into a new directory via ftp or similar,
+ *  go to shimmie's admin page and put that directory in the
+ *  bulk add box. If there are subdirectories, they get used
+ *  as tags (eg if you upload into /home/bob/uploads/holiday/2008/
+ *  and point shimmie ad /home/bob/uploads, then images will be
+ *  tagged "holiday 2008")
  */
 
 class BulkAdd implements Extension {

contrib/emoticons/main.php

@@ -3,7 +3,13 @@
  * Name: Emoticon Filter
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
- * Description: Turn :smile: into a link to smile.gif
+ * Description: Lets users use graphical smilies
+ * Documentation:
+ *  This extension will turn colon-something-colon into a link
+ *  to an image with that something as the name, eg :smile:
+ *  becomes a link to smile.gif
+ *  <p>Images are stored in /ext/emoticons/default/, and you can
+ *  add more emoticons by uploading images into that folder.
  */
 
 class Emoticons extends FormatterExtension {

contrib/et/main.php

@@ -3,7 +3,13 @@
  * Name: System Info
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
- * Description: Show various bits of system information, for debugging
+ * Description: Show various bits of system information
+ * Documentation:
+ *  Knowing the information that this extension shows can be
+ *  very useful for debugging. There's also an option to send
+ *  your stats to my database, so I can get some idea of how
+ *  shimmie is used, which servers I need to support, which
+ *  versions of PHP I should test with, etc.
  */
 
 class ET implements Extension {

contrib/featured/main.php

@@ -4,6 +4,11 @@
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
  * Description: Bring a specific image to the users' attentions
+ * Documentation:
+ *  Once enabled, a new "feature this" button will appear next
+ *  to the other image control buttons (delete, rotate, etc).
+ *  Clicking it will set the image as the site's current feature,
+ *  which will be shown in the side bar of the post list.
  */
 
 class Featured implements Extension {

contrib/handle_archive/main.php

@@ -3,6 +3,11 @@
  * Name: Archive File Handler
  * Author: Shish <webmaster@shishnet.org>
  * Description: Allow users to upload archives (zip, etc)
+ * Documentation:
+ *  Note: requires exec() access and an external unzip command
+ *  <p>Any command line unzipper should work, some examples:
+ *  <p>unzip: <code>unzip -d "%d" "%f"</code>
+ *  <br>7-zip: <code>7zr x -o"%d" "%f"</code>
  */
 
 class ArchiveFileHandler implements Extension {

contrib/home/main.php

@@ -1,11 +1,17 @@
 <?php
 /**
-* Name: Home Extension
+* Name: Home Page
 * Author: Bzchan <bzchan@animemahou.com>
 * License: GPLv2
-* Description: Extension adds a page "home" containing user specified
-*              links and a counter showing total number of posts. The
-*              page is accessed via /home.
+* Description: Displays a front page with logo, search box and image count
+* Documentation:
+*  Once enabled, the page will show up at the URL "home", so if you want
+*  this to be the front page of your site, you should go to "Board Config"
+*  and set "Front Page" to "home".
+*  <p>The images used for the numbers can be changed from the board config
+*  page. If you want to use your own numbers, upload them into a new folder
+*  in <code>/ext/home/counters</code>, and they'll become available
+*  alongside the default choices.
 */
 
 class Home implements Extension {

contrib/ipban/main.php

@@ -4,7 +4,11 @@
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
  * Description: Ban IP addresses
- * Link: http://trac.shishnet.org/shimmie2/wiki/Contrib/Extensions/IPBan
+ * Documentation:
+ *  <b>Adding a Ban</b>
+ *  <br>IP: Can be a single IP (eg. 123.234.210.21), or a CIDR block (eg. 152.23.43.0/24) 
+ *  <br>Reason: Any text, for the admin to remember why the ban was put in place 
+ *  <br>Until: Either a date in YYYY-MM-DD format, or an offset like "3 days"
  */
 
 // RemoveIPBanEvent {{{

contrib/news/main.php

@@ -3,7 +3,9 @@
  * Name: News
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
- * Description: Show a short amonut of text in a block on the post list
+ * Description: Show a short amount of text in a block on the post list
+ * Documentation:
+ *  Any HTML is allowed
  */
 
 class News implements Extension {

contrib/notes/main.php

@@ -4,6 +4,8 @@
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
  * Description: Adds notes overlaid on the images
+ * Documentation:
+ *  This is quite broken :(
  */
 
 class Notes implements Extension {

contrib/numeric_score/main.php

@@ -4,6 +4,9 @@
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
  * Description: Allow users to score images
+ * Documentation:
+ *  Each registered user may vote an image +1 or -1, the
+ *  image's score is the sum of all votes.
  */
 
 class NumericScoreSetEvent extends Event {

contrib/piclens/main.php

@@ -4,6 +4,11 @@
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
  * Description: Adds a link to piclensify the gallery
+ * Documentation:
+ *  This extension only provides a button to the javascript
+ *  version of the gallery; the "RSS for Images" extension
+ *  is piclens-compatible to start with. (And that extension
+ *  must be active for this one to do anything useful)
  */
 class PicLens implements Extension {
 	public function receive_event(Event $event) {

contrib/pm/main.php

@@ -4,6 +4,10 @@
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
  * Description: Allow users to send messages to eachother
+ * Documentation:
+ *  PMs show up on a user's profile page, readable by that user
+ *  as well as board admins. To send a PM, visit another user's
+ *  profile page and a box will be shown.
  */
 
 class SendPMEvent extends Event {

contrib/random_image/main.php

@@ -4,7 +4,19 @@
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
  * Description: Do things with a random image
- * Link: http://trac.shishnet.org/shimmie2/wiki/Contrib/Extensions/RandomImage
+ * Documentation:
+ *  <b>Viewing a random image</b>
+ *  <br>Visit <code>/random_image/view</code>
+ *  <p><b>Downloading a random image</b>
+ *  <br>Link to <code>/random_image/download</code>. This will give
+ *  the raw data for an image (no HTML). This is useful so that you
+ *  can set your desktop wallpaper to be the download URL, refreshed
+ *  every couple of hours.
+ *  <p><b>Getting a random image from a subset</b>
+ *  <br>Adding a slash and some search terms will get a random image
+ *  from those results. This can be useful if you want a specific size
+ *  of random image, or from a category. You could link to
+ *  <code>/random_image/download/size:1024x768+cute</code>
  */
 
 class RandomImage implements Extension {

contrib/rating/main.php

@@ -3,7 +3,7 @@
  * Name: Image Ratings
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
- * Description: Allow users to rate images
+ * Description: Allow users to rate images "safe", "questionable" or "explicit"
  */
 
 class RatingSetEvent extends Event {

contrib/regen_thumb/main.php

@@ -4,6 +4,12 @@
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
  * Description: Regenerate a thumbnail image
+ * Documentation:
+ *  This adds a button in the image control section on an
+ *  image's view page, which allows an admin to regenerate
+ *  an image's thumbnail; useful for instance if the first
+ *  attempt failed due to lack of memory, and memory has
+ *  since been increased.
  */
 
 class RegenThumb implements Extension {

contrib/site_description/main.php

@@ -3,8 +3,10 @@
  * Name: Site Description
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
- * Description: Sets the "description" meta-info in the page header, for
- *              eg search engines to read
+ * Description: A description for search engines
+ * Documentation:
+ *  This extension sets the "description" meta tag in the header
+ *  of pages so that search engines can pick it up
  */
 class SiteDescription implements Extension {
 	public function receive_event(Event $event) {

contrib/svn_update/main.php

@@ -4,6 +4,12 @@
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
  * Description: Provides a button to check for updates
+ * Documentation:
+ *  This is a very risky idea, implemented without safeguards.
+ *  If you've done a clean SVN checkout, then updating will
+ *  normally work fine; but if you've made changes in one way,
+ *  and SVN has changed something in a different way, then there
+ *  will be conflicts and the site will die :(
  */
 
 class SVNUpdate implements Extension {

contrib/text_score/main.php

@@ -4,6 +4,11 @@
  * Author: Shish <webmaster@shishnet.org>
  * License: GPLv2
  * Description: Allow users to score images
+ * Documentation:
+ *  Similar to the Image Scores (Numeric) extension, but this one
+ *  uses an average rather than the sum of all votes, which means
+ *  that the score will be [-2 .. +2], and each integer in that
+ *  range has a label attached.
  */
 
 class TextScoreSetEvent extends Event {

ext/ext_manager/main.php

@@ -8,7 +8,7 @@
  */
 
 class ExtensionInfo { // {{{
-	var $ext_name, $name, $link, $author, $email, $description;
+	var $ext_name, $name, $link, $author, $email, $description, $documentation;
 
 	function ExtensionInfo($main) {
 		$matches = array();
@@ -25,6 +25,9 @@ class ExtensionInfo { // {{{
 			}
 			if(preg_match("/Link: (.*)/", $line, $matches)) {
 				$this->link = $matches[1];
+				if($this->link[0] == "/") {
+					$this->link = make_link(substr($this->link, 1));
+				}
 			}
 			if(preg_match("/Author: (.*) [<\(](.*@.*)[>\)]/", $line, $matches)) {
 				$this->author = $matches[1];
@@ -33,12 +36,21 @@ class ExtensionInfo { // {{{
 			else if(preg_match("/Author: (.*)/", $line, $matches)) {
 				$this->author = $matches[1];
 			}
-			if(preg_match("/(.*)Description: (.*)/", $line, $matches)) {
+			if(preg_match("/(.*)Description: ?(.*)/", $line, $matches)) {
 				$this->description = $matches[2];
 				$start = $matches[1]." ";
 				$start_len = strlen($start);
 				while(substr($lines[$i+1], 0, $start_len) == $start) {
-					$this->description .= substr($lines[$i+1], $start_len);
+					$this->description .= " ".substr($lines[$i+1], $start_len);
+					$i++;
+				}
+			}
+			if(preg_match("/(.*)Documentation: ?(.*)/", $line, $matches)) {
+				$this->documentation = $matches[2];
+				$start = $matches[1]." ";
+				$start_len = strlen($start);
+				while(substr($lines[$i+1], 0, $start_len) == $start) {
+					$this->documentation .= " ".substr($lines[$i+1], $start_len);
 					$i++;
 				}
 			}
@@ -46,6 +58,9 @@ class ExtensionInfo { // {{{
 				break;
 			}
 		}
+		if(is_null($this->link) && !is_null($this->documentation)) {
+			$this->link = make_link("ext_doc/{$this->ext_name}");
+		}
 	}
 
 	private function is_enabled($fname) {
@@ -81,6 +96,12 @@ class ExtManager implements Extension {
 			}
 		}
 
+		if(($event instanceof PageRequestEvent) && $event->page_matches("ext_doc")) {
+			$ext = $event->get_arg(0);
+			$info = new ExtensionInfo("contrib/$ext/main.php");
+			$this->theme->display_doc($event->page, $info);
+		}
+
 		if($event instanceof UserBlockBuildingEvent) {
 			if($event->user->is_admin()) {
 				$event->add_link("Extension Manager", make_link("ext_manager"));

ext/ext_manager/theme.php

@@ -43,5 +43,13 @@ class ExtManagerTheme extends Themelet {
 		$page->add_block(new NavBlock());
 		$page->add_block(new Block("Extension Manager", $html));
 	}
+
+	public function display_doc(Page $page, ExtensionInfo $info) {
+		$html = "<div style='margin: auto; text-align: left; width: 512px;'>".$info->documentation."</div>";
+		$page->set_title("Documentation for ".html_escape($info->name));
+		$page->set_heading(html_escape($info->name));
+		$page->add_block(new NavBlock());
+		$page->add_block(new Block("Documentation", $html));
+	}
 }
 ?>

themes/default/style.css

@@ -33,6 +33,10 @@ TD {
 	vertical-align: top;
 	text-align: center;
 }
+CODE {
+	background: #DEDEDE;
+	font-size: 0.8em;
+}
 #subtitle {
 	width: 256px;
 	font-size: 0.75em;