Test-Scratch-Wiki:Block Plugin Style Guide

In order to keep the Scratch Wiki looking neat, please follow the following style guide when writing on the wiki.

Feel free to fix any articles that do not conform to this guide.

This guide is intended for wiki editors, and includes guidelines on style as well as a little extra syntax. It thus serves a different purpose to Block Plugin/Syntax, which is intended for forum users and wiki editors alike.

= Style Guide =

Whitespace
 No:  I like this script: when flag clicked say [Hello!] Pretty, isn't it?
 * Always put a line break before and after the opening and closing tags.

Yes:  I like this script:

when gf clicked say [Hello!]




 * However, if you're writing a script with a single block, only use one line:
 * Yes:
 * when gf clicked

 No:  repeat (10) if  move (10) steps end stamp end Yes:  repeat (10) if  move (10) steps end stamp end 
 * Use indentation. Always indent by 4 spaces. (This is for consistency as much as for any other reason.)


 * Always put whitespace around inserts and embedded blocks. This is easier to read.

 No: <dd> stamp//Draws a picture! <dd>Yes: <dd> stamp // Draws a picture! </dl>
 * Always put spaces around the comment symbol " ".

Be Explicit
The block plugin will close brackets and c-blocks for you, in case you forget. Do not rely on this; always include properly formatted scripts in wiki articles. If Javascript is disabled then the source code will be displayed directly to the user, so the scratchblocks code in articles needs to be readable.

 <dd>No: <dd> repeat (10) move (10) steps stamp <dd>Yes: <dd> repeat (10) move (10) steps stamp end </dl>
 * Always include " " after a C block.

 <dd>No: <dd> if <<(x position) < [3]> and <(var) = [4 <dd>Yes: <dd> if <<(x position) < [3]> and <(var) = [4]>> </dl>
 * Always close brackets.

Misc

 * Warning: The wiki does not support double-colon syntax yet. Go bug scmb1 to update the plugin! :) --blob8108 12:04 20 September 2014

 <dd>No: <dd> set [foo v] to (user id) <dd>Yes: <dd> set [foo v] to (user id :: sensing) </dl>
 * Replace " " with " ". The user id block is deprecated, and may be removed from scratchblocks in the future.

Scratch 2.0 Blocks
Make sure you use the 2.0 versions of blocks (unless it's an article specifically about Scratch 1.4). This includes:

= Wiki-only features = There are some extra "hidden" features intended for use on the wiki only.

Ellipsis

 * The grey <sb>. . .</sb> ellipsis block represents a gap in a script. Use it!


 * Do not write the word "script", "scripts", any other obsolete block, or a comment saying "script goes here".

 <dd>No: <dd> forever if <> script end end <dd>No: <dd> forever if <> // script goes here end end <dd>Yes: <dd> forever if <> . . .   end end </dl>


 * Always put spaces between the dots: . This makes the block easier to read.

Inline Scratchblocks
You can place scratchblocks inside a sentence using the  tag, like this:
 * I'm rather fond of the <sb>stamp</sb> block in Scratch 2.0.

Producing:
 * I'm rather fond of the <sb>stamp</sb> block in Scratch 2.0.

Notes:
 * You can only use a single block in the inline tag, not a whole script.

 <dd>No: <dd> Use the "score" variable to keep track of... <dd>Yes: <dd> Use the <sb>(score)</sb> variable to keep track of... </dl>
 * Use inline scratchblocks to represent variable names, e.g. <sb>(score)</sb>:

 <dd>Yes: <dd> <sb>stamp</sb> <dd><sb>stamp</sb> </dl>
 * For block links, use inline scratchblocks instead of images:

 <dd>No: <dd> == The (username) block == <dd>Yes: <dd> == The username block == </dl>
 * Do not use inline scratchblocks in headings.

Colouring blocks

 * Warning: The wiki does not support double-colon syntax yet. Go bug scmb1 to update the plugin! :) --blob8108 12:04 20 September 2014

You can set the colour of blocks using secret hacks. This allows you to colour blocks that would normally appear obsolete, for example the "create clone" block from the Scratch 2.0 prototype.


 * create clone

By using a special hack, you can get the correct colour:


 * create clone :: control

Notes:

 <dd>No: <dd> create clone // category=control <dd>Yes: <dd> create clone :: control <dd> say (ultrasonic sensor :: extension) </dl>
 * For colouring blocks, do not use the deprecated comment syntax, which may be removed in the future. Use the more flexible double-colon syntax instead, which also supports reporters:

= External Links =
 * Complete List of Blocks
 * Test page