Difference between revisions of "New board diagrams"

From HexWiki
Jump to: navigation, search
(explanation of new board code)
 
m (typo)
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
 
+
''This page is about the new diagram facility that was added to HexWiki in August 2015 and updated in December 2020.''
−
''This page is about the new diagram facility that was added in August 2015.''
+
 
''For information on the old diagram facility, see [[Help:Hex]].''
 
''For information on the old diagram facility, see [[Help:Hex]].''
 
''Both ways of making diagrams will work, but the new way is recommended.''
 
''Both ways of making diagrams will work, but the new way is recommended.''
  
 +
== Basic example ==
  
−
To display a board diagram, include a '''<hexboard>''' tag,
+
To make a simple board diagram on any HexWiki page, include a '''<hexboard>''' tag,
 
specifying the board size in the '''size''' attribute (e.g. 5x7)
 
specifying the board size in the '''size''' attribute (e.g. 5x7)
−
and the board position in the '''contents''' attribute.
+
and the board contents in the '''contents''' attribute. For example:
 +
 
 +
<nowiki><hexboard size="3x3" contents="R a1 b2 B c1"/></nowiki>
 +
 
 +
<hexboard size="3x3" contents="R a1 b2 B c1"/>
  
 
Board sizes from 0 to 26 are supported.
 
Board sizes from 0 to 26 are supported.
Line 16: Line 20:
 
* B  (to place blue pieces)
 
* B  (to place blue pieces)
 
* E  (to mark a cell as empty)
 
* E  (to mark a cell as empty)
 +
* S  (to mark a cell as shaded &mdash; see [[#Shading]] below)
  
 
When a cell name is encountered, that cell will be marked
 
When a cell name is encountered, that cell will be marked
−
with the most recently mentioned color (R/B/E).
+
with the most recently mentioned contents (R/B/E/S).
−
To include an annotation on a cell (a number, star, or plus sign),
+
−
include it before the cell name, with a colon between the annotation
+
−
and the cell.
+
  
−
By default, coordinates will be shown above and to the left of the board.
+
== Labels ==
−
If you do not wish to show these, specify '''coords="hide"'''.
+
  
−
Remember to close the tag!
+
To add a label to a cell,
 +
include it before the cell name, with a colon between the label
 +
and the cell. For example:
  
−
'''There is now a graphical tool to create these tags: http://hexwiki.amecy.com/board_gui.html  It lets you set up a board, then generates a tag that you can copy and paste.'''  Click on a piece type to choose it, then click on a board cell to place that piece on the cell.
+
<nowiki><hexboard size="3x4"
 +
  contents="R arrow(12):a1 b1 B a2 R 1:c1 B 2:b3 R 3:d2 E *:c2 *:d1 *:c3 *:d3"
 +
  /></nowiki>
  
 +
<hexboard size="3x4"
 +
  contents="R arrow(12):a1 b1 B a2 R 1:c1 B 2:b3 R 3:d2 E *:c2 *:d1 *:c3 *:d3"
 +
  />
  
−
== Example 1 ==
+
The possible labels are:
  
−
<nowiki><hexboard size="3x3" contents="" /></nowiki>
+
* numbers (1, 2, 3, etc.)
 +
* a single upper- or lowercase letter (a, b, c, and A, B, C, etc.)
 +
* a star (*)
 +
* a plus sign (+)
 +
* a minus sign (-)
 +
* arrows, written as "arrow(''n'')", where ''n'' is an hour on the clock, i.e., 1, 2, ..., 12. The arrow points in the corresponding clock direction.
 +
* You can also use the Unicode characters "↗", "→", "↘", "↓", "↙", "←", "↖", and "↑" to specify arrows pointing in the direction of 2, 3, 4, 6, 8, 9, 10, and 12 o'clock, respectively. (Unfortunately there aren't enough Unicode arrows to also cover 1, 5, 7, and 11 o'clock. You have to use the "arrow(''n'')" notation for these).
  
 +
Both empty cells and occupied cells can be labelled. To remove a label, just specify the corresponding cell again without a label.
  
−
<hexboard size="3x3" contents="" />
+
== Set expressions ==
  
 +
Instead of a single cell, it is also possible to specify a set of cells. For example:
  
−
== Example 2 ==
+
<nowiki><hexboard size="5x5"
 +
  contents="R line(a1,a5,e1) B area(b5,e5,e3,d3)"
 +
  /></nowiki>
  
−
  <nowiki><hexboard
+
<hexboard size="5x5"
−
  size="5x5"
+
  contents="R line(a1,a5,e1) B area(b5,e5,e3,d3)"
−
   contents="R c1 b3 a5  B a1 e5"
+
  />
 +
 
 +
The following set expressions are available:
 +
 
 +
=== Basic set expressions ===
 +
 
 +
* "all": specifies the set of all cells on the board.
 +
* "none": specifies the empty set of cells.
 +
* A cell name, such as a1, specifies the set consisting of that one cell.
 +
* line(cell₁,cell₂): the set of all cells whose ''center'' lies on the line segment connecting the centers of cell₁ and cell₂. More generally, line(cell₁,cell₂,...,cellₙ) specifies a multiline, i.e., a line from cell₁ to cell₂, followed by a line from cell₂ to cell₃, and so on.
 +
* cell₁--cell₂--...--cellₙ is a synonym of line(cell₁,cell₂,...,cellₙ).
 +
* area(cell₁,cell₂,...,cellₙ): the set of cells whose ''center'' lies on the border or in the inside of the polygon with vertices cell₁, cell₂, ..., cellₙ.
 +
 
 +
The cells on a line do not need to be adjacent, for example:
 +
  <nowiki><hexboard size="5x9"
 +
   contents="R line(a1,i5) B line(a4,g1)"
 
   /></nowiki>
 
   /></nowiki>
 +
<hexboard size="5x9"
 +
  contents="R line(a1,i5) B line(a4,g1)"
 +
  />
 +
It does not matter whether the area is described by a clockwise or counterclockwise boundary. Also, the polygon specified by "area" does not need to be convex. For example:
 +
<nowiki><hexboard size="5x9"
 +
  contents="R area(a5,c5,e3,g3,g5,i5,i1,e1)"
 +
  /></nowiki>
 +
<hexboard size="5x9"
 +
  contents="R area(a5,c5,e3,g3,g5,i5,i1,e1)"
 +
  />
 +
As another example, here is the area required by [[Tom's move]]:
 +
<nowiki><hexboard size="6x7"
 +
  contents="R ↑:b3 a4 a5 B b4 a6 E *:area(c2,b5,b6,g6,g4,e2) R d4"
 +
  /></nowiki>
 +
<hexboard size="6x7"
 +
  contents="R ↑:b3 a4 a5 B b4 a6 E *:area(c2,b5,b6,g6,g4,e2) R d4"
 +
  />
 +
The last example also shows that it is possible to attach a label to a set of cells. In this case, each of the cells will receive the label. Also note that we placed the red stone "R d3" after painting the area with "*"; therefore, the "*" in that location was overwritten by the red stone.
  
 +
=== Set operations ===
  
−
<hexboard
+
The following set operations are available. If X and Y are sets:
−
   size="5x5"
+
 
−
   contents="R c1 b3 a5  B a1 e5"
+
* The union of X and Y is written as X+Y.
 +
 
 +
* The difference of X and Y is written as X-Y (i.e., remove all the elements of Y from the set X).
 +
 
 +
* The complement of X is written as -X. It is equivalent to "all-X".
 +
 
 +
* The union of X and Y can also be written as X Y (with a space instead of a plus sign). This notation has a higher precedence than the operators "+" and "-". For example, "X Y - Z W + V" means: take the union of X and Y, then remove the union of Z and W, then add V.
 +
 
 +
* Set expressions can be parenthesized. For example, "X-(-Y)" means: remove the complement of Y from X (or in other words, take the intersection of X and Y).
 +
 
 +
* Commas can be used in place of spaces, and vice versa.
 +
 
 +
* Inside the '''contents''' attribute, any set expression that uses spaces must be parenthesized. For example:
 +
<nowiki><hexboard size="5x5"
 +
   contents="R 1:(-b2 b3 c2)"
 +
  /></nowiki>
 +
<hexboard size="5x5"
 +
   contents="R 1:(-b2 b3 c2)"
 
   />
 
   />
  
 +
== Edges ==
  
−
== Example 3 ==
+
By default, colored edges are shown on all four sides of the Hex board. This can be changed with the '''edges''' attribute. For example:
 +
<nowiki><hexboard size="4x5"
 +
  edges="bottom right"
 +
  contents=""
 +
  /></nowiki>
 +
<hexboard size="4x5"
 +
  edges="bottom right"
 +
  contents=""
 +
  />
 +
The keywords recognized by the '''edges''' attribute are:
  
−
  <nowiki><hexboard
+
* "hide" or "none": show no edges
−
  size="5x4"
+
* "show" or "all": show all edges (the default)
−
   contents="R 1:d1 b4
+
* Any combination of "left", "right", "top", "bottom": show the specified edges.
−
            B 2:c3
+
 
−
            E +:a2 *:c4"
+
== Visibility ==
−
   coords="hide"
+
 
 +
The attribute '''visible''' is used to specify the set of visible cells. This is useful for hiding parts of the board, and in particular, for showing positions (such as templates) whose natural shape is not a parallelogram. For example, here is a [[ziggurat]]:
 +
  <nowiki><hexboard size="3x4"
 +
   visible="area(a3,d3,d1,c1)"
 +
  edges="bottom"
 +
   coords="none"
 +
  contents="R c1"
 
   /></nowiki>
 
   /></nowiki>
 +
<hexboard size="3x4"
 +
  visible="area(a3,d3,d1,c1)"
 +
  edges="bottom"
 +
  coords="none"
 +
  contents="R c1"
 +
  />
 +
 +
== Coordinates ==
  
 +
By default, coordinates (row numbers and column letters) are shown along the top and left edges. This can be changed with the '''coords''' attribute. For example:
 +
<nowiki><hexboard size="3x4"
 +
  coords="bottom left"
 +
  /></nowiki>
 +
<hexboard size="3x4"
 +
  coords="bottom left"
 +
  />
 +
The keywords recognized by the '''coords''' attribute are:
  
−
<hexboard
+
* "hide" or "none": show no coordinates.
−
   size="5x4"
+
* "left", "right", "top", "bottom": show coordinates along the respective edges.
−
   contents="R 1:d1 b4
+
* "show": is equivalent to "top left" (the default).
−
            B 2:c3
+
* "all": is equivalent to "top left bottom right".
−
            E +:a2 *:c4"
+
* In addition, if the keywords "partial" or "full" are used ''before'' any of the other keywords, it means that along the specified edges, coordinates will only be shown next to visible cells ("partial") or also next to invisible cells ("full"). For example, consider the difference between the following two diagrams:
−
   coords="hide"
+
<nowiki><hexboard size="3x5"
 +
   visible="area(a3,e3,e1,c1)-c3"
 +
   edges="bottom"
 +
  coords="partial bottom left"
 +
  /></nowiki>
 +
<hexboard size="3x5"
 +
  visible="area(a3,e3,e1,c1)-c3"
 +
  edges="bottom"
 +
   coords="partial bottom left"
 
   />
 
   />
 +
<nowiki><hexboard size="3x5"
 +
  visible="area(a3,e3,e1,c1)-c3"
 +
  edges="bottom"
 +
  coords="full bottom left"
 +
  /></nowiki>
 +
<hexboard size="3x5"
 +
  visible="area(a3,e3,e1,c1)-c3"
 +
  edges="bottom"
 +
  coords="full bottom left"
 +
  />
 +
It is also possible to mix these modes, for example "full bottom partial left".
 +
 +
== Shading ==
 +
 +
Cells can be shaded (also known as highlighted) by using the keyword "S" in the '''contents''' tag. For example:
 +
<nowiki><hexboard size="5x5"
 +
  contents="R c3 S area(a5,d5,d3,c3)"
 +
  /></nowiki>
 +
<hexboard size="5x5"
 +
  contents="R c3 S area(a5,d5,d3,c3)"
 +
  />
 +
Its syntax is analogous to "R", "B", and "E" (for placing red or blue pieces, or creating an empty cell), but the shading of a cell is independent of its contents. In other words, placing a stone or a label on a cell does not remove the shading, and shading the cell does not remove any stones or labels. Also, marking a cell as empty does not remove the shading; it only removes any stones and labels. Set notations can be used for shading sets of cells. Also, the color of the shading can be specified using a similar syntax as for labels. The available colors are "gray" (or "grey"), "red", and "blue". The default is "gray". Also, "none" can be specified to remove the shading from a cell. For example, the following diagram shows cells [[Captured cell|captured]] by Red and Blue in their respective colors:
 +
<nowiki><hexboard size="5x5"
 +
  contents="R d2 S red:area(c1,c2,d2,e1) B b3 S blue:area(a1,a4,b3,b1)"
 +
  /></nowiki>
 +
<hexboard size="5x5"
 +
  contents="R d2 S red:area(c1,c2,d2,e1) B b3 S blue:area(a1,a4,b3,b1)"
 +
  />
 +
 +
== Placement ==
 +
 +
Hex boards are normally created as block elements, which means that they start a new line. By setting the '''float''' attribute to either "left" or "right", the board can instead be floated to the respective side of the page. Text will flow around it. The value "inline" can be used to turn the diagram into an inline element, where it can appear in the middle of text without starting a new line. This feature should be used very sparingly.
 +
 +
== Debugging ==
 +
 +
* Don't forget the "/>" to close the tag!
 +
 +
* Don't forget to enclose each attribute value in double quotes; especially don't forget the final double quote after the '''contents''' attribute!
 +
 +
* Some syntax errors will generate warnings. These are displayed below the diagram that caused them.
 +
 +
== Graphical tool ==
 +
 +
There is a graphical tool to create a <nowiki><hexboard></nowiki> tag at [http://www.hexwiki.net/board_gui.html http://www.hexwiki.net/board_gui.html]. It supports only a small subset of the features discussed above. It lets you set up a board, then generates a tag that you can copy and paste. Click on a piece type to choose it, then click on a board cell to place that piece on the cell.
 +
 +
[[category: HexWiki]]

Latest revision as of 04:24, 5 February 2023

This page is about the new diagram facility that was added to HexWiki in August 2015 and updated in December 2020. For information on the old diagram facility, see Help:Hex. Both ways of making diagrams will work, but the new way is recommended.

Basic example

To make a simple board diagram on any HexWiki page, include a <hexboard> tag, specifying the board size in the size attribute (e.g. 5x7) and the board contents in the contents attribute. For example: 

<hexboard size="3x3" contents="R a1 b2 B c1"/>
abc123

Board sizes from 0 to 26 are supported.

The following values can be used in contents:

  • R (to place red pieces)
  • B (to place blue pieces)
  • E (to mark a cell as empty)
  • S (to mark a cell as shaded — see #Shading below)

When a cell name is encountered, that cell will be marked with the most recently mentioned contents (R/B/E/S).

Labels

To add a label to a cell, include it before the cell name, with a colon between the label and the cell. For example: 

<hexboard size="3x4" 
   contents="R arrow(12):a1 b1 B a2 R 1:c1 B 2:b3 R 3:d2 E *:c2 *:d1 *:c3 *:d3"
   />
abcd123132

The possible labels are:

  • numbers (1, 2, 3, etc.)
  • a single upper- or lowercase letter (a, b, c, and A, B, C, etc.)
  • a star (*)
  • a plus sign (+)
  • a minus sign (-)
  • arrows, written as "arrow(n)", where n is an hour on the clock, i.e., 1, 2, ..., 12. The arrow points in the corresponding clock direction.
  • You can also use the Unicode characters "↗", "→", "↘", "↓", "↙", "←", "↖", and "↑" to specify arrows pointing in the direction of 2, 3, 4, 6, 8, 9, 10, and 12 o'clock, respectively. (Unfortunately there aren't enough Unicode arrows to also cover 1, 5, 7, and 11 o'clock. You have to use the "arrow(n)" notation for these).

Both empty cells and occupied cells can be labelled. To remove a label, just specify the corresponding cell again without a label.

Set expressions

Instead of a single cell, it is also possible to specify a set of cells. For example: 

<hexboard size="5x5"
   contents="R line(a1,a5,e1) B area(b5,e5,e3,d3)"
   />
abcde12345

The following set expressions are available:

Basic set expressions

  • "all": specifies the set of all cells on the board.
  • "none": specifies the empty set of cells.
  • A cell name, such as a1, specifies the set consisting of that one cell.
  • line(cell₁,cell₂): the set of all cells whose center lies on the line segment connecting the centers of cell₁ and cell₂. More generally, line(cell₁,cell₂,...,cellₙ) specifies a multiline, i.e., a line from cell₁ to cell₂, followed by a line from cell₂ to cell₃, and so on.
  • cell₁--cell₂--...--cellₙ is a synonym of line(cell₁,cell₂,...,cellₙ).
  • area(cell₁,cell₂,...,cellₙ): the set of cells whose center lies on the border or in the inside of the polygon with vertices cell₁, cell₂, ..., cellₙ.

The cells on a line do not need to be adjacent, for example: 

<hexboard size="5x9"
   contents="R line(a1,i5) B line(a4,g1)"
   />
abcdefghi12345

It does not matter whether the area is described by a clockwise or counterclockwise boundary. Also, the polygon specified by "area" does not need to be convex. For example: 

<hexboard size="5x9"
   contents="R area(a5,c5,e3,g3,g5,i5,i1,e1)"
   />
abcdefghi12345

As another example, here is the area required by Tom's move: 

<hexboard size="6x7"
   contents="R ↑:b3 a4 a5 B b4 a6 E *:area(c2,b5,b6,g6,g4,e2) R d4"
   />
abcdefg123456

The last example also shows that it is possible to attach a label to a set of cells. In this case, each of the cells will receive the label. Also note that we placed the red stone "R d3" after painting the area with "*"; therefore, the "*" in that location was overwritten by the red stone.

Set operations

The following set operations are available. If X and Y are sets:

  • The union of X and Y is written as X+Y.
  • The difference of X and Y is written as X-Y (i.e., remove all the elements of Y from the set X).
  • The complement of X is written as -X. It is equivalent to "all-X".
  • The union of X and Y can also be written as X Y (with a space instead of a plus sign). This notation has a higher precedence than the operators "+" and "-". For example, "X Y - Z W + V" means: take the union of X and Y, then remove the union of Z and W, then add V.
  • Set expressions can be parenthesized. For example, "X-(-Y)" means: remove the complement of Y from X (or in other words, take the intersection of X and Y).
  • Commas can be used in place of spaces, and vice versa.
  • Inside the contents attribute, any set expression that uses spaces must be parenthesized. For example: 
<hexboard size="5x5"
   contents="R 1:(-b2 b3 c2)"
   />
abcde123451111111111111111111111

Edges

By default, colored edges are shown on all four sides of the Hex board. This can be changed with the edges attribute. For example: 

<hexboard size="4x5"
   edges="bottom right"
   contents=""
   />
abcde1234

The keywords recognized by the edges attribute are:

  • "hide" or "none": show no edges
  • "show" or "all": show all edges (the default)
  • Any combination of "left", "right", "top", "bottom": show the specified edges.

Visibility

The attribute visible is used to specify the set of visible cells. This is useful for hiding parts of the board, and in particular, for showing positions (such as templates) whose natural shape is not a parallelogram. For example, here is a ziggurat: 

<hexboard size="3x4"
   visible="area(a3,d3,d1,c1)"
   edges="bottom"
   coords="none"
   contents="R c1"
   />

Coordinates

By default, coordinates (row numbers and column letters) are shown along the top and left edges. This can be changed with the coords attribute. For example: 

<hexboard size="3x4"
   coords="bottom left"
   />
abcd123

The keywords recognized by the coords attribute are:

  • "hide" or "none": show no coordinates.
  • "left", "right", "top", "bottom": show coordinates along the respective edges.
  • "show": is equivalent to "top left" (the default).
  • "all": is equivalent to "top left bottom right".
  • In addition, if the keywords "partial" or "full" are used before any of the other keywords, it means that along the specified edges, coordinates will only be shown next to visible cells ("partial") or also next to invisible cells ("full"). For example, consider the difference between the following two diagrams: 
<hexboard size="3x5"
   visible="area(a3,e3,e1,c1)-c3"
   edges="bottom"
   coords="partial bottom left"
   />
abde3
<hexboard size="3x5"
   visible="area(a3,e3,e1,c1)-c3"
   edges="bottom"
   coords="full bottom left"
   />
abcde123

It is also possible to mix these modes, for example "full bottom partial left".

Shading

Cells can be shaded (also known as highlighted) by using the keyword "S" in the contents tag. For example: 

<hexboard size="5x5"
   contents="R c3 S area(a5,d5,d3,c3)"
   />
abcde12345

Its syntax is analogous to "R", "B", and "E" (for placing red or blue pieces, or creating an empty cell), but the shading of a cell is independent of its contents. In other words, placing a stone or a label on a cell does not remove the shading, and shading the cell does not remove any stones or labels. Also, marking a cell as empty does not remove the shading; it only removes any stones and labels. Set notations can be used for shading sets of cells. Also, the color of the shading can be specified using a similar syntax as for labels. The available colors are "gray" (or "grey"), "red", and "blue". The default is "gray". Also, "none" can be specified to remove the shading from a cell. For example, the following diagram shows cells captured by Red and Blue in their respective colors: 

<hexboard size="5x5"
   contents="R d2 S red:area(c1,c2,d2,e1) B b3 S blue:area(a1,a4,b3,b1)"
   />
abcde12345

Placement

Hex boards are normally created as block elements, which means that they start a new line. By setting the float attribute to either "left" or "right", the board can instead be floated to the respective side of the page. Text will flow around it. The value "inline" can be used to turn the diagram into an inline element, where it can appear in the middle of text without starting a new line. This feature should be used very sparingly.

Debugging

  • Don't forget the "/>" to close the tag!
  • Don't forget to enclose each attribute value in double quotes; especially don't forget the final double quote after the contents attribute!
  • Some syntax errors will generate warnings. These are displayed below the diagram that caused them.

Graphical tool

There is a graphical tool to create a <hexboard> tag at http://www.hexwiki.net/board_gui.html. It supports only a small subset of the features discussed above. It lets you set up a board, then generates a tag that you can copy and paste. Click on a piece type to choose it, then click on a board cell to place that piece on the cell.

Retrieved from "https://www.hexwiki.net/index.php?title=New_board_diagrams&oldid=8004"