Difference between revisions of "Help:Hex"

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.

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.

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.

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>

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.

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

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

Numbered moves

Border

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

All possible fields

Source code

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