Complete rewrite of the module's help,

adding more attention to the examples,
and make the description be disconnected
from PHPBB. Also making it support translation.

README

-README for bbcode
-=================
+Drupal bbcode.module README
+==============================================================================
 
-This module lets users use bbcode in their posts. This is a safer way
-of letting people include quite flexible HTML in their posts, along
-with it being slightly easier for people to get the hang of.
+The Drupal bbcode.module adds a BBCode filter to Drupal, with which you
+can use HTML like tags as an alternative of HTML itself to add markup
+to your posts. BBCode is easier then HTML and blocks malicious users
+most of the time from screwing up the site formatting.
 
-In accordance with standard bbcode, this module automagically creates
-links from typed URLs (you don't have to go [url]).
+See the help screen of the module (or the code) for information on what
+tags and variants are supported. The implementation is not necessarily the
+same as the original BBCode implementaion.
+ 
+Note that this filter also recognizes and converts URLs and email addresses
+to links.
 
 Installation
-============
+------------------------------------------------------------------------------
+ 
+ Required:
   - Copy bbcode.module to modules/
- - Enable the module as usual from Drupal's admin pages.
- - Optional. Install the compose_tips module in order to inform your users about bbcode
+  - Enable the module as usual from Drupal's admin pages
+ 
+ Optional:
+  - Install the compose_tips module in order to inform your
+    users about the possibility of BBCode usage
 
 Configuration
-=============
-There is no configuration. It just works. :)
-To turn it on and off, enable/disable the module.
+------------------------------------------------------------------------------
+
+This module needs no configuration. After enabled it filters all text
+displayed, so you can turn it off by disabling the module. If you would
+like to use BBCode as an alternative to HTML, you should set Drupal to
+use the "Escape HTML" filter, so no HTML tags will be allowed in posts,
+just BBCode tags.
+
+Credits / Contact
+------------------------------------------------------------------------------
 
-Bugs/comments/suggestions/patches to drupal-bbcode@almaw.com
+The original author of this module is Alastair Maw, who can be reached at
+drupal-bbcode[at]almaw.com. Gabor Hojtsy (goba[at]php.net) also contributed
+to the module.
 
+TODO
+------------------------------------------------------------------------------
 
-TODO: - Configuration of which bbcode tags are allowed.
+ - Do not allow users to screw up the HTML output with
+   malicious parameters (color, size, url, etc.)
+ - Support block level [code] formatting, as shown on the help screen
+ - Support [php] code blocks (syntax highlighted)
+ - Configuration of which bbcode tags are allowed

bbcode.module

@@ -9,105 +9,311 @@ function bbcode_compose_tips() {
   return array(bbcode_help());
 }
 
+// Note that there are some plans to make this text modular,
+// displayiny only the parts of the help correspondnig to the
+// current situation (after the restriction feature on bbcode
+// tags will be implemented)
 function bbcode_help () {
-// help copied from phpbb (C) the PHPBB GROUP and released under the GPL
-ob_start();
-?>
-<a id="bbcodeTop"></a>
+
+  $bbcode_help = <<<END_HELP_TEXT
 <h1>BBCode Guide</h1>
-<h3>Introduction</h2>
-<p><a name="0"></a><b>What is BBCode?</b><br />
-BBCode is a special implementation of HTML. BBCode itself is similar in style to HTML,
-tags are enclosed in square braces [ and ] rather than &lt; and &gt; and it offers greater control
-over what and how something is displayed. You may find the following guide useful.</p>
-
-<h2>Text Formatting</h2>
-<p><a id="bbcode1"></a><b>How to create bold, italic and underlined text</b><br />
-BBCode includes tags to allow you to quickly change the basic style of your text.
-This is achieved in the following ways: <ul><li>To make a piece of text bold
-enclose it in <b>[b][/b]</b>, eg. <br /><br /><b>[b]</b>Hello<b>[/b]</b><br /><br />will become
-<b>Hello</b></li><li>For underlining use <b>[u][/u]</b>, for example:<br /><br /><b>[u]</b>
-Good Morning<b>[/u]</b><br /><br />becomes <u>Good Morning</u></li><li>
-To italicise text use <b>[i][/i]</b>, eg.<br /><br />This is <b>[i]</b>Great!<b>[/i]</b><br /><br />
-would give This is <i>Great!</i></li></ul></p>
-
-<p><a id="bbcode2"></a><b>How to change the text colour or size</b><br />
-To alter the color or size of your text the following tags can be used.
-Keep in mind that how the output appears will depend on the viewers browser and system:
- <ul><li>Changing the colour of text is achieved by wrapping it in
- <b>[color=][/color]</b>. You can specify either a recognised colour name
-  (eg. red, blue, yellow, etc.) or the hexadecimal
-  triplet alternative, eg. #FFFFFF, #000000. For example,
-  to create red text you could use:<br /><br /><b>[color=red]</b>Hello!<b>[/color]</b><br />
-  <br />or<br /><br /><b>[color=#FF0000]</b>Hello!<b>[/color]</b><br />
-  <br />will both output <span style="color:red">Hello!</span></li>
-  <li>Changing the text size is achieved in a similar way using
-  <b>[size=][/size]</b>. This tag is dependent on the
-  template you are using but the recommended format is a
-   numerical value representing the text size in pixels,
-   starting at 1 (so tiny you will not see it) through to 29
-   (very large). For example:<br /><br /><b>[size=9]</b>SMALL<b>[/size]</b><br />
-   <br />will generally be <span style="font-size:9px">SMALL</span><br />
-   <br />whereas:<br /><br /><b>[size=24]</b>HUGE!<b>[/size]</b><br />
-   <br />will be <span style="font-size:24px">HUGE!</span></li></ul></p>
-
-<p><a id="bbcode3"></a><b>Can I combine formatting tags?</b><br />
-Yes, of course you can, for example to get someones attention you may write:
-<br /><br /><b>[size=18][color=red][b]</b>LOOK AT ME!<b>[/b][/color][/size]</b>
-<br /><br />this would output <span style="color:red;font-size:18px">
-<b>LOOK AT ME!</b></span><br /><br />We don't
-recommend you output lots of text that looks like this though!
-Remember it is up to you, the poster to ensure
-tags are closed correctly. For example the following is
-incorrect:<br /><br /><b>[b][u]</b>This is wrong<b>[/b][/u]</b></p>
-
-<h2>Outputting fixed-width text</h2>
-
-<p><a id="bbcode5"></a><b>Outputting code or fixed width data</b><br />
-If you want to output a piece of code or in fact anything that requires a
-fixed width, eg. Courier type font you should enclose the text in
-<b>[code][/code]</b> tags, eg.<br />
-<br /><b>[code]</b>echo "This is some code";<b>[/code]</b>
-<br /><br />All formatting used within <b>[code][/code]</b>
-tags is retained when you later view it.</p>
-
-
-<h2>Generating lists</h2>
-<p><a id="bbcode6"></a><b>Creating an Un-ordered list</b><br />
-BBCode supports two types of lists, unordered and ordered. They are essentially the same as their HTML equivalents. An unordered list ouputs each item in your list sequentially one after the other indenting each with a bullet character. To create an unordered list you use <b>[list][/list]</b> and define each item within the list using <b>[*]</b>. For example to list your favorite colours you could use:<br /><br /><b>[list]</b><br /><b>[*]</b>Red<br /><b>[*]</b>Blue<br /><b>[*]</b>Yellow<br /><b>[/list]</b><br /><br />This would generate the following list:<ul><li>Red</li><li>Blue</li><li>Yellow</li></ul></p>
-
-<p><a id="bbcode7"></a><b>Creating an Ordered list</b><br />
-The second type of list, an ordered list gives you control over what is output before each item. To create an ordered list you use <b>[list=1][/list]</b> to create a numbered list or alternatively <b>[list=a][/list]</b> for an alphabetical list. As with the unordered list items are specified using <b>[*]</b>. For example:<br /><br /><b>[list=1]</b><br /><b>[*]</b>Go to the shops<br /><b>[*]</b>Buy a new computer<br /><b>[*]</b>Swear at computer when it crashes<br /><b>[/list]</b><br /><br />will generate the following:<ol type="1"><li>Go to the shops</li><li>Buy a new computer</li><li>Swear at computer when it crashes</li></ol>Whereas for an alphabetical list you would use:<br /><br /><b>[list=a]</b><br /><b>[*]</b>The first possible answer<br /><b>[*]</b>The second possible answer<br /><b>[*]</b>The third possible answer<br /><b>[/list]</b><br /><br />giving<ol type="a"><li>The first possible answer</li><li>The second possible answer</li><li>The third possible answer</li></ol></p>
+
+<h2>Introduction</h2>
+
+<p>
+ BBCode allows you to specify formatting to some parts of your text,
+ even if you are not allowed to use HTML in your posts. BBCode is
+ originated from the forum software named PHPBB, and Drupal has a
+ special implementation of it.
+</p>
+<p>
+ In BBCode terms, you use "tags" to add formatting to your text. Every
+ tag is enclosed in [ and ]. In case you need to mark some region in
+ your text, you need to use an opening tag and a closing tag. Closing
+ tags start with [/, as you will see in the examples below. In case you
+ mistype a tag or forget to close it, you will not get the desired
+ formatting.
+</p>
+
+<h2>Simple text formatting</h2>
+
+<p>
+ BBCode allows you to make some parts of your texts stand out from the
+ context by adding <strong>[b]</strong>old, <strong>[i]</strong>talic
+ and <strong>[u]</strong>nderlined formatting to them. The
+ <strong>[color]</strong> and <strong>[size]</strong> tags allow you to
+ change the color and size of some portion of the text you enclose with
+ these tags. Both require a parameter, which you can define after the name
+ of the tag and an equal sing. You should not repeat the parameter in the
+ closing tag!
+</p>
+
+<p>
+ You can specify any recognized color name (red, blue, green, white, etc.)
+ or a hexadecimal color value (#CDCDCD, #FFFFFF, etc.) as the parameter of
+ a <strong>[color]</strong> tag. The <strong>[size]</strong> tag allows you
+ to set the font size between 10 and 30, 10 being the smallest size.
+ Note that using too big text is often considered shouting and it is most
+ of the time not a good idea to try to drive more attention to your post
+ this way.
+</p>
+
+<table>
+ <tr>
+  <th>usage</th><th>display</th>
+ </tr>
+ <tr>
+  <td>I [b]need to do[/b] this by the weekend</td>
+  <td>I <strong>need to do</strong> this by the weekend</td>
+ </tr>
+ <tr>
+  <td>John said, that [i]we should[/i] ask her</td>
+  <td>John said, that <em>we should</em> ask her</td>
+ </tr>
+ <tr>
+  <td>I [u]would not like to[/u] offend you</td>
+  <td>I <span style="text-decoration: underline;">would not like to</span> offend you</td>
+ </tr>
+ <tr>
+  <td>Jane was at [color=blue]the coast[/color]</td>
+  <td>Jane was at <span style="color: blue;">the coast</span></td>
+ </tr>
+ <tr>
+  <td>Joe was in [color=#00FF00]the forest[/color]</td>
+  <td>Joe was in <span style="color: #00FF00;">the forest</span></td>
+ </tr>
+ <tr>
+  <td>You said: [size=20]HEY![/size]</td>
+  <td>You said: <span style="font-size: 20px;">HEY!</span></td>
+ </tr>
+</table>
 
 <h2>Creating Links</h2>
 
-<p><a id="bbcode8"></a><b>Linking to another site</b>
-BBCode supports a number of ways of creating URIs, Uniform Resource Indicators better known as URLs.<ul><li>The first of these uses the <b>[url=][/url]</b> tag, whatever you type after the = sign will cause the contents of that tag to act as a URL. For example to link to phpBB.com you could use:<br /><br /><b>[url=http://www.phpbb.com/]</b>Visit phpBB!<b>[/url]</b><br /><br />This would generate the following link, <a href="http://www.phpbb.com/" target="_blank">Visit phpBB!</a> You will notice the link opens in a new window so the user can continue browsing the forums if they wish.</li><li>If you want the URL itself displayed as the link you can do this by simply using:<br /><br /><b>[url]</b>http://www.phpbb.com/<b>[/url]</b><br /><br />This would generate the following link, <a href="http://www.phpbb.com/" target="_blank">http://www.phpbb.com/</a></li><li>Additionally phpBB features something called <i>Magic Links</i>, this will turn any syntatically correct URL into a link without you needing to specify any tags or even the leading http://. For example typing www.phpbb.com into your message will automatically lead to <a href="http://www.phpbb.com/" target="_blank">www.phpbb.com</a> being output when you view the message.</li><li>The same thing applies equally to email addresses, you can either specify an address explicitly for example:<br /><br /><b>[email]</b>no.one@domain.adr<b>[/email]</b><br /><br />which will output <a href="emailto:no.one@domain.adr">no.one@domain.adr</a> or you can just type no.one@domain.adr into your message and it will be automatically converted when you view.</li></ul>As with all the BBCode tags you can wrap URLs around any of the other tags such as <b>[img][/img]</b> (see next entry), <b>[b][/b]</b>, etc. As with the formatting tags it is up to you to ensure the correct open and close order is following, for example:<br /><br /><b>[url=http://www.phpbb.com/][img]</b>http://www.phpbb.com/images/phplogo.gif<b>[/url][/img]</b><br /><br />is <u>not</u> correct which may lead to your post being deleted so take care.</p>
-
-<h2>Showing images in posts</h2>
-
-<p><a id="bbcode9"></a><b>Adding an image to a post</b><br />
-BBCode incorporates a tag for including images in your posts.
-Two very important things to remember when using this tag are;
-many users do not appreciate lots of images being shown in posts
- and secondly the image you display must already be available
- on the internet (it cannot exist only on your computer for example,
- unless you run a webserver!). There is currently no way of storing
- images locally with phpBB (all these issues are expected to
- be addressed in the next release of phpBB).
- To display an image you must surround the URL pointing to the
- image with <b>[img][/img]</b> tags. For example:<br /><br />
- <b>[img]</b>http://www.phpbb.com/images/phplogo.gif<b>[/img]</b>
- <br /><br />As noted in the URL section above you can wrap an image
- in a <b>[url][/url]</b> tag if you wish, eg.<br /><br />
- <b>[url=http://www.phpbb.com/][img]</b>http://www.phpbb.com/images/phplogo.gif<b>[/img][/url]</b>
- <br /><br />would generate:<br />
- <br /><a href="http://www.phpbb.com/" target="_blank"><img src="http://www.phpbb.com/images/phplogo.gif" border="0" alt="" /></a></p>
+<p>
+ You have multiple options to specify links to other destinations in
+ your posts. All external links will open in new windows.
+</p>
 
-<?php
-$o = ob_get_contents();
-ob_end_clean();
-return $o;
+<p>
+ Drupal recognizes URLs (Uniform Resource Locators) used in your posts, and
+ automatically replaces them with links. For URLs starting with "www" or
+ "ftp" (eg. www.example.com) there is no need for a protocol specification,
+ but you need to specify a protocol for other types of addresses
+ (eg. example.com).
+</p>
+<p>
+ Drupal also recognizes email addresses in posts automatically, but for compatbility
+ with the common BBCode implementations, also provides the <strong>[email]</strong> tag
+ to mark email addresses. There is no spam protection applied to the email addresses!
+</p>
+<p>
+ You can use the <strong>[url]</strong> tag with a parameter to specify a link with
+ a meaningful text to click on. If you use the url tag without the parameter,
+ then the enclosed text is assumed to be an URL, and a link is created to that
+ destination.  
+</p>
+
+<table>
+ <tr>
+  <th>usage</th><th>display</th>
+ </tr>
+ <tr>
+  <td>For more examples, visit www.example.com</td>
+  <td>For more examples, visit <a href="http://www.example.com" target="_blank">www.example.com</a></td>
+ </tr>
+ <tr>
+  <td>For more examples, visit http://example.com</td>
+  <td>For more examples, visit <a href="http://example.com" target="_blank">http://example.com</a></td>
+ </tr>
+ <tr>
+  <td>If you have questions ask me at joe@example.com</td>
+  <td>If you have questions ask me at <a href="mailto:joe@example.com">joe@example.com</a></td>
+ </tr>
+ <tr>
+  <td>If you have questions ask me at [email]joe@example.com[/email]</td>
+  <td>If you have questions ask me at <a href="mailto:joe@example.com">joe@example.com</a></td>
+ </tr>
+ <tr>
+  <td>We use [url=http://example.com/]the example site[/url] in these examples</td>
+  <td>We use <a href="http://example.com/" target="_blank">the example site</a> in these examples</td>
+ </tr>
+ <tr>
+  <td>We use [url]http://example.com/[/url] in these examples</td>
+  <td>We use <a href="http://example.com/" target="_blank">http://example.com/</a> in these examples</td>
+ </tr>
+</table>
+
+<h2>Displaying images</h2>
+
+<p>
+ The <strong>[img]</strong> tag allows you to display an image in your
+ post. You need to specify an URL to the image, so it needs to be
+ accessible somewhere on the internet. Beware of adding too big
+ images to your text, or otherwise the page will load very slowly!
+</p>
+
+<p>
+ If you enclose an URL in an <strong>[img]</strong> tag, then it will
+ be replaced with code to display the image. For example <code>A good
+ screenshot: [img]http://example.com/screenshot.png[/img]</code>
+ will show you the screenshot (if it exists). 
+</p>
+<p>
+ You can also specify the desired display dimensions of the image with
+ adding a dimension parameter to the <strong>[img]</strong> tag. <code>A
+ good screenshot: [img=640x480]http://example.com/screenshot.png[/img]</code>
+ will display the image in 640x480 (though the full image will be
+ downloaded). Do not use this to show a thumbnail of an image!
+</p>
+
+<p>
+ You are free to link an image to an external destination by enclosing
+ the <strong>[img]</strong> tag with an <strong>[url]</strong> tag: <code>See
+ [url=http://example.com][img]http://example.com/screenshot.png[/img][/url]</code>.
+</p>
+
+<h2>Ordered and unordered lists</h2>
+
+<p>
+ The simplest list type is the unordered list, which means that there is
+ no numbering applied to the elements. You can make such a list by enclosing
+ the list elements in <strong>[list]</strong> opening and closing tags.
+ Specify the start of one element with the <strong>[*]</strong> list element
+ marker, which has no closing tag pair.
+</p>
+
+<p>
+ To create an ordered list, you should add a parameter to the [list]
+ list tag specifying what type of ordered list you would like to see.
+ The possible parameters are "i", "I", "1", "a", and "A" which all
+ correspond to the display of the first list element.
+</p>
+
+<table>
+ <tr>
+  <th>usage</th><th>display</th>
+ </tr>
+ <tr>
+  <td><pre>
+I love
+ [list]
+  [*]Oranges
+  [*]Apples
+  [*]Bananas
+ [/list]
+</pre></td>
+  <td>
+   I love 
+   <ul>
+    <li>Oranges</li>
+    <li>Apples</li>
+    <li>Bananas</li>
+   </ul>
+  </td>
+ </tr>
+ <tr>
+  <td><pre>
+I love
+ [list=I]
+  [*]Oranges
+  [*]Apples
+  [*]Bananas
+ [/list]
+</pre></td>
+  <td>
+   I love 
+   <ol style="list-style-type: upper-roman;">
+    <li>Oranges</li>
+    <li>Apples</li>
+    <li>Bananas</li>
+   </ol>
+  </td>
+ </tr>
+ <tr>
+  <td><pre>
+I love
+ [list=1]
+  [*]Oranges
+  [*]Apples
+  [*]Bananas
+ [/list]
+</pre></td>
+  <td>
+   I love 
+   <ol style="list-style-type: decimal;">
+    <li>Oranges</li>
+    <li>Apples</li>
+    <li>Bananas</li>
+   </ol>
+  </td>
+ </tr>
+</table>
+
+<h2>Fixed-width text and block formatting</h2>
+
+<p>
+ You can use the <strong>[code]</strong> tag to add an inline fixed-width
+ formatted part or to add a block of (usually program) code. If there is
+ any newline present between the opening and closing tags, then a block
+ will be displayed.
+</p>
+
+<table>
+ <tr>
+  <th>usage</th><th>display</th>
+ </tr>
+ <tr>
+  <td>Edit your [code]robots.txt[/code] file</td>
+  <td>Edit your <code>robots.txt</code> file</td>
+  </td>
+ </tr>
+ <tr>
+  <td>
+An HTML title example:<br />
+[code]<br />
+&lt;head&gt;<br />
+&nbsp;&lt;title&gt;Page Title&lt;/title&gt;<br />
+&lt;/head&gt;<br />
+[/code]
+  </td>
+  <td>
+An HTML title example:<br />
+<div class="codeblock"><code>
+&lt;head&gt;<br />
+&nbsp;&lt;title&gt;Page Title&lt;/title&gt;<br />
+&lt;/head&gt;<br />
+</code>
+  </td>
+ </tr>
+</table>
+
+<h2>Using multiple formatting tags</h2>
+
+<p>
+ You can apply more than one formatting specification to a portion of some
+ text. <code>I was at [b][i]the coast[/i][/b]</code> will be
+ rendered as <code>I was at <strong><em>the coast</em></strong></code> for
+ example.
+</p>
+
+<p>
+ Make sure that you take care of the proper order of the opening and closing
+ tags. You should close the tags in the opposite order in which you opened
+ them. Otherwise you might get very strange rendering results. Also check
+ your post with the preview function before submiting it to discover possible
+ formatting errors due to improper BBCode usage.
+</p>
+
+<p>
+ There are some exceptions where you cannot add more BBCode tags. Examples
+ of these include the contents of the <strong>[img]</strong> tag, which by
+ definition should contain an URL only. BBCode tags are also disallowed
+ inside <strong>[code]</strong> tags, and you cannot apply some formatting
+ to all list items by wrapping the list with that formatting tag.
+</p>
+END_HELP_TEXT;
+  return t($bbcode_help);
 }
 
 function bbcode_filter($body) {