Difference between revisions of "Help:Hex"

From HexWiki
Jump to: navigation, search
("game mode", especially for commenting games)
(Setting up a certain position and some moves: changed the syntax to "common words" instead of cryptic abbreviations)
Line 87: Line 87:
 
== Setting up a certain position and some moves ==
 
== Setting up a certain position and some moves ==
  
When commenting a game you usually have some moves that lead to a certain position, and from this position you want some numbered moves. This can be done using the plain coordinates.
+
When you set up a position there are two common cases: replaying a game, or setting up an isolated position. These cases can be written easily using the following ''setup modes'':
 +
 
 +
* <tt>play</tt> is used for playing mode. The color of the stones alternates between red and blue.
 +
* <tt>red</tt> is used for putting red stones on the board. When switching to <tt>play</tt> mode later, the first move will be red's.
 +
* <tt>blue</tt> is used for putting blue stones on the board. When switching to <tt>play</tt> mode later, the first move will be blue's.
 +
 
 +
All coordinates that follow the setup mode are processed according to that mode.
 +
The following diagram shows how the setup modes can be used.
  
 
<pre>
 
<pre>
 
&lt;hex>
 
&lt;hex>
R11 C11 Q1 B:on
+
R5 C9 labels borders
a1 a2 a3 a4
+
play a1 a2 a3 a4
N:on
+
red numbered c1 c2 c3 c4 unnumbered
a5 a6 a7 a8
+
blue e1 e2 e3 e4
 +
play numbered g1 g2 g3 g4 unnumbered
 +
red play i1 i2 i3 i4
 
&lt;/hex>
 
&lt;/hex>
 
</pre>
 
</pre>
 
* The first line sets up the board as usual.
 
* The second line sets up the position with alternating colors.
 
* The third line says that all the following moves will be numbered.
 
* The fourth line finally sets up the numbered moves, again with alternating colors.
 
  
 
<hex>
 
<hex>
R11 C11 Q1 B:on
+
R5 C9 labels borders
a1 a2 a3 a4
+
play a1 a2 a3 a4
N:on
+
red numbered c1 c2 c3 c4 unnumbered
a5 a6 a7 a8
+
blue e1 e2 e3 e4
 +
play numbered g1 g2 g3 g4 unnumbered
 +
red play i1 i2 i3 i4
 
</hex>
 
</hex>
  
The nice point is that for the next diagram you just have to remove the '''N:on''' to have the final position without numbers, so you can easily add the next moves.
+
Note:
 +
* The <tt>play</tt> mode keeps the color from before. So when you write <tt>blue</tt> (as for e1, e2, e3, e4) and then <tt>play</tt> (as for g1), the first move is blue.
 +
* To change the color of the next move you can write <tt>red</tt> <tt>play</tt>, as shown for i1.
 +
* The setup modes can be mixed freely with <tt>numbered</tt> and <tt>unnumbered</tt>.
 +
* The setup modes are useful for setting up diagrams from game records since you don't need to write the color in front of every move. Just the coordinate is enough.
 +
* The setup modes <tt>red</tt> and <tt>blue</tt> are also useful for setting up individual positions.
  
 
== Setting up a whole line at once ==
 
== Setting up a whole line at once ==

Revision as of 14:32, 4 November 2012

This is the documentation for the MediaWiki plug-in for drawing Hex diagrams.

Syntax

Hex diagrams are specified using the <hex>...</hex> tag. Inside this tag, a series of words describes the diagram itself. The first letter of each word is called the command, and the remaining letters are its arguments. There are commands for specifying the board size and for putting stones on the board.

Examples

  • <hex> R5 C5 </hex> draws an empty hex board with 5 rows and 5 columns.

Setting up the board

Before doing anything else, you have to say how large the board is. Each board has a number of rows (which go horizontally) and columns (which go vertically). In addition to that, you can say that you want the rows and colums labelled with their letters and numbers.

The commands for setting up the board all take a single numeric argument. The commands are:

  • R: Specifies the number of rows of the board.
  • C: Specifies the number of columns of the board.
  • Q: Specifies whether the coordinates should be printed next to the board. Zero means no, any other number means yes. By default, they are not shown.

Examples

  • R5 sets the number of rows to 5.
  • Q1 makes the coordinates appear next to the board.
  • Q0 explicitly makes the coordinates disappear.
  • <hex>R5 C5 Q1</hex> creates a board with five rows and five colums, which are all labelled.
abcde12345

Setting up single stones

The commands for setting up stones all take a coordinate as their argument. Coordinates are written in the form f7, where f is the column and 7 is the row.

The commands are:

  • B for a blue stone.
  • R for a red stone.
  • H for a horizontal stone (equivalent to B).
  • V for a vertical stone (equivalent to R).
  • S or * for a star.
  • P or + for a plus.

When you want to add move numbers, put a single digit (0-9) between the command and the coordinate, for example R5e4 when Red puts his fifth move onto e4.

It is also possible to link stones to any other wiki page. For that, use the form [[Link_target|Word]], where Word is used to setup the stone and Link_target is where you want to arrive when you click the link.

Examples

  • Ba4 puts a blue stone (B) in the first column (a) of the fourth row (4).
  • R7b1 puts a red stone (R) in the second column (b) of the first row (1) and labels it with a seven (7).
  • [[#Setting_up_single_stones|Ba5]] puts a blue stone on the board and links it to the section called Setting up single stones on the same page. Note that you cannot use space characters in the link.
abcde123457
WARNING: Unrecognized token: [[#Setting_up_single_stones|Ba5]]

Automatically numbered moves

There is a special command (M) for setting up numbered sequences of moves. The first of these moves is for Red and is labelled with a 1. After each M command, the color changes and the move number is increased automatically.

If you want to enter a sequence of moves that starts with a blue move, write MB. This changes the color without affecting the move number or the stones on the board.

When you want to show a complete game, it can be annoying to replace the H... and V... commands with M. For this reason, there is another feature, which automatically numbers the following stones. It is switched on with N:on and off with (you guessed it) N:off.

Limitations

Currently, the number of moves is restricted to 10, but this may be extended if there is the need for it. But before you request this change, please ask yourself whether you really need it. Ten moves is a lot, and especially when analyzing games, it would be easier for the reader if you split the moves into several diagrams.

Examples

  • MR Ma1 Ma2 Ma3 Mb4 is a sequence of four moves, starting with a red 1.
  • M5c1 Mc2 Mc3 are three moves, starting with a red 5.
  • MB Me1 Me2 Me3 are three moves, starting with a blue 1.
  • N:on Rg1 Bg7 N:off Rg4 results in two numbered moves on g1 and g7, and one unnumbered move at g4.
abcdefghijk12345678910111591226103711413

Setting up a certain position and some moves

When you set up a position there are two common cases: replaying a game, or setting up an isolated position. These cases can be written easily using the following setup modes:

  • play is used for playing mode. The color of the stones alternates between red and blue.
  • red is used for putting red stones on the board. When switching to play mode later, the first move will be red's.
  • blue is used for putting blue stones on the board. When switching to play mode later, the first move will be blue's.

All coordinates that follow the setup mode are processed according to that mode. The following diagram shows how the setup modes can be used.

<hex>
R5 C9 labels borders
play a1 a2 a3 a4
red numbered c1 c2 c3 c4 unnumbered
blue e1 e2 e3 e4
play numbered g1 g2 g3 g4 unnumbered
red play i1 i2 i3 i4
</hex>
abcdefghi1234515263748
WARNING: Unrecognized token: borders

Note:

  • The play mode keeps the color from before. So when you write blue (as for e1, e2, e3, e4) and then play (as for g1), the first move is blue.
  • To change the color of the next move you can write red play, as shown for i1.
  • The setup modes can be mixed freely with numbered and unnumbered.
  • The setup modes are useful for setting up diagrams from game records since you don't need to write the color in front of every move. Just the coordinate is enough.
  • The setup modes red and blue are also useful for setting up individual positions.

Setting up a whole line at once

In many cases, there are many stones on the board, and it would be annoying to write one word for each stone. For this reason, there exists a short-cut for drawing a complete line. If a word starts with a number, followed by a colon (:) and a list of cell contents, the whole line can be drawn with only one command. The valid types of cell contents are:

  • R or V for red stones,
  • B or H for blue stones,
  • * or S for stars,
  • + or P for plus,
  • _ for an empty cell.

Limitations

  • Stones with numbers cannot be put using this command. Instead, use the commands for putting a single stone or for putting a series of moves.

Examples

  • 3:__BBRRBBRR__* sets up the first 13 stones of the third row. The first two are empty, the next two are blue, and so on.
abcdefghijklm123

Formatting diagrams usefully

Depending on the situation and the intent of a diagram, it may be formatted in different styles. Large diagrams should be distributed over several lines, to make editing and reading easier. The suggested format is:

  1. Board size and coordinates,
  2. Setup stones: One line per color,
  3. The moves in the order they are played.

See the diagrams below for examples.

Examples for Complete Diagrams

A simple board with stones in all four corners

abcde12345

And the same with stones that are linked to other pages.

abcde12345
WARNING: Unrecognized token: [[Red|Ra1]]
WARNING: Unrecognized token: [[Red|Re5]]
WARNING: Unrecognized token: [[Blue|Be1]]
WARNING: Unrecognized token: [[Blue|Ba5]]

Numbered moves

abcde1234542135

Border

You can draw a colored border around the diagram by giving the command B:on.

abcde1234512345
WARNING: Invalid cell name: :on

All possible fields

abcdefghijk12341234567891234567891234567891011

Source code

The full source code of the plug-in is available here.