Difference between revisions of "Help:Hex"

Revision as of 13:04, 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 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.

<hex>
R11 C11 Q1 B:on
a1 a2 a3 a4
N:on
a5 a6 a7 a8
</hex>

• 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.

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.

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.