chessboard: A package to print chessboards Ulrike Fischer May 1, 2014 Contents 1 Changes 3 2 Introduction 4 2.1 Bugs and errors ..................................... 5 2.2 Requirements ...................................... 6 2.3 Installation ........................................ 6 2.4 Robustness: using \chessboard in moving arguments .............. 6 2.5 Setting the options ................................... 7 2.6 Saving optionlists .................................... 9 2.7 Naming the board .................................... 10 2.8 Naming areas of the board ............................... 10 2.9 FEN: Forsyth-Edwards Notation ........................... 11 2.10 The main parts of the board .............................. 11 1
76
Embed
chessboard: A package to print chessboards - ibibliomirrors.ibiblio.org/.../macros/latex/contrib/chessboard/chessboard.pdf · chessboard: A package to print chessboards Ulrike Fischer
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
chessboard A package to printchessboards
Ulrike Fischer
May 1 2014
Contents
1 Changes 3
2 Introduction 421 Bugs and errors 522 Requirements 623 Installation 624 Robustness using chessboard in moving arguments 625 Setting the options 726 Saving optionlists 927 Naming the board 1028 Naming areas of the board 1029 FEN Forsyth-Edwards Notation 11210 The main parts of the board 11
1
3 Setting the contents of the board 1231 The maximum number of fields 1232 Filling with the package skak 1333 Clearing 1434 Adding single pieces 1435 Adding FEN-positions 1536 Saving positions 1737 Getting the positions of pieces 1838 Using saved and stored games 1939 Restoring the running game 19310 Changing the input language 20
4 The look of the board 2141 Units for lengths 2142 Some words about box sizes 2143 Margins 2244 Borders 2345 The size of the boardfont 2546 Changing the boardfont 2547 Coloring and emphasizing the board chars 27
471 In short 27472 Introduction About composed chars and encodings 27473 Setting the default colors of the board 30474 Applying the colors to the whole board 31475 Emphasising and coloring individual areas 32476 Transparencyopacity 34
48 Labels 3449 The mover 37
5 Controlling the printing 4051 Printing partial boards 4052 Rotating the board 4153 Hiding the content of the board 42
531 Hiding the content of fields 42532 Hiding piecetypes 42533 Showing the content of fields 43534 Showing piecetypes 44
611 Naming of the pgf related keys 46612 Executing the drawing commands 46613 Drawing on and under fields 47614 Drawing on regions 48
May 1 2014 2 chessboard 17
615 Drawing move related 49616 Choosing what is drawn pgf styles 50617 Introduction to the predefined pgf styles 51618 Setting graphic properties 56619 A special shortcut key for background border 616110 Special shortcut keys for background color 626111 Clearing the pgf-pictures 636112 Clipping the pgf pictures 656113 Trimming 66
62 Using a graphic as background 7063 Using the commands of the package skak 7164 Intelligent highlighting 72
7 Extending the game 7271 Adding new pieces 7272 Using chessboard for other games 73
8 Compability with other packages 7481 skak 7482 texmate 7483 beamer 7484 animate 75
1 Changes
Attention
From version 15 on the documentation uses the (new) package xskak instead of skak Themost notable difference is that in some examples newchessgame instead of newgame isused But in most cases all examples should work with skak alone too The package xskakadds quite a lot new keys to chessboard to show arbitrary positions from previously parsedgames Read its documentation if you want to use them
In version 13 I made a lot of changes I tried to preserve the behaviour of existing keys andcommands But is possible that older documents will look different when processed withthis version
Notably two things can give problems The value of the padding key now affects much moreobjects (marks) in the pgf pictures So it could be necessary to reset the padding And theapplycolor has changed its behaviour It will now also affect the foreground picture
2011-03-17 (Version 17) Changed definition of the triangle mover style It now uses tikzand no longer amssymb chessboard no longer loads amssymb (it clashes with xunicode)
May 1 2014 3 chessboard 17
2011-03-13 (Version 17) Corrected a bug with spacing when the amsart is used
2008-11-27 (Version 16) Corrected a bug in getpiecelists (empty lists were undefined)
2007-12-11 (Version 15) Added the key getpiecelists to retrieve the positions of piecesQuite a lot new keys to show arbitrary positions from previously parsed games areadded by the package xskak Read its documentation if you want to use them
2007-08-20 (Version 15) Added curvemove-style to draw moves Corrected some bugsChanged a lot internally to adapt the package to xskaksty
2007-07-03 (Version 14) Rewrote the code that process the keys saved globally (withchessboard) and in styles (with storechessboardstyle) to go around a problemdue to a change in xkeyval 25 Corrected some errors in the documentation
2006-07-20 (Version 13) Rearranged and rewrote the keys and commands for the pgf-pictures Now all styles and marks can be used in both pictures Added definitions forpartial borders Extended trim and clip commands xifthen is now required
2006-06-22 Added keys for fancy borders added local commands for the boardarea and theprintarea Disabled the option skaknew as it not longer works in the package chessfss
2 Introduction
What is does
This package offers a command chessboard[langkey=value listrang] to print boards of chesschessboard
positions and similar games It is intended to replace the showboard command of thepackage skak which has some deficiencies
bull To print a special position one always has to type the complete FEN
bull It frames all boards with a rule of 1pt ndash which is okay for a large board but doesnrsquot lookgood on small boards
bull Itrsquos difficult (up to impossible) to color some squares
bull Even for simple markings like crosses or the mover the package skak use postscriptThat makes it difficult to use pdfLATEX
bull Itrsquos difficult to print partial boards
bull Itrsquos difficult (up to impossible) to print boards with exotic pieces eg fairy chess
bull Itrsquos impossible to print boards with unusual dimension or unusual labels used by othergames eg 10times10 boards with numbers instead of characters
bull The labels at the bottom changes the baseline which makes it difficult to align boards
May 1 2014 4 chessboard 17
bull Some commands eg notationoff of the package skak redefines skakboard so itis difficult to patch the command eg to get larger margins
With the package chessboard you have now full control about size content and look of theboard I have tried to make chessboard as flexible as possible So I added a lot of optionsto change values that control the size layout and filling of the board In most cases you canignore them but being able to change them can come handy if you need something unusual
But I didnrsquot tried to stretch flexibility too much The main aim of the package is to printchessboards easily so eg the inputs use the naming conventions of chess That means thatndash as the files are numbered alphabetically ndash the width of the board is restricted to 26 fields (27with option zero) The board is build with alternating black and white fields changing to egthree colors could be difficult The pieces are named with simple ASCII-chars so the numberof different pieces is restricted (It is perhaps possible to define piecenames consisting oftwo or more chars and to use such names by putting braces around the chars eg KKa3A small test worked fine for me but I wouldnrsquot bet that it really works everywhere)
What it doesnrsquot
The package chessboard doesnrsquot offer commands to type captions or titles or a list of thechessboards There are no options that control the placement of the board in the textflow eg to center it or to let it float This is a design decision chessboard prints onlychessboards like includegraphics inserts only graphics
21 Bugs and errors
Irsquom quite sure that they are bugs and errors in the package I did find some quite horriblewhile making the documentation and Irsquom sure I overlooked some Eg I have a lot of doubtsif spaces and braces in keys saved in a style or with setchessboard are handled correctlyin every case
If you have questions ask them in the newsgroups comptexttex or decomptexttexIrsquom reading these groups regularly and Irsquom much better in answering there than in answeringe-mails
If you find errors in this text (this includes wrong english) or in the package you can writeme a bugreport at skaknililandde A bugreport should contain a complete minimalexample and the log-file of the pdfLATEX run (this is the engine that makes a pdf)
Before sending a bug record check the following things
If you get mysterious error messages
bull Check the commas in the key=value lists
May 1 2014 5 chessboard 17
Missing or faulty pgf-decorations
bull Check if the borders or marks are hidden under other decorations or under boardchars with solid fieldmasks
bull Check if trimming is responsible try the key trim=false
bull Check the state of the key pgf
bull Try another previewer zoom in and out print the document
bull Go through your log-file and search for chessboard warnings
22 Requirements
The package chessboard uses some primitives of eTEX It needs a recent version of thepackage chessfss (chess font selection) xkeyval (key=value-syntax) and xifthen It also needsthe packages pgfcore pgfbaseshapes (from pgf for the highlighting commands) pst-node(from pstricks)
23 Installation
Run chessboardins through LATEX and then put the four sty-files somewhere whereLATEX finds them lttexmfgttexlatexchessboard is a good place Update the filenamedatabase
24 Robustness using chessboard in moving arguments
I have used chessboard in tabulars and in moving arguments It seems to work fine so Iwould say the command is quite robust
Putting chessboards in the table of contents or the header will in most case not look verygood so it is sensible to avoid it with section[short text]chessboard Title Butif you want to do some advices
bull Boards in the title and in the table of contents are built at different times during therun when perhaps different options and different games are active so they can lookdifferent if you are not careful
bull You canrsquot put boards in the bookmarks of a pdf use texorpdfstring from hyperrefto provide a replacement
bull Some pagestyles puts a command to uppercase around the header This affects keys inthe optional argument of chessboard and will give error messages about undefinedkeys Try to surround the chessboard command with lowercase
May 1 2014 6 chessboard 17
25 Setting the options
The package chessboard use the keyval syntax langkeyrang=langvaluerangIt differs in some respects to other packages with keyval syntax
bull There are really very much keys
bull Some keys donrsquot set properties of a board (like a width) but do things like drawing
bull The order of the keys can matter
bull Some effects are achieved by using two or more keys after one other
There are keys that need a certain type of argument eg a length or a list of fields Thereare boolean keys that accept only the values =true and =false where the value =true canalways be omitted And at last there are keys that works as commands you can use whateverargument you want or leave it blank Donrsquot confound this commands with boolean keys Egclearboard clearboard=hallo and even clearboard=false will always clear the board
Irsquom struggling permanently with the naming of the keys Giving them names that are not tolong but descriptive and a bit systematic isnrsquot easy Also it isnrsquot easy to decide if a specialeffect should be achieve with one key (which gives a short input) or with a combination ofkeys (with is more flexible as it can be used to implement similar effects but gives longerinput) While the package evolved I sometimes tumbled in problems and inconsistencies ofthe current naming scheme and had to reconsider my decisions and implemented betternames or new key combinations I didnrsquot delete or disable older now perhaps obsolate keysin any case as I wanted to avoid that older documents breaks I also sometimes add a keythat is simply a copy of an existing key only to get a more consistent naming So ist quitepossible that you can get the same result with different key combination For a lot of thingsthere isnrsquot one correct way ndash you can choose the one which suits you more
Itrsquos easy to make mistakes when using a lot of keys So if you get mysterious errors check thatyou donrsquot have forgot a comma between the keys that you put braces around lists used asvalue that you didnrsquot use a backslash before a key that you didnrsquot used a list of fields when alist of pieces is requested
You can set an option either for one board by using the optional argument of chessboardsetchessboard
or by using setchessboardlangkey=value listrang which sets the keys for all following boardsin the same environmentgroup
May 1 2014 7 chessboard 17
Default setting in this Dokumentationsetchessboard
Even if they share the same name keys used in the argument of chessboard are implemen-tated differently than the keys used in setchessboard They do different things In thefirst case the key gets ldquoexecutedrdquo while in the second case the key=value pair is only storedfor later use So it is quite possible that a key works with chessboard but fails because of abug when used in setchessboard or vice-versa
Values set by keys in the argument of chessboard will if appropriate overwrite the ones setby setchessboard
The keys belong roughly to two classes There are the keys that set one property of the boardeg the width of a rule or the size Such keys always have a default and only the last value setis used it overwrites all previous values Internally I call such keys ldquoset-keysrdquo In the secondclass there are keys that can be used more than once eg keys that add a piece or a mark ora color to the board I call such keys ldquofill-keysrdquo1
The ldquoset-keysrdquo are always processed first Inside the classes the keys are processed in generalfrom ldquoleft to rightrdquo so later keys can overwrite values set by earlier keys This is also true forvalues hidden in a style
For each ldquoset-keyrdquo you will find in this documentation a box like this
zero=langtrue|falserang zero=false zero false
It shows on the left the general description of the possible values in the middle one or moreexamples of correct input and on the right the default value
For each ldquofill-keyrdquo you will find in this documentation a box like this
clearranks=langlist of ranksrang clearranks=8
It shows on the left the general description of the possible values and on the right one ormore examples of correct input
1I did realize only quite late that using keys not only to set some parameters but also for the real content isa bit unusual It is a bit as if one would use keys for the items of a list or the lines of tabular or the codein a listing ndash in most cases quite a bad idea But at my opinion it works fine in this special case because achessboard is a quite restricted room with only 64 fields
May 1 2014 8 chessboard 17
26 Saving optionlists
style=langnamerang style=mystyle
With the storechessboardstylelangnameranglangkey=value listrang it is possible to store a list ofstorechessboardstyle
key=value-pairs in a ldquostylerdquo and to use this style instead of the keys themselves
storechessboardstyle and setchessboard only store the key=value pair they donrsquotexpand anything and they donrsquot do anything with them So be careful when using commandsthat could be redefined later
In chess the rows of the board are called ranks and are numbered from 1 to 8 The columnsare called files and are ldquonumberedrdquo from a to h2
The package chessboard use this naming conventions for all inputs Every time langfieldrang is usedin this documentation you should give a char from andashz followed by a number
28 Naming areas of the board
Rectangular areas are normally described by giving the coordinates of the left bottom cornerand the right upper corner But when using the Forsyth Edwards Notation (FEN) chessboardsare filled starting from the left upper corner a8 and then going on to the right and down tothe right bottom corner ndash like the normal typesetting direction So it is quite natural to usefor FEN related areas this corners As it would be awkward to have two different ways todescribe areas I decided to use the fen convention everywhere Each area has a startfieldthe left upper corner and a stopfield the right bottom corner If some area related keys donrsquotseem to work check that you have used the correct corners
An area can also be given as two fields separated by an hyphen When using this input youdonrsquot have to worry about the corners the package will sort themlangarearang=langa cornerrang-langthe opposite cornerrangchessboard sets at the start this two command to the current values of the printareaprintarea
board and the total board as given by the keys zero maxfield and printarea You can use thiscommands in later keys
2I have some difficulties to remember the english names so I use the following mnemonics FiLe = coLumn =Linie = alFabet Rank = Row = Reihe = numbeRed
May 1 2014 10 chessboard 17
29 FEN Forsyth-Edwards Notation
FEN describes a chess position It consist of 6 fields separated by spaces The first fieldrepresents the placement of the pieces on the board The second field represents the activecolor A lower case ldquowrdquo is used if White is to move a lower case ldquobrdquo is used if Black is theactive player The third field represents castling availability The fourth field is the en passanttarget square The fifth field is a nonnegative integer representing the halfmove clock Thesixth and last field is a positive integer that gives the fullmove number
In the first field the board contents are specified starting with the eighth rank and endingwith the first rank (ldquoin typesetting directionrdquo when the board has the standard orientation)For each rank the squares are specified from file a to file h White pieces are identified byuppercase piece letters (ldquoPNBRQKrdquo) and black pieces are identified by lowercase piece letters(ldquopnbrqkrdquo) Empty squares are represented by the digits one through eight the digit usedrepresents the count of contiguous empty squares along a rank A solidus character ldquordquo isused to separate data of adjacent ranks
chessboard handles FEN-input but also only ldquoFEN-likerdquo-input If given a complete FENchessboard will store all fields in commands and evaluate the first field to fill the boardBut if they are less than six fields chessboard will not complain but simply fill up themissing fields with some default values
In the first field there donrsquot need to be exact 8 pieces in each rank and exactly 8 rank descrip-tions When there are more pieces than needed chessboard will ignore them When thereare less pieces than needed then chessboard will leave the remaining fields in this rankuntouched
The FEN can also be stored in a command So all chessboard will accept all the followinginputs as langFENrangrnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR w KQkq - 0 1rnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR8qK10 w - - 0 10myfen
210 The main parts of the board
Each chessboard is build by printing three ldquolayersrdquo on top of each other
1 The background layer
This is a pgf-picture that lies under the board It can be used for background colors or fancyborders or other background decoration
May 1 2014 11 chessboard 17
2 The main board layer
This is the main part of the board It lies above the background picture It uses only ldquonormalrdquoLATEX objects like rules and chars Labels movers and figures are all build together in thislayer
3 The mark layer
This layer is again a pgf picture now over the board It can be used to draw crosses arrowsetc on the board
The sections 3 to 5 describe how to manipulate the main layer The section 6 describes howto handle the pgf pictures
3 Setting the contents of the board
31 The maximum number of fields
maxfield=langfieldrang maxfield=j10 h8
Chessboards have 8times8 fields So this is the default If you want another size you shoulddeclare a new right upper corner with maxfield=langFieldrang eg maxfield=j10 for a 10times10board Donrsquot use this key if you want only to print a partial board there is another key toachieve this Use it to change the maximum size of a board All fields and areas you use inother arguments should lie inside this maximum size
I was told that some games numbers the fields starting with 0 So I added this option Whenset to true the rank numbers start with 0 and a file named Z is added left to the file a
clearareas=langlist of areasrang clearareas=a1-c3g7-h8
clearfile=langfilerang clearfile=g
clearfiles=langlist of filesrang clearfiles=gh
clearrank=langrankrang clearrank=5
clearranks=langlist of ranksrang clearranks=87
clearfield=langfieldrang clearfield=c6
clearfields=langlist of fieldsrang clearfields=b5c6
You canrsquot prevent that chessboard fills up the board with the running game so if you needan empty board you should clear it ndash either with the keys mentioned here or by using oneof the keys described later that clears the board before adding new pieces
setwhite=langList of piece positionsrang setwhite=Ke4 Qe1 kd6
addwhite=langList of piece positionsrang addwhite=Ke4 Qe1 kd6
setblack=langList of piece positionsrang setblack=Ke4 Qe1 kd6
addblack=langList of piece positionsrang addblack=Ke4 Qe1 kd6
It is a bit cumbersome to have to be careful to use uppercase chars for the white andlowercase chars for the black piece With the keys setwhite addwhite setblack andaddblack you can add white and black pieces without caring about the cases Like the keysfor adding pieces the keys starting with set first clears the board so if you donrsquot want toloose all the set pieces you should use such a key only once
With this keys you can add pieces to the board by given a FEN The setfen will clear theboard addfen will left pieces outside the fields described by the FEN undisturbed
The package skak has the command storegamelangnamerang that stores the FEN of the currentgame in an internal command and the command savegamelangnamerang that stores the FENin a file langnamerangfenThe package chessboard defines similar keys The key storefen=langnamerang stores the FEN inan internal command with the same name as used by storegamelangnamerang That meansthat you can exchange the games stored by the package skak and the package chessboardbut it also means that the package chessboard can overwrite games stored with the packageskak So be careful
storefen=langnamerang storefen=game1
savefen=langname of filerang savefen=game
storefen saves the current position as FEN to a internal command savefen saves thecurrent position as FEN to a file
startstore=langfieldrang startstore=b7
stopstore=langfieldrang stopstore=f2
storearea=langarearang storearea=c2-d4
With this keys you can restrict the area that is stored or saved But attention the packageskak absolutly doesnrsquot like ldquoillegalrdquo FENs that doesnrsquot describe a full 8times8 board
May 1 2014 17 chessboard 17
mover=langw|brang mover=w
castling=langcastling possibiliesrang castling=Kq
enpassant=langfield|-rang enpassant=c4
halfmove=langnumberrang halfmove=14
fullmove=langnumberrang fullmove=20
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
3 Setting the contents of the board 1231 The maximum number of fields 1232 Filling with the package skak 1333 Clearing 1434 Adding single pieces 1435 Adding FEN-positions 1536 Saving positions 1737 Getting the positions of pieces 1838 Using saved and stored games 1939 Restoring the running game 19310 Changing the input language 20
4 The look of the board 2141 Units for lengths 2142 Some words about box sizes 2143 Margins 2244 Borders 2345 The size of the boardfont 2546 Changing the boardfont 2547 Coloring and emphasizing the board chars 27
471 In short 27472 Introduction About composed chars and encodings 27473 Setting the default colors of the board 30474 Applying the colors to the whole board 31475 Emphasising and coloring individual areas 32476 Transparencyopacity 34
48 Labels 3449 The mover 37
5 Controlling the printing 4051 Printing partial boards 4052 Rotating the board 4153 Hiding the content of the board 42
531 Hiding the content of fields 42532 Hiding piecetypes 42533 Showing the content of fields 43534 Showing piecetypes 44
611 Naming of the pgf related keys 46612 Executing the drawing commands 46613 Drawing on and under fields 47614 Drawing on regions 48
May 1 2014 2 chessboard 17
615 Drawing move related 49616 Choosing what is drawn pgf styles 50617 Introduction to the predefined pgf styles 51618 Setting graphic properties 56619 A special shortcut key for background border 616110 Special shortcut keys for background color 626111 Clearing the pgf-pictures 636112 Clipping the pgf pictures 656113 Trimming 66
62 Using a graphic as background 7063 Using the commands of the package skak 7164 Intelligent highlighting 72
7 Extending the game 7271 Adding new pieces 7272 Using chessboard for other games 73
8 Compability with other packages 7481 skak 7482 texmate 7483 beamer 7484 animate 75
1 Changes
Attention
From version 15 on the documentation uses the (new) package xskak instead of skak Themost notable difference is that in some examples newchessgame instead of newgame isused But in most cases all examples should work with skak alone too The package xskakadds quite a lot new keys to chessboard to show arbitrary positions from previously parsedgames Read its documentation if you want to use them
In version 13 I made a lot of changes I tried to preserve the behaviour of existing keys andcommands But is possible that older documents will look different when processed withthis version
Notably two things can give problems The value of the padding key now affects much moreobjects (marks) in the pgf pictures So it could be necessary to reset the padding And theapplycolor has changed its behaviour It will now also affect the foreground picture
2011-03-17 (Version 17) Changed definition of the triangle mover style It now uses tikzand no longer amssymb chessboard no longer loads amssymb (it clashes with xunicode)
May 1 2014 3 chessboard 17
2011-03-13 (Version 17) Corrected a bug with spacing when the amsart is used
2008-11-27 (Version 16) Corrected a bug in getpiecelists (empty lists were undefined)
2007-12-11 (Version 15) Added the key getpiecelists to retrieve the positions of piecesQuite a lot new keys to show arbitrary positions from previously parsed games areadded by the package xskak Read its documentation if you want to use them
2007-08-20 (Version 15) Added curvemove-style to draw moves Corrected some bugsChanged a lot internally to adapt the package to xskaksty
2007-07-03 (Version 14) Rewrote the code that process the keys saved globally (withchessboard) and in styles (with storechessboardstyle) to go around a problemdue to a change in xkeyval 25 Corrected some errors in the documentation
2006-07-20 (Version 13) Rearranged and rewrote the keys and commands for the pgf-pictures Now all styles and marks can be used in both pictures Added definitions forpartial borders Extended trim and clip commands xifthen is now required
2006-06-22 Added keys for fancy borders added local commands for the boardarea and theprintarea Disabled the option skaknew as it not longer works in the package chessfss
2 Introduction
What is does
This package offers a command chessboard[langkey=value listrang] to print boards of chesschessboard
positions and similar games It is intended to replace the showboard command of thepackage skak which has some deficiencies
bull To print a special position one always has to type the complete FEN
bull It frames all boards with a rule of 1pt ndash which is okay for a large board but doesnrsquot lookgood on small boards
bull Itrsquos difficult (up to impossible) to color some squares
bull Even for simple markings like crosses or the mover the package skak use postscriptThat makes it difficult to use pdfLATEX
bull Itrsquos difficult to print partial boards
bull Itrsquos difficult (up to impossible) to print boards with exotic pieces eg fairy chess
bull Itrsquos impossible to print boards with unusual dimension or unusual labels used by othergames eg 10times10 boards with numbers instead of characters
bull The labels at the bottom changes the baseline which makes it difficult to align boards
May 1 2014 4 chessboard 17
bull Some commands eg notationoff of the package skak redefines skakboard so itis difficult to patch the command eg to get larger margins
With the package chessboard you have now full control about size content and look of theboard I have tried to make chessboard as flexible as possible So I added a lot of optionsto change values that control the size layout and filling of the board In most cases you canignore them but being able to change them can come handy if you need something unusual
But I didnrsquot tried to stretch flexibility too much The main aim of the package is to printchessboards easily so eg the inputs use the naming conventions of chess That means thatndash as the files are numbered alphabetically ndash the width of the board is restricted to 26 fields (27with option zero) The board is build with alternating black and white fields changing to egthree colors could be difficult The pieces are named with simple ASCII-chars so the numberof different pieces is restricted (It is perhaps possible to define piecenames consisting oftwo or more chars and to use such names by putting braces around the chars eg KKa3A small test worked fine for me but I wouldnrsquot bet that it really works everywhere)
What it doesnrsquot
The package chessboard doesnrsquot offer commands to type captions or titles or a list of thechessboards There are no options that control the placement of the board in the textflow eg to center it or to let it float This is a design decision chessboard prints onlychessboards like includegraphics inserts only graphics
21 Bugs and errors
Irsquom quite sure that they are bugs and errors in the package I did find some quite horriblewhile making the documentation and Irsquom sure I overlooked some Eg I have a lot of doubtsif spaces and braces in keys saved in a style or with setchessboard are handled correctlyin every case
If you have questions ask them in the newsgroups comptexttex or decomptexttexIrsquom reading these groups regularly and Irsquom much better in answering there than in answeringe-mails
If you find errors in this text (this includes wrong english) or in the package you can writeme a bugreport at skaknililandde A bugreport should contain a complete minimalexample and the log-file of the pdfLATEX run (this is the engine that makes a pdf)
Before sending a bug record check the following things
If you get mysterious error messages
bull Check the commas in the key=value lists
May 1 2014 5 chessboard 17
Missing or faulty pgf-decorations
bull Check if the borders or marks are hidden under other decorations or under boardchars with solid fieldmasks
bull Check if trimming is responsible try the key trim=false
bull Check the state of the key pgf
bull Try another previewer zoom in and out print the document
bull Go through your log-file and search for chessboard warnings
22 Requirements
The package chessboard uses some primitives of eTEX It needs a recent version of thepackage chessfss (chess font selection) xkeyval (key=value-syntax) and xifthen It also needsthe packages pgfcore pgfbaseshapes (from pgf for the highlighting commands) pst-node(from pstricks)
23 Installation
Run chessboardins through LATEX and then put the four sty-files somewhere whereLATEX finds them lttexmfgttexlatexchessboard is a good place Update the filenamedatabase
24 Robustness using chessboard in moving arguments
I have used chessboard in tabulars and in moving arguments It seems to work fine so Iwould say the command is quite robust
Putting chessboards in the table of contents or the header will in most case not look verygood so it is sensible to avoid it with section[short text]chessboard Title Butif you want to do some advices
bull Boards in the title and in the table of contents are built at different times during therun when perhaps different options and different games are active so they can lookdifferent if you are not careful
bull You canrsquot put boards in the bookmarks of a pdf use texorpdfstring from hyperrefto provide a replacement
bull Some pagestyles puts a command to uppercase around the header This affects keys inthe optional argument of chessboard and will give error messages about undefinedkeys Try to surround the chessboard command with lowercase
May 1 2014 6 chessboard 17
25 Setting the options
The package chessboard use the keyval syntax langkeyrang=langvaluerangIt differs in some respects to other packages with keyval syntax
bull There are really very much keys
bull Some keys donrsquot set properties of a board (like a width) but do things like drawing
bull The order of the keys can matter
bull Some effects are achieved by using two or more keys after one other
There are keys that need a certain type of argument eg a length or a list of fields Thereare boolean keys that accept only the values =true and =false where the value =true canalways be omitted And at last there are keys that works as commands you can use whateverargument you want or leave it blank Donrsquot confound this commands with boolean keys Egclearboard clearboard=hallo and even clearboard=false will always clear the board
Irsquom struggling permanently with the naming of the keys Giving them names that are not tolong but descriptive and a bit systematic isnrsquot easy Also it isnrsquot easy to decide if a specialeffect should be achieve with one key (which gives a short input) or with a combination ofkeys (with is more flexible as it can be used to implement similar effects but gives longerinput) While the package evolved I sometimes tumbled in problems and inconsistencies ofthe current naming scheme and had to reconsider my decisions and implemented betternames or new key combinations I didnrsquot delete or disable older now perhaps obsolate keysin any case as I wanted to avoid that older documents breaks I also sometimes add a keythat is simply a copy of an existing key only to get a more consistent naming So ist quitepossible that you can get the same result with different key combination For a lot of thingsthere isnrsquot one correct way ndash you can choose the one which suits you more
Itrsquos easy to make mistakes when using a lot of keys So if you get mysterious errors check thatyou donrsquot have forgot a comma between the keys that you put braces around lists used asvalue that you didnrsquot use a backslash before a key that you didnrsquot used a list of fields when alist of pieces is requested
You can set an option either for one board by using the optional argument of chessboardsetchessboard
or by using setchessboardlangkey=value listrang which sets the keys for all following boardsin the same environmentgroup
May 1 2014 7 chessboard 17
Default setting in this Dokumentationsetchessboard
Even if they share the same name keys used in the argument of chessboard are implemen-tated differently than the keys used in setchessboard They do different things In thefirst case the key gets ldquoexecutedrdquo while in the second case the key=value pair is only storedfor later use So it is quite possible that a key works with chessboard but fails because of abug when used in setchessboard or vice-versa
Values set by keys in the argument of chessboard will if appropriate overwrite the ones setby setchessboard
The keys belong roughly to two classes There are the keys that set one property of the boardeg the width of a rule or the size Such keys always have a default and only the last value setis used it overwrites all previous values Internally I call such keys ldquoset-keysrdquo In the secondclass there are keys that can be used more than once eg keys that add a piece or a mark ora color to the board I call such keys ldquofill-keysrdquo1
The ldquoset-keysrdquo are always processed first Inside the classes the keys are processed in generalfrom ldquoleft to rightrdquo so later keys can overwrite values set by earlier keys This is also true forvalues hidden in a style
For each ldquoset-keyrdquo you will find in this documentation a box like this
zero=langtrue|falserang zero=false zero false
It shows on the left the general description of the possible values in the middle one or moreexamples of correct input and on the right the default value
For each ldquofill-keyrdquo you will find in this documentation a box like this
clearranks=langlist of ranksrang clearranks=8
It shows on the left the general description of the possible values and on the right one ormore examples of correct input
1I did realize only quite late that using keys not only to set some parameters but also for the real content isa bit unusual It is a bit as if one would use keys for the items of a list or the lines of tabular or the codein a listing ndash in most cases quite a bad idea But at my opinion it works fine in this special case because achessboard is a quite restricted room with only 64 fields
May 1 2014 8 chessboard 17
26 Saving optionlists
style=langnamerang style=mystyle
With the storechessboardstylelangnameranglangkey=value listrang it is possible to store a list ofstorechessboardstyle
key=value-pairs in a ldquostylerdquo and to use this style instead of the keys themselves
storechessboardstyle and setchessboard only store the key=value pair they donrsquotexpand anything and they donrsquot do anything with them So be careful when using commandsthat could be redefined later
In chess the rows of the board are called ranks and are numbered from 1 to 8 The columnsare called files and are ldquonumberedrdquo from a to h2
The package chessboard use this naming conventions for all inputs Every time langfieldrang is usedin this documentation you should give a char from andashz followed by a number
28 Naming areas of the board
Rectangular areas are normally described by giving the coordinates of the left bottom cornerand the right upper corner But when using the Forsyth Edwards Notation (FEN) chessboardsare filled starting from the left upper corner a8 and then going on to the right and down tothe right bottom corner ndash like the normal typesetting direction So it is quite natural to usefor FEN related areas this corners As it would be awkward to have two different ways todescribe areas I decided to use the fen convention everywhere Each area has a startfieldthe left upper corner and a stopfield the right bottom corner If some area related keys donrsquotseem to work check that you have used the correct corners
An area can also be given as two fields separated by an hyphen When using this input youdonrsquot have to worry about the corners the package will sort themlangarearang=langa cornerrang-langthe opposite cornerrangchessboard sets at the start this two command to the current values of the printareaprintarea
board and the total board as given by the keys zero maxfield and printarea You can use thiscommands in later keys
2I have some difficulties to remember the english names so I use the following mnemonics FiLe = coLumn =Linie = alFabet Rank = Row = Reihe = numbeRed
May 1 2014 10 chessboard 17
29 FEN Forsyth-Edwards Notation
FEN describes a chess position It consist of 6 fields separated by spaces The first fieldrepresents the placement of the pieces on the board The second field represents the activecolor A lower case ldquowrdquo is used if White is to move a lower case ldquobrdquo is used if Black is theactive player The third field represents castling availability The fourth field is the en passanttarget square The fifth field is a nonnegative integer representing the halfmove clock Thesixth and last field is a positive integer that gives the fullmove number
In the first field the board contents are specified starting with the eighth rank and endingwith the first rank (ldquoin typesetting directionrdquo when the board has the standard orientation)For each rank the squares are specified from file a to file h White pieces are identified byuppercase piece letters (ldquoPNBRQKrdquo) and black pieces are identified by lowercase piece letters(ldquopnbrqkrdquo) Empty squares are represented by the digits one through eight the digit usedrepresents the count of contiguous empty squares along a rank A solidus character ldquordquo isused to separate data of adjacent ranks
chessboard handles FEN-input but also only ldquoFEN-likerdquo-input If given a complete FENchessboard will store all fields in commands and evaluate the first field to fill the boardBut if they are less than six fields chessboard will not complain but simply fill up themissing fields with some default values
In the first field there donrsquot need to be exact 8 pieces in each rank and exactly 8 rank descrip-tions When there are more pieces than needed chessboard will ignore them When thereare less pieces than needed then chessboard will leave the remaining fields in this rankuntouched
The FEN can also be stored in a command So all chessboard will accept all the followinginputs as langFENrangrnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR w KQkq - 0 1rnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR8qK10 w - - 0 10myfen
210 The main parts of the board
Each chessboard is build by printing three ldquolayersrdquo on top of each other
1 The background layer
This is a pgf-picture that lies under the board It can be used for background colors or fancyborders or other background decoration
May 1 2014 11 chessboard 17
2 The main board layer
This is the main part of the board It lies above the background picture It uses only ldquonormalrdquoLATEX objects like rules and chars Labels movers and figures are all build together in thislayer
3 The mark layer
This layer is again a pgf picture now over the board It can be used to draw crosses arrowsetc on the board
The sections 3 to 5 describe how to manipulate the main layer The section 6 describes howto handle the pgf pictures
3 Setting the contents of the board
31 The maximum number of fields
maxfield=langfieldrang maxfield=j10 h8
Chessboards have 8times8 fields So this is the default If you want another size you shoulddeclare a new right upper corner with maxfield=langFieldrang eg maxfield=j10 for a 10times10board Donrsquot use this key if you want only to print a partial board there is another key toachieve this Use it to change the maximum size of a board All fields and areas you use inother arguments should lie inside this maximum size
I was told that some games numbers the fields starting with 0 So I added this option Whenset to true the rank numbers start with 0 and a file named Z is added left to the file a
clearareas=langlist of areasrang clearareas=a1-c3g7-h8
clearfile=langfilerang clearfile=g
clearfiles=langlist of filesrang clearfiles=gh
clearrank=langrankrang clearrank=5
clearranks=langlist of ranksrang clearranks=87
clearfield=langfieldrang clearfield=c6
clearfields=langlist of fieldsrang clearfields=b5c6
You canrsquot prevent that chessboard fills up the board with the running game so if you needan empty board you should clear it ndash either with the keys mentioned here or by using oneof the keys described later that clears the board before adding new pieces
setwhite=langList of piece positionsrang setwhite=Ke4 Qe1 kd6
addwhite=langList of piece positionsrang addwhite=Ke4 Qe1 kd6
setblack=langList of piece positionsrang setblack=Ke4 Qe1 kd6
addblack=langList of piece positionsrang addblack=Ke4 Qe1 kd6
It is a bit cumbersome to have to be careful to use uppercase chars for the white andlowercase chars for the black piece With the keys setwhite addwhite setblack andaddblack you can add white and black pieces without caring about the cases Like the keysfor adding pieces the keys starting with set first clears the board so if you donrsquot want toloose all the set pieces you should use such a key only once
With this keys you can add pieces to the board by given a FEN The setfen will clear theboard addfen will left pieces outside the fields described by the FEN undisturbed
The package skak has the command storegamelangnamerang that stores the FEN of the currentgame in an internal command and the command savegamelangnamerang that stores the FENin a file langnamerangfenThe package chessboard defines similar keys The key storefen=langnamerang stores the FEN inan internal command with the same name as used by storegamelangnamerang That meansthat you can exchange the games stored by the package skak and the package chessboardbut it also means that the package chessboard can overwrite games stored with the packageskak So be careful
storefen=langnamerang storefen=game1
savefen=langname of filerang savefen=game
storefen saves the current position as FEN to a internal command savefen saves thecurrent position as FEN to a file
startstore=langfieldrang startstore=b7
stopstore=langfieldrang stopstore=f2
storearea=langarearang storearea=c2-d4
With this keys you can restrict the area that is stored or saved But attention the packageskak absolutly doesnrsquot like ldquoillegalrdquo FENs that doesnrsquot describe a full 8times8 board
May 1 2014 17 chessboard 17
mover=langw|brang mover=w
castling=langcastling possibiliesrang castling=Kq
enpassant=langfield|-rang enpassant=c4
halfmove=langnumberrang halfmove=14
fullmove=langnumberrang fullmove=20
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
615 Drawing move related 49616 Choosing what is drawn pgf styles 50617 Introduction to the predefined pgf styles 51618 Setting graphic properties 56619 A special shortcut key for background border 616110 Special shortcut keys for background color 626111 Clearing the pgf-pictures 636112 Clipping the pgf pictures 656113 Trimming 66
62 Using a graphic as background 7063 Using the commands of the package skak 7164 Intelligent highlighting 72
7 Extending the game 7271 Adding new pieces 7272 Using chessboard for other games 73
8 Compability with other packages 7481 skak 7482 texmate 7483 beamer 7484 animate 75
1 Changes
Attention
From version 15 on the documentation uses the (new) package xskak instead of skak Themost notable difference is that in some examples newchessgame instead of newgame isused But in most cases all examples should work with skak alone too The package xskakadds quite a lot new keys to chessboard to show arbitrary positions from previously parsedgames Read its documentation if you want to use them
In version 13 I made a lot of changes I tried to preserve the behaviour of existing keys andcommands But is possible that older documents will look different when processed withthis version
Notably two things can give problems The value of the padding key now affects much moreobjects (marks) in the pgf pictures So it could be necessary to reset the padding And theapplycolor has changed its behaviour It will now also affect the foreground picture
2011-03-17 (Version 17) Changed definition of the triangle mover style It now uses tikzand no longer amssymb chessboard no longer loads amssymb (it clashes with xunicode)
May 1 2014 3 chessboard 17
2011-03-13 (Version 17) Corrected a bug with spacing when the amsart is used
2008-11-27 (Version 16) Corrected a bug in getpiecelists (empty lists were undefined)
2007-12-11 (Version 15) Added the key getpiecelists to retrieve the positions of piecesQuite a lot new keys to show arbitrary positions from previously parsed games areadded by the package xskak Read its documentation if you want to use them
2007-08-20 (Version 15) Added curvemove-style to draw moves Corrected some bugsChanged a lot internally to adapt the package to xskaksty
2007-07-03 (Version 14) Rewrote the code that process the keys saved globally (withchessboard) and in styles (with storechessboardstyle) to go around a problemdue to a change in xkeyval 25 Corrected some errors in the documentation
2006-07-20 (Version 13) Rearranged and rewrote the keys and commands for the pgf-pictures Now all styles and marks can be used in both pictures Added definitions forpartial borders Extended trim and clip commands xifthen is now required
2006-06-22 Added keys for fancy borders added local commands for the boardarea and theprintarea Disabled the option skaknew as it not longer works in the package chessfss
2 Introduction
What is does
This package offers a command chessboard[langkey=value listrang] to print boards of chesschessboard
positions and similar games It is intended to replace the showboard command of thepackage skak which has some deficiencies
bull To print a special position one always has to type the complete FEN
bull It frames all boards with a rule of 1pt ndash which is okay for a large board but doesnrsquot lookgood on small boards
bull Itrsquos difficult (up to impossible) to color some squares
bull Even for simple markings like crosses or the mover the package skak use postscriptThat makes it difficult to use pdfLATEX
bull Itrsquos difficult to print partial boards
bull Itrsquos difficult (up to impossible) to print boards with exotic pieces eg fairy chess
bull Itrsquos impossible to print boards with unusual dimension or unusual labels used by othergames eg 10times10 boards with numbers instead of characters
bull The labels at the bottom changes the baseline which makes it difficult to align boards
May 1 2014 4 chessboard 17
bull Some commands eg notationoff of the package skak redefines skakboard so itis difficult to patch the command eg to get larger margins
With the package chessboard you have now full control about size content and look of theboard I have tried to make chessboard as flexible as possible So I added a lot of optionsto change values that control the size layout and filling of the board In most cases you canignore them but being able to change them can come handy if you need something unusual
But I didnrsquot tried to stretch flexibility too much The main aim of the package is to printchessboards easily so eg the inputs use the naming conventions of chess That means thatndash as the files are numbered alphabetically ndash the width of the board is restricted to 26 fields (27with option zero) The board is build with alternating black and white fields changing to egthree colors could be difficult The pieces are named with simple ASCII-chars so the numberof different pieces is restricted (It is perhaps possible to define piecenames consisting oftwo or more chars and to use such names by putting braces around the chars eg KKa3A small test worked fine for me but I wouldnrsquot bet that it really works everywhere)
What it doesnrsquot
The package chessboard doesnrsquot offer commands to type captions or titles or a list of thechessboards There are no options that control the placement of the board in the textflow eg to center it or to let it float This is a design decision chessboard prints onlychessboards like includegraphics inserts only graphics
21 Bugs and errors
Irsquom quite sure that they are bugs and errors in the package I did find some quite horriblewhile making the documentation and Irsquom sure I overlooked some Eg I have a lot of doubtsif spaces and braces in keys saved in a style or with setchessboard are handled correctlyin every case
If you have questions ask them in the newsgroups comptexttex or decomptexttexIrsquom reading these groups regularly and Irsquom much better in answering there than in answeringe-mails
If you find errors in this text (this includes wrong english) or in the package you can writeme a bugreport at skaknililandde A bugreport should contain a complete minimalexample and the log-file of the pdfLATEX run (this is the engine that makes a pdf)
Before sending a bug record check the following things
If you get mysterious error messages
bull Check the commas in the key=value lists
May 1 2014 5 chessboard 17
Missing or faulty pgf-decorations
bull Check if the borders or marks are hidden under other decorations or under boardchars with solid fieldmasks
bull Check if trimming is responsible try the key trim=false
bull Check the state of the key pgf
bull Try another previewer zoom in and out print the document
bull Go through your log-file and search for chessboard warnings
22 Requirements
The package chessboard uses some primitives of eTEX It needs a recent version of thepackage chessfss (chess font selection) xkeyval (key=value-syntax) and xifthen It also needsthe packages pgfcore pgfbaseshapes (from pgf for the highlighting commands) pst-node(from pstricks)
23 Installation
Run chessboardins through LATEX and then put the four sty-files somewhere whereLATEX finds them lttexmfgttexlatexchessboard is a good place Update the filenamedatabase
24 Robustness using chessboard in moving arguments
I have used chessboard in tabulars and in moving arguments It seems to work fine so Iwould say the command is quite robust
Putting chessboards in the table of contents or the header will in most case not look verygood so it is sensible to avoid it with section[short text]chessboard Title Butif you want to do some advices
bull Boards in the title and in the table of contents are built at different times during therun when perhaps different options and different games are active so they can lookdifferent if you are not careful
bull You canrsquot put boards in the bookmarks of a pdf use texorpdfstring from hyperrefto provide a replacement
bull Some pagestyles puts a command to uppercase around the header This affects keys inthe optional argument of chessboard and will give error messages about undefinedkeys Try to surround the chessboard command with lowercase
May 1 2014 6 chessboard 17
25 Setting the options
The package chessboard use the keyval syntax langkeyrang=langvaluerangIt differs in some respects to other packages with keyval syntax
bull There are really very much keys
bull Some keys donrsquot set properties of a board (like a width) but do things like drawing
bull The order of the keys can matter
bull Some effects are achieved by using two or more keys after one other
There are keys that need a certain type of argument eg a length or a list of fields Thereare boolean keys that accept only the values =true and =false where the value =true canalways be omitted And at last there are keys that works as commands you can use whateverargument you want or leave it blank Donrsquot confound this commands with boolean keys Egclearboard clearboard=hallo and even clearboard=false will always clear the board
Irsquom struggling permanently with the naming of the keys Giving them names that are not tolong but descriptive and a bit systematic isnrsquot easy Also it isnrsquot easy to decide if a specialeffect should be achieve with one key (which gives a short input) or with a combination ofkeys (with is more flexible as it can be used to implement similar effects but gives longerinput) While the package evolved I sometimes tumbled in problems and inconsistencies ofthe current naming scheme and had to reconsider my decisions and implemented betternames or new key combinations I didnrsquot delete or disable older now perhaps obsolate keysin any case as I wanted to avoid that older documents breaks I also sometimes add a keythat is simply a copy of an existing key only to get a more consistent naming So ist quitepossible that you can get the same result with different key combination For a lot of thingsthere isnrsquot one correct way ndash you can choose the one which suits you more
Itrsquos easy to make mistakes when using a lot of keys So if you get mysterious errors check thatyou donrsquot have forgot a comma between the keys that you put braces around lists used asvalue that you didnrsquot use a backslash before a key that you didnrsquot used a list of fields when alist of pieces is requested
You can set an option either for one board by using the optional argument of chessboardsetchessboard
or by using setchessboardlangkey=value listrang which sets the keys for all following boardsin the same environmentgroup
May 1 2014 7 chessboard 17
Default setting in this Dokumentationsetchessboard
Even if they share the same name keys used in the argument of chessboard are implemen-tated differently than the keys used in setchessboard They do different things In thefirst case the key gets ldquoexecutedrdquo while in the second case the key=value pair is only storedfor later use So it is quite possible that a key works with chessboard but fails because of abug when used in setchessboard or vice-versa
Values set by keys in the argument of chessboard will if appropriate overwrite the ones setby setchessboard
The keys belong roughly to two classes There are the keys that set one property of the boardeg the width of a rule or the size Such keys always have a default and only the last value setis used it overwrites all previous values Internally I call such keys ldquoset-keysrdquo In the secondclass there are keys that can be used more than once eg keys that add a piece or a mark ora color to the board I call such keys ldquofill-keysrdquo1
The ldquoset-keysrdquo are always processed first Inside the classes the keys are processed in generalfrom ldquoleft to rightrdquo so later keys can overwrite values set by earlier keys This is also true forvalues hidden in a style
For each ldquoset-keyrdquo you will find in this documentation a box like this
zero=langtrue|falserang zero=false zero false
It shows on the left the general description of the possible values in the middle one or moreexamples of correct input and on the right the default value
For each ldquofill-keyrdquo you will find in this documentation a box like this
clearranks=langlist of ranksrang clearranks=8
It shows on the left the general description of the possible values and on the right one ormore examples of correct input
1I did realize only quite late that using keys not only to set some parameters but also for the real content isa bit unusual It is a bit as if one would use keys for the items of a list or the lines of tabular or the codein a listing ndash in most cases quite a bad idea But at my opinion it works fine in this special case because achessboard is a quite restricted room with only 64 fields
May 1 2014 8 chessboard 17
26 Saving optionlists
style=langnamerang style=mystyle
With the storechessboardstylelangnameranglangkey=value listrang it is possible to store a list ofstorechessboardstyle
key=value-pairs in a ldquostylerdquo and to use this style instead of the keys themselves
storechessboardstyle and setchessboard only store the key=value pair they donrsquotexpand anything and they donrsquot do anything with them So be careful when using commandsthat could be redefined later
In chess the rows of the board are called ranks and are numbered from 1 to 8 The columnsare called files and are ldquonumberedrdquo from a to h2
The package chessboard use this naming conventions for all inputs Every time langfieldrang is usedin this documentation you should give a char from andashz followed by a number
28 Naming areas of the board
Rectangular areas are normally described by giving the coordinates of the left bottom cornerand the right upper corner But when using the Forsyth Edwards Notation (FEN) chessboardsare filled starting from the left upper corner a8 and then going on to the right and down tothe right bottom corner ndash like the normal typesetting direction So it is quite natural to usefor FEN related areas this corners As it would be awkward to have two different ways todescribe areas I decided to use the fen convention everywhere Each area has a startfieldthe left upper corner and a stopfield the right bottom corner If some area related keys donrsquotseem to work check that you have used the correct corners
An area can also be given as two fields separated by an hyphen When using this input youdonrsquot have to worry about the corners the package will sort themlangarearang=langa cornerrang-langthe opposite cornerrangchessboard sets at the start this two command to the current values of the printareaprintarea
board and the total board as given by the keys zero maxfield and printarea You can use thiscommands in later keys
2I have some difficulties to remember the english names so I use the following mnemonics FiLe = coLumn =Linie = alFabet Rank = Row = Reihe = numbeRed
May 1 2014 10 chessboard 17
29 FEN Forsyth-Edwards Notation
FEN describes a chess position It consist of 6 fields separated by spaces The first fieldrepresents the placement of the pieces on the board The second field represents the activecolor A lower case ldquowrdquo is used if White is to move a lower case ldquobrdquo is used if Black is theactive player The third field represents castling availability The fourth field is the en passanttarget square The fifth field is a nonnegative integer representing the halfmove clock Thesixth and last field is a positive integer that gives the fullmove number
In the first field the board contents are specified starting with the eighth rank and endingwith the first rank (ldquoin typesetting directionrdquo when the board has the standard orientation)For each rank the squares are specified from file a to file h White pieces are identified byuppercase piece letters (ldquoPNBRQKrdquo) and black pieces are identified by lowercase piece letters(ldquopnbrqkrdquo) Empty squares are represented by the digits one through eight the digit usedrepresents the count of contiguous empty squares along a rank A solidus character ldquordquo isused to separate data of adjacent ranks
chessboard handles FEN-input but also only ldquoFEN-likerdquo-input If given a complete FENchessboard will store all fields in commands and evaluate the first field to fill the boardBut if they are less than six fields chessboard will not complain but simply fill up themissing fields with some default values
In the first field there donrsquot need to be exact 8 pieces in each rank and exactly 8 rank descrip-tions When there are more pieces than needed chessboard will ignore them When thereare less pieces than needed then chessboard will leave the remaining fields in this rankuntouched
The FEN can also be stored in a command So all chessboard will accept all the followinginputs as langFENrangrnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR w KQkq - 0 1rnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR8qK10 w - - 0 10myfen
210 The main parts of the board
Each chessboard is build by printing three ldquolayersrdquo on top of each other
1 The background layer
This is a pgf-picture that lies under the board It can be used for background colors or fancyborders or other background decoration
May 1 2014 11 chessboard 17
2 The main board layer
This is the main part of the board It lies above the background picture It uses only ldquonormalrdquoLATEX objects like rules and chars Labels movers and figures are all build together in thislayer
3 The mark layer
This layer is again a pgf picture now over the board It can be used to draw crosses arrowsetc on the board
The sections 3 to 5 describe how to manipulate the main layer The section 6 describes howto handle the pgf pictures
3 Setting the contents of the board
31 The maximum number of fields
maxfield=langfieldrang maxfield=j10 h8
Chessboards have 8times8 fields So this is the default If you want another size you shoulddeclare a new right upper corner with maxfield=langFieldrang eg maxfield=j10 for a 10times10board Donrsquot use this key if you want only to print a partial board there is another key toachieve this Use it to change the maximum size of a board All fields and areas you use inother arguments should lie inside this maximum size
I was told that some games numbers the fields starting with 0 So I added this option Whenset to true the rank numbers start with 0 and a file named Z is added left to the file a
clearareas=langlist of areasrang clearareas=a1-c3g7-h8
clearfile=langfilerang clearfile=g
clearfiles=langlist of filesrang clearfiles=gh
clearrank=langrankrang clearrank=5
clearranks=langlist of ranksrang clearranks=87
clearfield=langfieldrang clearfield=c6
clearfields=langlist of fieldsrang clearfields=b5c6
You canrsquot prevent that chessboard fills up the board with the running game so if you needan empty board you should clear it ndash either with the keys mentioned here or by using oneof the keys described later that clears the board before adding new pieces
setwhite=langList of piece positionsrang setwhite=Ke4 Qe1 kd6
addwhite=langList of piece positionsrang addwhite=Ke4 Qe1 kd6
setblack=langList of piece positionsrang setblack=Ke4 Qe1 kd6
addblack=langList of piece positionsrang addblack=Ke4 Qe1 kd6
It is a bit cumbersome to have to be careful to use uppercase chars for the white andlowercase chars for the black piece With the keys setwhite addwhite setblack andaddblack you can add white and black pieces without caring about the cases Like the keysfor adding pieces the keys starting with set first clears the board so if you donrsquot want toloose all the set pieces you should use such a key only once
With this keys you can add pieces to the board by given a FEN The setfen will clear theboard addfen will left pieces outside the fields described by the FEN undisturbed
The package skak has the command storegamelangnamerang that stores the FEN of the currentgame in an internal command and the command savegamelangnamerang that stores the FENin a file langnamerangfenThe package chessboard defines similar keys The key storefen=langnamerang stores the FEN inan internal command with the same name as used by storegamelangnamerang That meansthat you can exchange the games stored by the package skak and the package chessboardbut it also means that the package chessboard can overwrite games stored with the packageskak So be careful
storefen=langnamerang storefen=game1
savefen=langname of filerang savefen=game
storefen saves the current position as FEN to a internal command savefen saves thecurrent position as FEN to a file
startstore=langfieldrang startstore=b7
stopstore=langfieldrang stopstore=f2
storearea=langarearang storearea=c2-d4
With this keys you can restrict the area that is stored or saved But attention the packageskak absolutly doesnrsquot like ldquoillegalrdquo FENs that doesnrsquot describe a full 8times8 board
May 1 2014 17 chessboard 17
mover=langw|brang mover=w
castling=langcastling possibiliesrang castling=Kq
enpassant=langfield|-rang enpassant=c4
halfmove=langnumberrang halfmove=14
fullmove=langnumberrang fullmove=20
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
2011-03-13 (Version 17) Corrected a bug with spacing when the amsart is used
2008-11-27 (Version 16) Corrected a bug in getpiecelists (empty lists were undefined)
2007-12-11 (Version 15) Added the key getpiecelists to retrieve the positions of piecesQuite a lot new keys to show arbitrary positions from previously parsed games areadded by the package xskak Read its documentation if you want to use them
2007-08-20 (Version 15) Added curvemove-style to draw moves Corrected some bugsChanged a lot internally to adapt the package to xskaksty
2007-07-03 (Version 14) Rewrote the code that process the keys saved globally (withchessboard) and in styles (with storechessboardstyle) to go around a problemdue to a change in xkeyval 25 Corrected some errors in the documentation
2006-07-20 (Version 13) Rearranged and rewrote the keys and commands for the pgf-pictures Now all styles and marks can be used in both pictures Added definitions forpartial borders Extended trim and clip commands xifthen is now required
2006-06-22 Added keys for fancy borders added local commands for the boardarea and theprintarea Disabled the option skaknew as it not longer works in the package chessfss
2 Introduction
What is does
This package offers a command chessboard[langkey=value listrang] to print boards of chesschessboard
positions and similar games It is intended to replace the showboard command of thepackage skak which has some deficiencies
bull To print a special position one always has to type the complete FEN
bull It frames all boards with a rule of 1pt ndash which is okay for a large board but doesnrsquot lookgood on small boards
bull Itrsquos difficult (up to impossible) to color some squares
bull Even for simple markings like crosses or the mover the package skak use postscriptThat makes it difficult to use pdfLATEX
bull Itrsquos difficult to print partial boards
bull Itrsquos difficult (up to impossible) to print boards with exotic pieces eg fairy chess
bull Itrsquos impossible to print boards with unusual dimension or unusual labels used by othergames eg 10times10 boards with numbers instead of characters
bull The labels at the bottom changes the baseline which makes it difficult to align boards
May 1 2014 4 chessboard 17
bull Some commands eg notationoff of the package skak redefines skakboard so itis difficult to patch the command eg to get larger margins
With the package chessboard you have now full control about size content and look of theboard I have tried to make chessboard as flexible as possible So I added a lot of optionsto change values that control the size layout and filling of the board In most cases you canignore them but being able to change them can come handy if you need something unusual
But I didnrsquot tried to stretch flexibility too much The main aim of the package is to printchessboards easily so eg the inputs use the naming conventions of chess That means thatndash as the files are numbered alphabetically ndash the width of the board is restricted to 26 fields (27with option zero) The board is build with alternating black and white fields changing to egthree colors could be difficult The pieces are named with simple ASCII-chars so the numberof different pieces is restricted (It is perhaps possible to define piecenames consisting oftwo or more chars and to use such names by putting braces around the chars eg KKa3A small test worked fine for me but I wouldnrsquot bet that it really works everywhere)
What it doesnrsquot
The package chessboard doesnrsquot offer commands to type captions or titles or a list of thechessboards There are no options that control the placement of the board in the textflow eg to center it or to let it float This is a design decision chessboard prints onlychessboards like includegraphics inserts only graphics
21 Bugs and errors
Irsquom quite sure that they are bugs and errors in the package I did find some quite horriblewhile making the documentation and Irsquom sure I overlooked some Eg I have a lot of doubtsif spaces and braces in keys saved in a style or with setchessboard are handled correctlyin every case
If you have questions ask them in the newsgroups comptexttex or decomptexttexIrsquom reading these groups regularly and Irsquom much better in answering there than in answeringe-mails
If you find errors in this text (this includes wrong english) or in the package you can writeme a bugreport at skaknililandde A bugreport should contain a complete minimalexample and the log-file of the pdfLATEX run (this is the engine that makes a pdf)
Before sending a bug record check the following things
If you get mysterious error messages
bull Check the commas in the key=value lists
May 1 2014 5 chessboard 17
Missing or faulty pgf-decorations
bull Check if the borders or marks are hidden under other decorations or under boardchars with solid fieldmasks
bull Check if trimming is responsible try the key trim=false
bull Check the state of the key pgf
bull Try another previewer zoom in and out print the document
bull Go through your log-file and search for chessboard warnings
22 Requirements
The package chessboard uses some primitives of eTEX It needs a recent version of thepackage chessfss (chess font selection) xkeyval (key=value-syntax) and xifthen It also needsthe packages pgfcore pgfbaseshapes (from pgf for the highlighting commands) pst-node(from pstricks)
23 Installation
Run chessboardins through LATEX and then put the four sty-files somewhere whereLATEX finds them lttexmfgttexlatexchessboard is a good place Update the filenamedatabase
24 Robustness using chessboard in moving arguments
I have used chessboard in tabulars and in moving arguments It seems to work fine so Iwould say the command is quite robust
Putting chessboards in the table of contents or the header will in most case not look verygood so it is sensible to avoid it with section[short text]chessboard Title Butif you want to do some advices
bull Boards in the title and in the table of contents are built at different times during therun when perhaps different options and different games are active so they can lookdifferent if you are not careful
bull You canrsquot put boards in the bookmarks of a pdf use texorpdfstring from hyperrefto provide a replacement
bull Some pagestyles puts a command to uppercase around the header This affects keys inthe optional argument of chessboard and will give error messages about undefinedkeys Try to surround the chessboard command with lowercase
May 1 2014 6 chessboard 17
25 Setting the options
The package chessboard use the keyval syntax langkeyrang=langvaluerangIt differs in some respects to other packages with keyval syntax
bull There are really very much keys
bull Some keys donrsquot set properties of a board (like a width) but do things like drawing
bull The order of the keys can matter
bull Some effects are achieved by using two or more keys after one other
There are keys that need a certain type of argument eg a length or a list of fields Thereare boolean keys that accept only the values =true and =false where the value =true canalways be omitted And at last there are keys that works as commands you can use whateverargument you want or leave it blank Donrsquot confound this commands with boolean keys Egclearboard clearboard=hallo and even clearboard=false will always clear the board
Irsquom struggling permanently with the naming of the keys Giving them names that are not tolong but descriptive and a bit systematic isnrsquot easy Also it isnrsquot easy to decide if a specialeffect should be achieve with one key (which gives a short input) or with a combination ofkeys (with is more flexible as it can be used to implement similar effects but gives longerinput) While the package evolved I sometimes tumbled in problems and inconsistencies ofthe current naming scheme and had to reconsider my decisions and implemented betternames or new key combinations I didnrsquot delete or disable older now perhaps obsolate keysin any case as I wanted to avoid that older documents breaks I also sometimes add a keythat is simply a copy of an existing key only to get a more consistent naming So ist quitepossible that you can get the same result with different key combination For a lot of thingsthere isnrsquot one correct way ndash you can choose the one which suits you more
Itrsquos easy to make mistakes when using a lot of keys So if you get mysterious errors check thatyou donrsquot have forgot a comma between the keys that you put braces around lists used asvalue that you didnrsquot use a backslash before a key that you didnrsquot used a list of fields when alist of pieces is requested
You can set an option either for one board by using the optional argument of chessboardsetchessboard
or by using setchessboardlangkey=value listrang which sets the keys for all following boardsin the same environmentgroup
May 1 2014 7 chessboard 17
Default setting in this Dokumentationsetchessboard
Even if they share the same name keys used in the argument of chessboard are implemen-tated differently than the keys used in setchessboard They do different things In thefirst case the key gets ldquoexecutedrdquo while in the second case the key=value pair is only storedfor later use So it is quite possible that a key works with chessboard but fails because of abug when used in setchessboard or vice-versa
Values set by keys in the argument of chessboard will if appropriate overwrite the ones setby setchessboard
The keys belong roughly to two classes There are the keys that set one property of the boardeg the width of a rule or the size Such keys always have a default and only the last value setis used it overwrites all previous values Internally I call such keys ldquoset-keysrdquo In the secondclass there are keys that can be used more than once eg keys that add a piece or a mark ora color to the board I call such keys ldquofill-keysrdquo1
The ldquoset-keysrdquo are always processed first Inside the classes the keys are processed in generalfrom ldquoleft to rightrdquo so later keys can overwrite values set by earlier keys This is also true forvalues hidden in a style
For each ldquoset-keyrdquo you will find in this documentation a box like this
zero=langtrue|falserang zero=false zero false
It shows on the left the general description of the possible values in the middle one or moreexamples of correct input and on the right the default value
For each ldquofill-keyrdquo you will find in this documentation a box like this
clearranks=langlist of ranksrang clearranks=8
It shows on the left the general description of the possible values and on the right one ormore examples of correct input
1I did realize only quite late that using keys not only to set some parameters but also for the real content isa bit unusual It is a bit as if one would use keys for the items of a list or the lines of tabular or the codein a listing ndash in most cases quite a bad idea But at my opinion it works fine in this special case because achessboard is a quite restricted room with only 64 fields
May 1 2014 8 chessboard 17
26 Saving optionlists
style=langnamerang style=mystyle
With the storechessboardstylelangnameranglangkey=value listrang it is possible to store a list ofstorechessboardstyle
key=value-pairs in a ldquostylerdquo and to use this style instead of the keys themselves
storechessboardstyle and setchessboard only store the key=value pair they donrsquotexpand anything and they donrsquot do anything with them So be careful when using commandsthat could be redefined later
In chess the rows of the board are called ranks and are numbered from 1 to 8 The columnsare called files and are ldquonumberedrdquo from a to h2
The package chessboard use this naming conventions for all inputs Every time langfieldrang is usedin this documentation you should give a char from andashz followed by a number
28 Naming areas of the board
Rectangular areas are normally described by giving the coordinates of the left bottom cornerand the right upper corner But when using the Forsyth Edwards Notation (FEN) chessboardsare filled starting from the left upper corner a8 and then going on to the right and down tothe right bottom corner ndash like the normal typesetting direction So it is quite natural to usefor FEN related areas this corners As it would be awkward to have two different ways todescribe areas I decided to use the fen convention everywhere Each area has a startfieldthe left upper corner and a stopfield the right bottom corner If some area related keys donrsquotseem to work check that you have used the correct corners
An area can also be given as two fields separated by an hyphen When using this input youdonrsquot have to worry about the corners the package will sort themlangarearang=langa cornerrang-langthe opposite cornerrangchessboard sets at the start this two command to the current values of the printareaprintarea
board and the total board as given by the keys zero maxfield and printarea You can use thiscommands in later keys
2I have some difficulties to remember the english names so I use the following mnemonics FiLe = coLumn =Linie = alFabet Rank = Row = Reihe = numbeRed
May 1 2014 10 chessboard 17
29 FEN Forsyth-Edwards Notation
FEN describes a chess position It consist of 6 fields separated by spaces The first fieldrepresents the placement of the pieces on the board The second field represents the activecolor A lower case ldquowrdquo is used if White is to move a lower case ldquobrdquo is used if Black is theactive player The third field represents castling availability The fourth field is the en passanttarget square The fifth field is a nonnegative integer representing the halfmove clock Thesixth and last field is a positive integer that gives the fullmove number
In the first field the board contents are specified starting with the eighth rank and endingwith the first rank (ldquoin typesetting directionrdquo when the board has the standard orientation)For each rank the squares are specified from file a to file h White pieces are identified byuppercase piece letters (ldquoPNBRQKrdquo) and black pieces are identified by lowercase piece letters(ldquopnbrqkrdquo) Empty squares are represented by the digits one through eight the digit usedrepresents the count of contiguous empty squares along a rank A solidus character ldquordquo isused to separate data of adjacent ranks
chessboard handles FEN-input but also only ldquoFEN-likerdquo-input If given a complete FENchessboard will store all fields in commands and evaluate the first field to fill the boardBut if they are less than six fields chessboard will not complain but simply fill up themissing fields with some default values
In the first field there donrsquot need to be exact 8 pieces in each rank and exactly 8 rank descrip-tions When there are more pieces than needed chessboard will ignore them When thereare less pieces than needed then chessboard will leave the remaining fields in this rankuntouched
The FEN can also be stored in a command So all chessboard will accept all the followinginputs as langFENrangrnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR w KQkq - 0 1rnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR8qK10 w - - 0 10myfen
210 The main parts of the board
Each chessboard is build by printing three ldquolayersrdquo on top of each other
1 The background layer
This is a pgf-picture that lies under the board It can be used for background colors or fancyborders or other background decoration
May 1 2014 11 chessboard 17
2 The main board layer
This is the main part of the board It lies above the background picture It uses only ldquonormalrdquoLATEX objects like rules and chars Labels movers and figures are all build together in thislayer
3 The mark layer
This layer is again a pgf picture now over the board It can be used to draw crosses arrowsetc on the board
The sections 3 to 5 describe how to manipulate the main layer The section 6 describes howto handle the pgf pictures
3 Setting the contents of the board
31 The maximum number of fields
maxfield=langfieldrang maxfield=j10 h8
Chessboards have 8times8 fields So this is the default If you want another size you shoulddeclare a new right upper corner with maxfield=langFieldrang eg maxfield=j10 for a 10times10board Donrsquot use this key if you want only to print a partial board there is another key toachieve this Use it to change the maximum size of a board All fields and areas you use inother arguments should lie inside this maximum size
I was told that some games numbers the fields starting with 0 So I added this option Whenset to true the rank numbers start with 0 and a file named Z is added left to the file a
clearareas=langlist of areasrang clearareas=a1-c3g7-h8
clearfile=langfilerang clearfile=g
clearfiles=langlist of filesrang clearfiles=gh
clearrank=langrankrang clearrank=5
clearranks=langlist of ranksrang clearranks=87
clearfield=langfieldrang clearfield=c6
clearfields=langlist of fieldsrang clearfields=b5c6
You canrsquot prevent that chessboard fills up the board with the running game so if you needan empty board you should clear it ndash either with the keys mentioned here or by using oneof the keys described later that clears the board before adding new pieces
setwhite=langList of piece positionsrang setwhite=Ke4 Qe1 kd6
addwhite=langList of piece positionsrang addwhite=Ke4 Qe1 kd6
setblack=langList of piece positionsrang setblack=Ke4 Qe1 kd6
addblack=langList of piece positionsrang addblack=Ke4 Qe1 kd6
It is a bit cumbersome to have to be careful to use uppercase chars for the white andlowercase chars for the black piece With the keys setwhite addwhite setblack andaddblack you can add white and black pieces without caring about the cases Like the keysfor adding pieces the keys starting with set first clears the board so if you donrsquot want toloose all the set pieces you should use such a key only once
With this keys you can add pieces to the board by given a FEN The setfen will clear theboard addfen will left pieces outside the fields described by the FEN undisturbed
The package skak has the command storegamelangnamerang that stores the FEN of the currentgame in an internal command and the command savegamelangnamerang that stores the FENin a file langnamerangfenThe package chessboard defines similar keys The key storefen=langnamerang stores the FEN inan internal command with the same name as used by storegamelangnamerang That meansthat you can exchange the games stored by the package skak and the package chessboardbut it also means that the package chessboard can overwrite games stored with the packageskak So be careful
storefen=langnamerang storefen=game1
savefen=langname of filerang savefen=game
storefen saves the current position as FEN to a internal command savefen saves thecurrent position as FEN to a file
startstore=langfieldrang startstore=b7
stopstore=langfieldrang stopstore=f2
storearea=langarearang storearea=c2-d4
With this keys you can restrict the area that is stored or saved But attention the packageskak absolutly doesnrsquot like ldquoillegalrdquo FENs that doesnrsquot describe a full 8times8 board
May 1 2014 17 chessboard 17
mover=langw|brang mover=w
castling=langcastling possibiliesrang castling=Kq
enpassant=langfield|-rang enpassant=c4
halfmove=langnumberrang halfmove=14
fullmove=langnumberrang fullmove=20
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
bull Some commands eg notationoff of the package skak redefines skakboard so itis difficult to patch the command eg to get larger margins
With the package chessboard you have now full control about size content and look of theboard I have tried to make chessboard as flexible as possible So I added a lot of optionsto change values that control the size layout and filling of the board In most cases you canignore them but being able to change them can come handy if you need something unusual
But I didnrsquot tried to stretch flexibility too much The main aim of the package is to printchessboards easily so eg the inputs use the naming conventions of chess That means thatndash as the files are numbered alphabetically ndash the width of the board is restricted to 26 fields (27with option zero) The board is build with alternating black and white fields changing to egthree colors could be difficult The pieces are named with simple ASCII-chars so the numberof different pieces is restricted (It is perhaps possible to define piecenames consisting oftwo or more chars and to use such names by putting braces around the chars eg KKa3A small test worked fine for me but I wouldnrsquot bet that it really works everywhere)
What it doesnrsquot
The package chessboard doesnrsquot offer commands to type captions or titles or a list of thechessboards There are no options that control the placement of the board in the textflow eg to center it or to let it float This is a design decision chessboard prints onlychessboards like includegraphics inserts only graphics
21 Bugs and errors
Irsquom quite sure that they are bugs and errors in the package I did find some quite horriblewhile making the documentation and Irsquom sure I overlooked some Eg I have a lot of doubtsif spaces and braces in keys saved in a style or with setchessboard are handled correctlyin every case
If you have questions ask them in the newsgroups comptexttex or decomptexttexIrsquom reading these groups regularly and Irsquom much better in answering there than in answeringe-mails
If you find errors in this text (this includes wrong english) or in the package you can writeme a bugreport at skaknililandde A bugreport should contain a complete minimalexample and the log-file of the pdfLATEX run (this is the engine that makes a pdf)
Before sending a bug record check the following things
If you get mysterious error messages
bull Check the commas in the key=value lists
May 1 2014 5 chessboard 17
Missing or faulty pgf-decorations
bull Check if the borders or marks are hidden under other decorations or under boardchars with solid fieldmasks
bull Check if trimming is responsible try the key trim=false
bull Check the state of the key pgf
bull Try another previewer zoom in and out print the document
bull Go through your log-file and search for chessboard warnings
22 Requirements
The package chessboard uses some primitives of eTEX It needs a recent version of thepackage chessfss (chess font selection) xkeyval (key=value-syntax) and xifthen It also needsthe packages pgfcore pgfbaseshapes (from pgf for the highlighting commands) pst-node(from pstricks)
23 Installation
Run chessboardins through LATEX and then put the four sty-files somewhere whereLATEX finds them lttexmfgttexlatexchessboard is a good place Update the filenamedatabase
24 Robustness using chessboard in moving arguments
I have used chessboard in tabulars and in moving arguments It seems to work fine so Iwould say the command is quite robust
Putting chessboards in the table of contents or the header will in most case not look verygood so it is sensible to avoid it with section[short text]chessboard Title Butif you want to do some advices
bull Boards in the title and in the table of contents are built at different times during therun when perhaps different options and different games are active so they can lookdifferent if you are not careful
bull You canrsquot put boards in the bookmarks of a pdf use texorpdfstring from hyperrefto provide a replacement
bull Some pagestyles puts a command to uppercase around the header This affects keys inthe optional argument of chessboard and will give error messages about undefinedkeys Try to surround the chessboard command with lowercase
May 1 2014 6 chessboard 17
25 Setting the options
The package chessboard use the keyval syntax langkeyrang=langvaluerangIt differs in some respects to other packages with keyval syntax
bull There are really very much keys
bull Some keys donrsquot set properties of a board (like a width) but do things like drawing
bull The order of the keys can matter
bull Some effects are achieved by using two or more keys after one other
There are keys that need a certain type of argument eg a length or a list of fields Thereare boolean keys that accept only the values =true and =false where the value =true canalways be omitted And at last there are keys that works as commands you can use whateverargument you want or leave it blank Donrsquot confound this commands with boolean keys Egclearboard clearboard=hallo and even clearboard=false will always clear the board
Irsquom struggling permanently with the naming of the keys Giving them names that are not tolong but descriptive and a bit systematic isnrsquot easy Also it isnrsquot easy to decide if a specialeffect should be achieve with one key (which gives a short input) or with a combination ofkeys (with is more flexible as it can be used to implement similar effects but gives longerinput) While the package evolved I sometimes tumbled in problems and inconsistencies ofthe current naming scheme and had to reconsider my decisions and implemented betternames or new key combinations I didnrsquot delete or disable older now perhaps obsolate keysin any case as I wanted to avoid that older documents breaks I also sometimes add a keythat is simply a copy of an existing key only to get a more consistent naming So ist quitepossible that you can get the same result with different key combination For a lot of thingsthere isnrsquot one correct way ndash you can choose the one which suits you more
Itrsquos easy to make mistakes when using a lot of keys So if you get mysterious errors check thatyou donrsquot have forgot a comma between the keys that you put braces around lists used asvalue that you didnrsquot use a backslash before a key that you didnrsquot used a list of fields when alist of pieces is requested
You can set an option either for one board by using the optional argument of chessboardsetchessboard
or by using setchessboardlangkey=value listrang which sets the keys for all following boardsin the same environmentgroup
May 1 2014 7 chessboard 17
Default setting in this Dokumentationsetchessboard
Even if they share the same name keys used in the argument of chessboard are implemen-tated differently than the keys used in setchessboard They do different things In thefirst case the key gets ldquoexecutedrdquo while in the second case the key=value pair is only storedfor later use So it is quite possible that a key works with chessboard but fails because of abug when used in setchessboard or vice-versa
Values set by keys in the argument of chessboard will if appropriate overwrite the ones setby setchessboard
The keys belong roughly to two classes There are the keys that set one property of the boardeg the width of a rule or the size Such keys always have a default and only the last value setis used it overwrites all previous values Internally I call such keys ldquoset-keysrdquo In the secondclass there are keys that can be used more than once eg keys that add a piece or a mark ora color to the board I call such keys ldquofill-keysrdquo1
The ldquoset-keysrdquo are always processed first Inside the classes the keys are processed in generalfrom ldquoleft to rightrdquo so later keys can overwrite values set by earlier keys This is also true forvalues hidden in a style
For each ldquoset-keyrdquo you will find in this documentation a box like this
zero=langtrue|falserang zero=false zero false
It shows on the left the general description of the possible values in the middle one or moreexamples of correct input and on the right the default value
For each ldquofill-keyrdquo you will find in this documentation a box like this
clearranks=langlist of ranksrang clearranks=8
It shows on the left the general description of the possible values and on the right one ormore examples of correct input
1I did realize only quite late that using keys not only to set some parameters but also for the real content isa bit unusual It is a bit as if one would use keys for the items of a list or the lines of tabular or the codein a listing ndash in most cases quite a bad idea But at my opinion it works fine in this special case because achessboard is a quite restricted room with only 64 fields
May 1 2014 8 chessboard 17
26 Saving optionlists
style=langnamerang style=mystyle
With the storechessboardstylelangnameranglangkey=value listrang it is possible to store a list ofstorechessboardstyle
key=value-pairs in a ldquostylerdquo and to use this style instead of the keys themselves
storechessboardstyle and setchessboard only store the key=value pair they donrsquotexpand anything and they donrsquot do anything with them So be careful when using commandsthat could be redefined later
In chess the rows of the board are called ranks and are numbered from 1 to 8 The columnsare called files and are ldquonumberedrdquo from a to h2
The package chessboard use this naming conventions for all inputs Every time langfieldrang is usedin this documentation you should give a char from andashz followed by a number
28 Naming areas of the board
Rectangular areas are normally described by giving the coordinates of the left bottom cornerand the right upper corner But when using the Forsyth Edwards Notation (FEN) chessboardsare filled starting from the left upper corner a8 and then going on to the right and down tothe right bottom corner ndash like the normal typesetting direction So it is quite natural to usefor FEN related areas this corners As it would be awkward to have two different ways todescribe areas I decided to use the fen convention everywhere Each area has a startfieldthe left upper corner and a stopfield the right bottom corner If some area related keys donrsquotseem to work check that you have used the correct corners
An area can also be given as two fields separated by an hyphen When using this input youdonrsquot have to worry about the corners the package will sort themlangarearang=langa cornerrang-langthe opposite cornerrangchessboard sets at the start this two command to the current values of the printareaprintarea
board and the total board as given by the keys zero maxfield and printarea You can use thiscommands in later keys
2I have some difficulties to remember the english names so I use the following mnemonics FiLe = coLumn =Linie = alFabet Rank = Row = Reihe = numbeRed
May 1 2014 10 chessboard 17
29 FEN Forsyth-Edwards Notation
FEN describes a chess position It consist of 6 fields separated by spaces The first fieldrepresents the placement of the pieces on the board The second field represents the activecolor A lower case ldquowrdquo is used if White is to move a lower case ldquobrdquo is used if Black is theactive player The third field represents castling availability The fourth field is the en passanttarget square The fifth field is a nonnegative integer representing the halfmove clock Thesixth and last field is a positive integer that gives the fullmove number
In the first field the board contents are specified starting with the eighth rank and endingwith the first rank (ldquoin typesetting directionrdquo when the board has the standard orientation)For each rank the squares are specified from file a to file h White pieces are identified byuppercase piece letters (ldquoPNBRQKrdquo) and black pieces are identified by lowercase piece letters(ldquopnbrqkrdquo) Empty squares are represented by the digits one through eight the digit usedrepresents the count of contiguous empty squares along a rank A solidus character ldquordquo isused to separate data of adjacent ranks
chessboard handles FEN-input but also only ldquoFEN-likerdquo-input If given a complete FENchessboard will store all fields in commands and evaluate the first field to fill the boardBut if they are less than six fields chessboard will not complain but simply fill up themissing fields with some default values
In the first field there donrsquot need to be exact 8 pieces in each rank and exactly 8 rank descrip-tions When there are more pieces than needed chessboard will ignore them When thereare less pieces than needed then chessboard will leave the remaining fields in this rankuntouched
The FEN can also be stored in a command So all chessboard will accept all the followinginputs as langFENrangrnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR w KQkq - 0 1rnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR8qK10 w - - 0 10myfen
210 The main parts of the board
Each chessboard is build by printing three ldquolayersrdquo on top of each other
1 The background layer
This is a pgf-picture that lies under the board It can be used for background colors or fancyborders or other background decoration
May 1 2014 11 chessboard 17
2 The main board layer
This is the main part of the board It lies above the background picture It uses only ldquonormalrdquoLATEX objects like rules and chars Labels movers and figures are all build together in thislayer
3 The mark layer
This layer is again a pgf picture now over the board It can be used to draw crosses arrowsetc on the board
The sections 3 to 5 describe how to manipulate the main layer The section 6 describes howto handle the pgf pictures
3 Setting the contents of the board
31 The maximum number of fields
maxfield=langfieldrang maxfield=j10 h8
Chessboards have 8times8 fields So this is the default If you want another size you shoulddeclare a new right upper corner with maxfield=langFieldrang eg maxfield=j10 for a 10times10board Donrsquot use this key if you want only to print a partial board there is another key toachieve this Use it to change the maximum size of a board All fields and areas you use inother arguments should lie inside this maximum size
I was told that some games numbers the fields starting with 0 So I added this option Whenset to true the rank numbers start with 0 and a file named Z is added left to the file a
clearareas=langlist of areasrang clearareas=a1-c3g7-h8
clearfile=langfilerang clearfile=g
clearfiles=langlist of filesrang clearfiles=gh
clearrank=langrankrang clearrank=5
clearranks=langlist of ranksrang clearranks=87
clearfield=langfieldrang clearfield=c6
clearfields=langlist of fieldsrang clearfields=b5c6
You canrsquot prevent that chessboard fills up the board with the running game so if you needan empty board you should clear it ndash either with the keys mentioned here or by using oneof the keys described later that clears the board before adding new pieces
setwhite=langList of piece positionsrang setwhite=Ke4 Qe1 kd6
addwhite=langList of piece positionsrang addwhite=Ke4 Qe1 kd6
setblack=langList of piece positionsrang setblack=Ke4 Qe1 kd6
addblack=langList of piece positionsrang addblack=Ke4 Qe1 kd6
It is a bit cumbersome to have to be careful to use uppercase chars for the white andlowercase chars for the black piece With the keys setwhite addwhite setblack andaddblack you can add white and black pieces without caring about the cases Like the keysfor adding pieces the keys starting with set first clears the board so if you donrsquot want toloose all the set pieces you should use such a key only once
With this keys you can add pieces to the board by given a FEN The setfen will clear theboard addfen will left pieces outside the fields described by the FEN undisturbed
The package skak has the command storegamelangnamerang that stores the FEN of the currentgame in an internal command and the command savegamelangnamerang that stores the FENin a file langnamerangfenThe package chessboard defines similar keys The key storefen=langnamerang stores the FEN inan internal command with the same name as used by storegamelangnamerang That meansthat you can exchange the games stored by the package skak and the package chessboardbut it also means that the package chessboard can overwrite games stored with the packageskak So be careful
storefen=langnamerang storefen=game1
savefen=langname of filerang savefen=game
storefen saves the current position as FEN to a internal command savefen saves thecurrent position as FEN to a file
startstore=langfieldrang startstore=b7
stopstore=langfieldrang stopstore=f2
storearea=langarearang storearea=c2-d4
With this keys you can restrict the area that is stored or saved But attention the packageskak absolutly doesnrsquot like ldquoillegalrdquo FENs that doesnrsquot describe a full 8times8 board
May 1 2014 17 chessboard 17
mover=langw|brang mover=w
castling=langcastling possibiliesrang castling=Kq
enpassant=langfield|-rang enpassant=c4
halfmove=langnumberrang halfmove=14
fullmove=langnumberrang fullmove=20
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
bull Check if the borders or marks are hidden under other decorations or under boardchars with solid fieldmasks
bull Check if trimming is responsible try the key trim=false
bull Check the state of the key pgf
bull Try another previewer zoom in and out print the document
bull Go through your log-file and search for chessboard warnings
22 Requirements
The package chessboard uses some primitives of eTEX It needs a recent version of thepackage chessfss (chess font selection) xkeyval (key=value-syntax) and xifthen It also needsthe packages pgfcore pgfbaseshapes (from pgf for the highlighting commands) pst-node(from pstricks)
23 Installation
Run chessboardins through LATEX and then put the four sty-files somewhere whereLATEX finds them lttexmfgttexlatexchessboard is a good place Update the filenamedatabase
24 Robustness using chessboard in moving arguments
I have used chessboard in tabulars and in moving arguments It seems to work fine so Iwould say the command is quite robust
Putting chessboards in the table of contents or the header will in most case not look verygood so it is sensible to avoid it with section[short text]chessboard Title Butif you want to do some advices
bull Boards in the title and in the table of contents are built at different times during therun when perhaps different options and different games are active so they can lookdifferent if you are not careful
bull You canrsquot put boards in the bookmarks of a pdf use texorpdfstring from hyperrefto provide a replacement
bull Some pagestyles puts a command to uppercase around the header This affects keys inthe optional argument of chessboard and will give error messages about undefinedkeys Try to surround the chessboard command with lowercase
May 1 2014 6 chessboard 17
25 Setting the options
The package chessboard use the keyval syntax langkeyrang=langvaluerangIt differs in some respects to other packages with keyval syntax
bull There are really very much keys
bull Some keys donrsquot set properties of a board (like a width) but do things like drawing
bull The order of the keys can matter
bull Some effects are achieved by using two or more keys after one other
There are keys that need a certain type of argument eg a length or a list of fields Thereare boolean keys that accept only the values =true and =false where the value =true canalways be omitted And at last there are keys that works as commands you can use whateverargument you want or leave it blank Donrsquot confound this commands with boolean keys Egclearboard clearboard=hallo and even clearboard=false will always clear the board
Irsquom struggling permanently with the naming of the keys Giving them names that are not tolong but descriptive and a bit systematic isnrsquot easy Also it isnrsquot easy to decide if a specialeffect should be achieve with one key (which gives a short input) or with a combination ofkeys (with is more flexible as it can be used to implement similar effects but gives longerinput) While the package evolved I sometimes tumbled in problems and inconsistencies ofthe current naming scheme and had to reconsider my decisions and implemented betternames or new key combinations I didnrsquot delete or disable older now perhaps obsolate keysin any case as I wanted to avoid that older documents breaks I also sometimes add a keythat is simply a copy of an existing key only to get a more consistent naming So ist quitepossible that you can get the same result with different key combination For a lot of thingsthere isnrsquot one correct way ndash you can choose the one which suits you more
Itrsquos easy to make mistakes when using a lot of keys So if you get mysterious errors check thatyou donrsquot have forgot a comma between the keys that you put braces around lists used asvalue that you didnrsquot use a backslash before a key that you didnrsquot used a list of fields when alist of pieces is requested
You can set an option either for one board by using the optional argument of chessboardsetchessboard
or by using setchessboardlangkey=value listrang which sets the keys for all following boardsin the same environmentgroup
May 1 2014 7 chessboard 17
Default setting in this Dokumentationsetchessboard
Even if they share the same name keys used in the argument of chessboard are implemen-tated differently than the keys used in setchessboard They do different things In thefirst case the key gets ldquoexecutedrdquo while in the second case the key=value pair is only storedfor later use So it is quite possible that a key works with chessboard but fails because of abug when used in setchessboard or vice-versa
Values set by keys in the argument of chessboard will if appropriate overwrite the ones setby setchessboard
The keys belong roughly to two classes There are the keys that set one property of the boardeg the width of a rule or the size Such keys always have a default and only the last value setis used it overwrites all previous values Internally I call such keys ldquoset-keysrdquo In the secondclass there are keys that can be used more than once eg keys that add a piece or a mark ora color to the board I call such keys ldquofill-keysrdquo1
The ldquoset-keysrdquo are always processed first Inside the classes the keys are processed in generalfrom ldquoleft to rightrdquo so later keys can overwrite values set by earlier keys This is also true forvalues hidden in a style
For each ldquoset-keyrdquo you will find in this documentation a box like this
zero=langtrue|falserang zero=false zero false
It shows on the left the general description of the possible values in the middle one or moreexamples of correct input and on the right the default value
For each ldquofill-keyrdquo you will find in this documentation a box like this
clearranks=langlist of ranksrang clearranks=8
It shows on the left the general description of the possible values and on the right one ormore examples of correct input
1I did realize only quite late that using keys not only to set some parameters but also for the real content isa bit unusual It is a bit as if one would use keys for the items of a list or the lines of tabular or the codein a listing ndash in most cases quite a bad idea But at my opinion it works fine in this special case because achessboard is a quite restricted room with only 64 fields
May 1 2014 8 chessboard 17
26 Saving optionlists
style=langnamerang style=mystyle
With the storechessboardstylelangnameranglangkey=value listrang it is possible to store a list ofstorechessboardstyle
key=value-pairs in a ldquostylerdquo and to use this style instead of the keys themselves
storechessboardstyle and setchessboard only store the key=value pair they donrsquotexpand anything and they donrsquot do anything with them So be careful when using commandsthat could be redefined later
In chess the rows of the board are called ranks and are numbered from 1 to 8 The columnsare called files and are ldquonumberedrdquo from a to h2
The package chessboard use this naming conventions for all inputs Every time langfieldrang is usedin this documentation you should give a char from andashz followed by a number
28 Naming areas of the board
Rectangular areas are normally described by giving the coordinates of the left bottom cornerand the right upper corner But when using the Forsyth Edwards Notation (FEN) chessboardsare filled starting from the left upper corner a8 and then going on to the right and down tothe right bottom corner ndash like the normal typesetting direction So it is quite natural to usefor FEN related areas this corners As it would be awkward to have two different ways todescribe areas I decided to use the fen convention everywhere Each area has a startfieldthe left upper corner and a stopfield the right bottom corner If some area related keys donrsquotseem to work check that you have used the correct corners
An area can also be given as two fields separated by an hyphen When using this input youdonrsquot have to worry about the corners the package will sort themlangarearang=langa cornerrang-langthe opposite cornerrangchessboard sets at the start this two command to the current values of the printareaprintarea
board and the total board as given by the keys zero maxfield and printarea You can use thiscommands in later keys
2I have some difficulties to remember the english names so I use the following mnemonics FiLe = coLumn =Linie = alFabet Rank = Row = Reihe = numbeRed
May 1 2014 10 chessboard 17
29 FEN Forsyth-Edwards Notation
FEN describes a chess position It consist of 6 fields separated by spaces The first fieldrepresents the placement of the pieces on the board The second field represents the activecolor A lower case ldquowrdquo is used if White is to move a lower case ldquobrdquo is used if Black is theactive player The third field represents castling availability The fourth field is the en passanttarget square The fifth field is a nonnegative integer representing the halfmove clock Thesixth and last field is a positive integer that gives the fullmove number
In the first field the board contents are specified starting with the eighth rank and endingwith the first rank (ldquoin typesetting directionrdquo when the board has the standard orientation)For each rank the squares are specified from file a to file h White pieces are identified byuppercase piece letters (ldquoPNBRQKrdquo) and black pieces are identified by lowercase piece letters(ldquopnbrqkrdquo) Empty squares are represented by the digits one through eight the digit usedrepresents the count of contiguous empty squares along a rank A solidus character ldquordquo isused to separate data of adjacent ranks
chessboard handles FEN-input but also only ldquoFEN-likerdquo-input If given a complete FENchessboard will store all fields in commands and evaluate the first field to fill the boardBut if they are less than six fields chessboard will not complain but simply fill up themissing fields with some default values
In the first field there donrsquot need to be exact 8 pieces in each rank and exactly 8 rank descrip-tions When there are more pieces than needed chessboard will ignore them When thereare less pieces than needed then chessboard will leave the remaining fields in this rankuntouched
The FEN can also be stored in a command So all chessboard will accept all the followinginputs as langFENrangrnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR w KQkq - 0 1rnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR8qK10 w - - 0 10myfen
210 The main parts of the board
Each chessboard is build by printing three ldquolayersrdquo on top of each other
1 The background layer
This is a pgf-picture that lies under the board It can be used for background colors or fancyborders or other background decoration
May 1 2014 11 chessboard 17
2 The main board layer
This is the main part of the board It lies above the background picture It uses only ldquonormalrdquoLATEX objects like rules and chars Labels movers and figures are all build together in thislayer
3 The mark layer
This layer is again a pgf picture now over the board It can be used to draw crosses arrowsetc on the board
The sections 3 to 5 describe how to manipulate the main layer The section 6 describes howto handle the pgf pictures
3 Setting the contents of the board
31 The maximum number of fields
maxfield=langfieldrang maxfield=j10 h8
Chessboards have 8times8 fields So this is the default If you want another size you shoulddeclare a new right upper corner with maxfield=langFieldrang eg maxfield=j10 for a 10times10board Donrsquot use this key if you want only to print a partial board there is another key toachieve this Use it to change the maximum size of a board All fields and areas you use inother arguments should lie inside this maximum size
I was told that some games numbers the fields starting with 0 So I added this option Whenset to true the rank numbers start with 0 and a file named Z is added left to the file a
clearareas=langlist of areasrang clearareas=a1-c3g7-h8
clearfile=langfilerang clearfile=g
clearfiles=langlist of filesrang clearfiles=gh
clearrank=langrankrang clearrank=5
clearranks=langlist of ranksrang clearranks=87
clearfield=langfieldrang clearfield=c6
clearfields=langlist of fieldsrang clearfields=b5c6
You canrsquot prevent that chessboard fills up the board with the running game so if you needan empty board you should clear it ndash either with the keys mentioned here or by using oneof the keys described later that clears the board before adding new pieces
setwhite=langList of piece positionsrang setwhite=Ke4 Qe1 kd6
addwhite=langList of piece positionsrang addwhite=Ke4 Qe1 kd6
setblack=langList of piece positionsrang setblack=Ke4 Qe1 kd6
addblack=langList of piece positionsrang addblack=Ke4 Qe1 kd6
It is a bit cumbersome to have to be careful to use uppercase chars for the white andlowercase chars for the black piece With the keys setwhite addwhite setblack andaddblack you can add white and black pieces without caring about the cases Like the keysfor adding pieces the keys starting with set first clears the board so if you donrsquot want toloose all the set pieces you should use such a key only once
With this keys you can add pieces to the board by given a FEN The setfen will clear theboard addfen will left pieces outside the fields described by the FEN undisturbed
The package skak has the command storegamelangnamerang that stores the FEN of the currentgame in an internal command and the command savegamelangnamerang that stores the FENin a file langnamerangfenThe package chessboard defines similar keys The key storefen=langnamerang stores the FEN inan internal command with the same name as used by storegamelangnamerang That meansthat you can exchange the games stored by the package skak and the package chessboardbut it also means that the package chessboard can overwrite games stored with the packageskak So be careful
storefen=langnamerang storefen=game1
savefen=langname of filerang savefen=game
storefen saves the current position as FEN to a internal command savefen saves thecurrent position as FEN to a file
startstore=langfieldrang startstore=b7
stopstore=langfieldrang stopstore=f2
storearea=langarearang storearea=c2-d4
With this keys you can restrict the area that is stored or saved But attention the packageskak absolutly doesnrsquot like ldquoillegalrdquo FENs that doesnrsquot describe a full 8times8 board
May 1 2014 17 chessboard 17
mover=langw|brang mover=w
castling=langcastling possibiliesrang castling=Kq
enpassant=langfield|-rang enpassant=c4
halfmove=langnumberrang halfmove=14
fullmove=langnumberrang fullmove=20
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
The package chessboard use the keyval syntax langkeyrang=langvaluerangIt differs in some respects to other packages with keyval syntax
bull There are really very much keys
bull Some keys donrsquot set properties of a board (like a width) but do things like drawing
bull The order of the keys can matter
bull Some effects are achieved by using two or more keys after one other
There are keys that need a certain type of argument eg a length or a list of fields Thereare boolean keys that accept only the values =true and =false where the value =true canalways be omitted And at last there are keys that works as commands you can use whateverargument you want or leave it blank Donrsquot confound this commands with boolean keys Egclearboard clearboard=hallo and even clearboard=false will always clear the board
Irsquom struggling permanently with the naming of the keys Giving them names that are not tolong but descriptive and a bit systematic isnrsquot easy Also it isnrsquot easy to decide if a specialeffect should be achieve with one key (which gives a short input) or with a combination ofkeys (with is more flexible as it can be used to implement similar effects but gives longerinput) While the package evolved I sometimes tumbled in problems and inconsistencies ofthe current naming scheme and had to reconsider my decisions and implemented betternames or new key combinations I didnrsquot delete or disable older now perhaps obsolate keysin any case as I wanted to avoid that older documents breaks I also sometimes add a keythat is simply a copy of an existing key only to get a more consistent naming So ist quitepossible that you can get the same result with different key combination For a lot of thingsthere isnrsquot one correct way ndash you can choose the one which suits you more
Itrsquos easy to make mistakes when using a lot of keys So if you get mysterious errors check thatyou donrsquot have forgot a comma between the keys that you put braces around lists used asvalue that you didnrsquot use a backslash before a key that you didnrsquot used a list of fields when alist of pieces is requested
You can set an option either for one board by using the optional argument of chessboardsetchessboard
or by using setchessboardlangkey=value listrang which sets the keys for all following boardsin the same environmentgroup
May 1 2014 7 chessboard 17
Default setting in this Dokumentationsetchessboard
Even if they share the same name keys used in the argument of chessboard are implemen-tated differently than the keys used in setchessboard They do different things In thefirst case the key gets ldquoexecutedrdquo while in the second case the key=value pair is only storedfor later use So it is quite possible that a key works with chessboard but fails because of abug when used in setchessboard or vice-versa
Values set by keys in the argument of chessboard will if appropriate overwrite the ones setby setchessboard
The keys belong roughly to two classes There are the keys that set one property of the boardeg the width of a rule or the size Such keys always have a default and only the last value setis used it overwrites all previous values Internally I call such keys ldquoset-keysrdquo In the secondclass there are keys that can be used more than once eg keys that add a piece or a mark ora color to the board I call such keys ldquofill-keysrdquo1
The ldquoset-keysrdquo are always processed first Inside the classes the keys are processed in generalfrom ldquoleft to rightrdquo so later keys can overwrite values set by earlier keys This is also true forvalues hidden in a style
For each ldquoset-keyrdquo you will find in this documentation a box like this
zero=langtrue|falserang zero=false zero false
It shows on the left the general description of the possible values in the middle one or moreexamples of correct input and on the right the default value
For each ldquofill-keyrdquo you will find in this documentation a box like this
clearranks=langlist of ranksrang clearranks=8
It shows on the left the general description of the possible values and on the right one ormore examples of correct input
1I did realize only quite late that using keys not only to set some parameters but also for the real content isa bit unusual It is a bit as if one would use keys for the items of a list or the lines of tabular or the codein a listing ndash in most cases quite a bad idea But at my opinion it works fine in this special case because achessboard is a quite restricted room with only 64 fields
May 1 2014 8 chessboard 17
26 Saving optionlists
style=langnamerang style=mystyle
With the storechessboardstylelangnameranglangkey=value listrang it is possible to store a list ofstorechessboardstyle
key=value-pairs in a ldquostylerdquo and to use this style instead of the keys themselves
storechessboardstyle and setchessboard only store the key=value pair they donrsquotexpand anything and they donrsquot do anything with them So be careful when using commandsthat could be redefined later
In chess the rows of the board are called ranks and are numbered from 1 to 8 The columnsare called files and are ldquonumberedrdquo from a to h2
The package chessboard use this naming conventions for all inputs Every time langfieldrang is usedin this documentation you should give a char from andashz followed by a number
28 Naming areas of the board
Rectangular areas are normally described by giving the coordinates of the left bottom cornerand the right upper corner But when using the Forsyth Edwards Notation (FEN) chessboardsare filled starting from the left upper corner a8 and then going on to the right and down tothe right bottom corner ndash like the normal typesetting direction So it is quite natural to usefor FEN related areas this corners As it would be awkward to have two different ways todescribe areas I decided to use the fen convention everywhere Each area has a startfieldthe left upper corner and a stopfield the right bottom corner If some area related keys donrsquotseem to work check that you have used the correct corners
An area can also be given as two fields separated by an hyphen When using this input youdonrsquot have to worry about the corners the package will sort themlangarearang=langa cornerrang-langthe opposite cornerrangchessboard sets at the start this two command to the current values of the printareaprintarea
board and the total board as given by the keys zero maxfield and printarea You can use thiscommands in later keys
2I have some difficulties to remember the english names so I use the following mnemonics FiLe = coLumn =Linie = alFabet Rank = Row = Reihe = numbeRed
May 1 2014 10 chessboard 17
29 FEN Forsyth-Edwards Notation
FEN describes a chess position It consist of 6 fields separated by spaces The first fieldrepresents the placement of the pieces on the board The second field represents the activecolor A lower case ldquowrdquo is used if White is to move a lower case ldquobrdquo is used if Black is theactive player The third field represents castling availability The fourth field is the en passanttarget square The fifth field is a nonnegative integer representing the halfmove clock Thesixth and last field is a positive integer that gives the fullmove number
In the first field the board contents are specified starting with the eighth rank and endingwith the first rank (ldquoin typesetting directionrdquo when the board has the standard orientation)For each rank the squares are specified from file a to file h White pieces are identified byuppercase piece letters (ldquoPNBRQKrdquo) and black pieces are identified by lowercase piece letters(ldquopnbrqkrdquo) Empty squares are represented by the digits one through eight the digit usedrepresents the count of contiguous empty squares along a rank A solidus character ldquordquo isused to separate data of adjacent ranks
chessboard handles FEN-input but also only ldquoFEN-likerdquo-input If given a complete FENchessboard will store all fields in commands and evaluate the first field to fill the boardBut if they are less than six fields chessboard will not complain but simply fill up themissing fields with some default values
In the first field there donrsquot need to be exact 8 pieces in each rank and exactly 8 rank descrip-tions When there are more pieces than needed chessboard will ignore them When thereare less pieces than needed then chessboard will leave the remaining fields in this rankuntouched
The FEN can also be stored in a command So all chessboard will accept all the followinginputs as langFENrangrnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR w KQkq - 0 1rnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR8qK10 w - - 0 10myfen
210 The main parts of the board
Each chessboard is build by printing three ldquolayersrdquo on top of each other
1 The background layer
This is a pgf-picture that lies under the board It can be used for background colors or fancyborders or other background decoration
May 1 2014 11 chessboard 17
2 The main board layer
This is the main part of the board It lies above the background picture It uses only ldquonormalrdquoLATEX objects like rules and chars Labels movers and figures are all build together in thislayer
3 The mark layer
This layer is again a pgf picture now over the board It can be used to draw crosses arrowsetc on the board
The sections 3 to 5 describe how to manipulate the main layer The section 6 describes howto handle the pgf pictures
3 Setting the contents of the board
31 The maximum number of fields
maxfield=langfieldrang maxfield=j10 h8
Chessboards have 8times8 fields So this is the default If you want another size you shoulddeclare a new right upper corner with maxfield=langFieldrang eg maxfield=j10 for a 10times10board Donrsquot use this key if you want only to print a partial board there is another key toachieve this Use it to change the maximum size of a board All fields and areas you use inother arguments should lie inside this maximum size
I was told that some games numbers the fields starting with 0 So I added this option Whenset to true the rank numbers start with 0 and a file named Z is added left to the file a
clearareas=langlist of areasrang clearareas=a1-c3g7-h8
clearfile=langfilerang clearfile=g
clearfiles=langlist of filesrang clearfiles=gh
clearrank=langrankrang clearrank=5
clearranks=langlist of ranksrang clearranks=87
clearfield=langfieldrang clearfield=c6
clearfields=langlist of fieldsrang clearfields=b5c6
You canrsquot prevent that chessboard fills up the board with the running game so if you needan empty board you should clear it ndash either with the keys mentioned here or by using oneof the keys described later that clears the board before adding new pieces
setwhite=langList of piece positionsrang setwhite=Ke4 Qe1 kd6
addwhite=langList of piece positionsrang addwhite=Ke4 Qe1 kd6
setblack=langList of piece positionsrang setblack=Ke4 Qe1 kd6
addblack=langList of piece positionsrang addblack=Ke4 Qe1 kd6
It is a bit cumbersome to have to be careful to use uppercase chars for the white andlowercase chars for the black piece With the keys setwhite addwhite setblack andaddblack you can add white and black pieces without caring about the cases Like the keysfor adding pieces the keys starting with set first clears the board so if you donrsquot want toloose all the set pieces you should use such a key only once
With this keys you can add pieces to the board by given a FEN The setfen will clear theboard addfen will left pieces outside the fields described by the FEN undisturbed
The package skak has the command storegamelangnamerang that stores the FEN of the currentgame in an internal command and the command savegamelangnamerang that stores the FENin a file langnamerangfenThe package chessboard defines similar keys The key storefen=langnamerang stores the FEN inan internal command with the same name as used by storegamelangnamerang That meansthat you can exchange the games stored by the package skak and the package chessboardbut it also means that the package chessboard can overwrite games stored with the packageskak So be careful
storefen=langnamerang storefen=game1
savefen=langname of filerang savefen=game
storefen saves the current position as FEN to a internal command savefen saves thecurrent position as FEN to a file
startstore=langfieldrang startstore=b7
stopstore=langfieldrang stopstore=f2
storearea=langarearang storearea=c2-d4
With this keys you can restrict the area that is stored or saved But attention the packageskak absolutly doesnrsquot like ldquoillegalrdquo FENs that doesnrsquot describe a full 8times8 board
May 1 2014 17 chessboard 17
mover=langw|brang mover=w
castling=langcastling possibiliesrang castling=Kq
enpassant=langfield|-rang enpassant=c4
halfmove=langnumberrang halfmove=14
fullmove=langnumberrang fullmove=20
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
Even if they share the same name keys used in the argument of chessboard are implemen-tated differently than the keys used in setchessboard They do different things In thefirst case the key gets ldquoexecutedrdquo while in the second case the key=value pair is only storedfor later use So it is quite possible that a key works with chessboard but fails because of abug when used in setchessboard or vice-versa
Values set by keys in the argument of chessboard will if appropriate overwrite the ones setby setchessboard
The keys belong roughly to two classes There are the keys that set one property of the boardeg the width of a rule or the size Such keys always have a default and only the last value setis used it overwrites all previous values Internally I call such keys ldquoset-keysrdquo In the secondclass there are keys that can be used more than once eg keys that add a piece or a mark ora color to the board I call such keys ldquofill-keysrdquo1
The ldquoset-keysrdquo are always processed first Inside the classes the keys are processed in generalfrom ldquoleft to rightrdquo so later keys can overwrite values set by earlier keys This is also true forvalues hidden in a style
For each ldquoset-keyrdquo you will find in this documentation a box like this
zero=langtrue|falserang zero=false zero false
It shows on the left the general description of the possible values in the middle one or moreexamples of correct input and on the right the default value
For each ldquofill-keyrdquo you will find in this documentation a box like this
clearranks=langlist of ranksrang clearranks=8
It shows on the left the general description of the possible values and on the right one ormore examples of correct input
1I did realize only quite late that using keys not only to set some parameters but also for the real content isa bit unusual It is a bit as if one would use keys for the items of a list or the lines of tabular or the codein a listing ndash in most cases quite a bad idea But at my opinion it works fine in this special case because achessboard is a quite restricted room with only 64 fields
May 1 2014 8 chessboard 17
26 Saving optionlists
style=langnamerang style=mystyle
With the storechessboardstylelangnameranglangkey=value listrang it is possible to store a list ofstorechessboardstyle
key=value-pairs in a ldquostylerdquo and to use this style instead of the keys themselves
storechessboardstyle and setchessboard only store the key=value pair they donrsquotexpand anything and they donrsquot do anything with them So be careful when using commandsthat could be redefined later
In chess the rows of the board are called ranks and are numbered from 1 to 8 The columnsare called files and are ldquonumberedrdquo from a to h2
The package chessboard use this naming conventions for all inputs Every time langfieldrang is usedin this documentation you should give a char from andashz followed by a number
28 Naming areas of the board
Rectangular areas are normally described by giving the coordinates of the left bottom cornerand the right upper corner But when using the Forsyth Edwards Notation (FEN) chessboardsare filled starting from the left upper corner a8 and then going on to the right and down tothe right bottom corner ndash like the normal typesetting direction So it is quite natural to usefor FEN related areas this corners As it would be awkward to have two different ways todescribe areas I decided to use the fen convention everywhere Each area has a startfieldthe left upper corner and a stopfield the right bottom corner If some area related keys donrsquotseem to work check that you have used the correct corners
An area can also be given as two fields separated by an hyphen When using this input youdonrsquot have to worry about the corners the package will sort themlangarearang=langa cornerrang-langthe opposite cornerrangchessboard sets at the start this two command to the current values of the printareaprintarea
board and the total board as given by the keys zero maxfield and printarea You can use thiscommands in later keys
2I have some difficulties to remember the english names so I use the following mnemonics FiLe = coLumn =Linie = alFabet Rank = Row = Reihe = numbeRed
May 1 2014 10 chessboard 17
29 FEN Forsyth-Edwards Notation
FEN describes a chess position It consist of 6 fields separated by spaces The first fieldrepresents the placement of the pieces on the board The second field represents the activecolor A lower case ldquowrdquo is used if White is to move a lower case ldquobrdquo is used if Black is theactive player The third field represents castling availability The fourth field is the en passanttarget square The fifth field is a nonnegative integer representing the halfmove clock Thesixth and last field is a positive integer that gives the fullmove number
In the first field the board contents are specified starting with the eighth rank and endingwith the first rank (ldquoin typesetting directionrdquo when the board has the standard orientation)For each rank the squares are specified from file a to file h White pieces are identified byuppercase piece letters (ldquoPNBRQKrdquo) and black pieces are identified by lowercase piece letters(ldquopnbrqkrdquo) Empty squares are represented by the digits one through eight the digit usedrepresents the count of contiguous empty squares along a rank A solidus character ldquordquo isused to separate data of adjacent ranks
chessboard handles FEN-input but also only ldquoFEN-likerdquo-input If given a complete FENchessboard will store all fields in commands and evaluate the first field to fill the boardBut if they are less than six fields chessboard will not complain but simply fill up themissing fields with some default values
In the first field there donrsquot need to be exact 8 pieces in each rank and exactly 8 rank descrip-tions When there are more pieces than needed chessboard will ignore them When thereare less pieces than needed then chessboard will leave the remaining fields in this rankuntouched
The FEN can also be stored in a command So all chessboard will accept all the followinginputs as langFENrangrnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR w KQkq - 0 1rnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR8qK10 w - - 0 10myfen
210 The main parts of the board
Each chessboard is build by printing three ldquolayersrdquo on top of each other
1 The background layer
This is a pgf-picture that lies under the board It can be used for background colors or fancyborders or other background decoration
May 1 2014 11 chessboard 17
2 The main board layer
This is the main part of the board It lies above the background picture It uses only ldquonormalrdquoLATEX objects like rules and chars Labels movers and figures are all build together in thislayer
3 The mark layer
This layer is again a pgf picture now over the board It can be used to draw crosses arrowsetc on the board
The sections 3 to 5 describe how to manipulate the main layer The section 6 describes howto handle the pgf pictures
3 Setting the contents of the board
31 The maximum number of fields
maxfield=langfieldrang maxfield=j10 h8
Chessboards have 8times8 fields So this is the default If you want another size you shoulddeclare a new right upper corner with maxfield=langFieldrang eg maxfield=j10 for a 10times10board Donrsquot use this key if you want only to print a partial board there is another key toachieve this Use it to change the maximum size of a board All fields and areas you use inother arguments should lie inside this maximum size
I was told that some games numbers the fields starting with 0 So I added this option Whenset to true the rank numbers start with 0 and a file named Z is added left to the file a
clearareas=langlist of areasrang clearareas=a1-c3g7-h8
clearfile=langfilerang clearfile=g
clearfiles=langlist of filesrang clearfiles=gh
clearrank=langrankrang clearrank=5
clearranks=langlist of ranksrang clearranks=87
clearfield=langfieldrang clearfield=c6
clearfields=langlist of fieldsrang clearfields=b5c6
You canrsquot prevent that chessboard fills up the board with the running game so if you needan empty board you should clear it ndash either with the keys mentioned here or by using oneof the keys described later that clears the board before adding new pieces
setwhite=langList of piece positionsrang setwhite=Ke4 Qe1 kd6
addwhite=langList of piece positionsrang addwhite=Ke4 Qe1 kd6
setblack=langList of piece positionsrang setblack=Ke4 Qe1 kd6
addblack=langList of piece positionsrang addblack=Ke4 Qe1 kd6
It is a bit cumbersome to have to be careful to use uppercase chars for the white andlowercase chars for the black piece With the keys setwhite addwhite setblack andaddblack you can add white and black pieces without caring about the cases Like the keysfor adding pieces the keys starting with set first clears the board so if you donrsquot want toloose all the set pieces you should use such a key only once
With this keys you can add pieces to the board by given a FEN The setfen will clear theboard addfen will left pieces outside the fields described by the FEN undisturbed
The package skak has the command storegamelangnamerang that stores the FEN of the currentgame in an internal command and the command savegamelangnamerang that stores the FENin a file langnamerangfenThe package chessboard defines similar keys The key storefen=langnamerang stores the FEN inan internal command with the same name as used by storegamelangnamerang That meansthat you can exchange the games stored by the package skak and the package chessboardbut it also means that the package chessboard can overwrite games stored with the packageskak So be careful
storefen=langnamerang storefen=game1
savefen=langname of filerang savefen=game
storefen saves the current position as FEN to a internal command savefen saves thecurrent position as FEN to a file
startstore=langfieldrang startstore=b7
stopstore=langfieldrang stopstore=f2
storearea=langarearang storearea=c2-d4
With this keys you can restrict the area that is stored or saved But attention the packageskak absolutly doesnrsquot like ldquoillegalrdquo FENs that doesnrsquot describe a full 8times8 board
May 1 2014 17 chessboard 17
mover=langw|brang mover=w
castling=langcastling possibiliesrang castling=Kq
enpassant=langfield|-rang enpassant=c4
halfmove=langnumberrang halfmove=14
fullmove=langnumberrang fullmove=20
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
storechessboardstyle and setchessboard only store the key=value pair they donrsquotexpand anything and they donrsquot do anything with them So be careful when using commandsthat could be redefined later
In chess the rows of the board are called ranks and are numbered from 1 to 8 The columnsare called files and are ldquonumberedrdquo from a to h2
The package chessboard use this naming conventions for all inputs Every time langfieldrang is usedin this documentation you should give a char from andashz followed by a number
28 Naming areas of the board
Rectangular areas are normally described by giving the coordinates of the left bottom cornerand the right upper corner But when using the Forsyth Edwards Notation (FEN) chessboardsare filled starting from the left upper corner a8 and then going on to the right and down tothe right bottom corner ndash like the normal typesetting direction So it is quite natural to usefor FEN related areas this corners As it would be awkward to have two different ways todescribe areas I decided to use the fen convention everywhere Each area has a startfieldthe left upper corner and a stopfield the right bottom corner If some area related keys donrsquotseem to work check that you have used the correct corners
An area can also be given as two fields separated by an hyphen When using this input youdonrsquot have to worry about the corners the package will sort themlangarearang=langa cornerrang-langthe opposite cornerrangchessboard sets at the start this two command to the current values of the printareaprintarea
board and the total board as given by the keys zero maxfield and printarea You can use thiscommands in later keys
2I have some difficulties to remember the english names so I use the following mnemonics FiLe = coLumn =Linie = alFabet Rank = Row = Reihe = numbeRed
May 1 2014 10 chessboard 17
29 FEN Forsyth-Edwards Notation
FEN describes a chess position It consist of 6 fields separated by spaces The first fieldrepresents the placement of the pieces on the board The second field represents the activecolor A lower case ldquowrdquo is used if White is to move a lower case ldquobrdquo is used if Black is theactive player The third field represents castling availability The fourth field is the en passanttarget square The fifth field is a nonnegative integer representing the halfmove clock Thesixth and last field is a positive integer that gives the fullmove number
In the first field the board contents are specified starting with the eighth rank and endingwith the first rank (ldquoin typesetting directionrdquo when the board has the standard orientation)For each rank the squares are specified from file a to file h White pieces are identified byuppercase piece letters (ldquoPNBRQKrdquo) and black pieces are identified by lowercase piece letters(ldquopnbrqkrdquo) Empty squares are represented by the digits one through eight the digit usedrepresents the count of contiguous empty squares along a rank A solidus character ldquordquo isused to separate data of adjacent ranks
chessboard handles FEN-input but also only ldquoFEN-likerdquo-input If given a complete FENchessboard will store all fields in commands and evaluate the first field to fill the boardBut if they are less than six fields chessboard will not complain but simply fill up themissing fields with some default values
In the first field there donrsquot need to be exact 8 pieces in each rank and exactly 8 rank descrip-tions When there are more pieces than needed chessboard will ignore them When thereare less pieces than needed then chessboard will leave the remaining fields in this rankuntouched
The FEN can also be stored in a command So all chessboard will accept all the followinginputs as langFENrangrnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR w KQkq - 0 1rnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR8qK10 w - - 0 10myfen
210 The main parts of the board
Each chessboard is build by printing three ldquolayersrdquo on top of each other
1 The background layer
This is a pgf-picture that lies under the board It can be used for background colors or fancyborders or other background decoration
May 1 2014 11 chessboard 17
2 The main board layer
This is the main part of the board It lies above the background picture It uses only ldquonormalrdquoLATEX objects like rules and chars Labels movers and figures are all build together in thislayer
3 The mark layer
This layer is again a pgf picture now over the board It can be used to draw crosses arrowsetc on the board
The sections 3 to 5 describe how to manipulate the main layer The section 6 describes howto handle the pgf pictures
3 Setting the contents of the board
31 The maximum number of fields
maxfield=langfieldrang maxfield=j10 h8
Chessboards have 8times8 fields So this is the default If you want another size you shoulddeclare a new right upper corner with maxfield=langFieldrang eg maxfield=j10 for a 10times10board Donrsquot use this key if you want only to print a partial board there is another key toachieve this Use it to change the maximum size of a board All fields and areas you use inother arguments should lie inside this maximum size
I was told that some games numbers the fields starting with 0 So I added this option Whenset to true the rank numbers start with 0 and a file named Z is added left to the file a
clearareas=langlist of areasrang clearareas=a1-c3g7-h8
clearfile=langfilerang clearfile=g
clearfiles=langlist of filesrang clearfiles=gh
clearrank=langrankrang clearrank=5
clearranks=langlist of ranksrang clearranks=87
clearfield=langfieldrang clearfield=c6
clearfields=langlist of fieldsrang clearfields=b5c6
You canrsquot prevent that chessboard fills up the board with the running game so if you needan empty board you should clear it ndash either with the keys mentioned here or by using oneof the keys described later that clears the board before adding new pieces
setwhite=langList of piece positionsrang setwhite=Ke4 Qe1 kd6
addwhite=langList of piece positionsrang addwhite=Ke4 Qe1 kd6
setblack=langList of piece positionsrang setblack=Ke4 Qe1 kd6
addblack=langList of piece positionsrang addblack=Ke4 Qe1 kd6
It is a bit cumbersome to have to be careful to use uppercase chars for the white andlowercase chars for the black piece With the keys setwhite addwhite setblack andaddblack you can add white and black pieces without caring about the cases Like the keysfor adding pieces the keys starting with set first clears the board so if you donrsquot want toloose all the set pieces you should use such a key only once
With this keys you can add pieces to the board by given a FEN The setfen will clear theboard addfen will left pieces outside the fields described by the FEN undisturbed
The package skak has the command storegamelangnamerang that stores the FEN of the currentgame in an internal command and the command savegamelangnamerang that stores the FENin a file langnamerangfenThe package chessboard defines similar keys The key storefen=langnamerang stores the FEN inan internal command with the same name as used by storegamelangnamerang That meansthat you can exchange the games stored by the package skak and the package chessboardbut it also means that the package chessboard can overwrite games stored with the packageskak So be careful
storefen=langnamerang storefen=game1
savefen=langname of filerang savefen=game
storefen saves the current position as FEN to a internal command savefen saves thecurrent position as FEN to a file
startstore=langfieldrang startstore=b7
stopstore=langfieldrang stopstore=f2
storearea=langarearang storearea=c2-d4
With this keys you can restrict the area that is stored or saved But attention the packageskak absolutly doesnrsquot like ldquoillegalrdquo FENs that doesnrsquot describe a full 8times8 board
May 1 2014 17 chessboard 17
mover=langw|brang mover=w
castling=langcastling possibiliesrang castling=Kq
enpassant=langfield|-rang enpassant=c4
halfmove=langnumberrang halfmove=14
fullmove=langnumberrang fullmove=20
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
In chess the rows of the board are called ranks and are numbered from 1 to 8 The columnsare called files and are ldquonumberedrdquo from a to h2
The package chessboard use this naming conventions for all inputs Every time langfieldrang is usedin this documentation you should give a char from andashz followed by a number
28 Naming areas of the board
Rectangular areas are normally described by giving the coordinates of the left bottom cornerand the right upper corner But when using the Forsyth Edwards Notation (FEN) chessboardsare filled starting from the left upper corner a8 and then going on to the right and down tothe right bottom corner ndash like the normal typesetting direction So it is quite natural to usefor FEN related areas this corners As it would be awkward to have two different ways todescribe areas I decided to use the fen convention everywhere Each area has a startfieldthe left upper corner and a stopfield the right bottom corner If some area related keys donrsquotseem to work check that you have used the correct corners
An area can also be given as two fields separated by an hyphen When using this input youdonrsquot have to worry about the corners the package will sort themlangarearang=langa cornerrang-langthe opposite cornerrangchessboard sets at the start this two command to the current values of the printareaprintarea
board and the total board as given by the keys zero maxfield and printarea You can use thiscommands in later keys
2I have some difficulties to remember the english names so I use the following mnemonics FiLe = coLumn =Linie = alFabet Rank = Row = Reihe = numbeRed
May 1 2014 10 chessboard 17
29 FEN Forsyth-Edwards Notation
FEN describes a chess position It consist of 6 fields separated by spaces The first fieldrepresents the placement of the pieces on the board The second field represents the activecolor A lower case ldquowrdquo is used if White is to move a lower case ldquobrdquo is used if Black is theactive player The third field represents castling availability The fourth field is the en passanttarget square The fifth field is a nonnegative integer representing the halfmove clock Thesixth and last field is a positive integer that gives the fullmove number
In the first field the board contents are specified starting with the eighth rank and endingwith the first rank (ldquoin typesetting directionrdquo when the board has the standard orientation)For each rank the squares are specified from file a to file h White pieces are identified byuppercase piece letters (ldquoPNBRQKrdquo) and black pieces are identified by lowercase piece letters(ldquopnbrqkrdquo) Empty squares are represented by the digits one through eight the digit usedrepresents the count of contiguous empty squares along a rank A solidus character ldquordquo isused to separate data of adjacent ranks
chessboard handles FEN-input but also only ldquoFEN-likerdquo-input If given a complete FENchessboard will store all fields in commands and evaluate the first field to fill the boardBut if they are less than six fields chessboard will not complain but simply fill up themissing fields with some default values
In the first field there donrsquot need to be exact 8 pieces in each rank and exactly 8 rank descrip-tions When there are more pieces than needed chessboard will ignore them When thereare less pieces than needed then chessboard will leave the remaining fields in this rankuntouched
The FEN can also be stored in a command So all chessboard will accept all the followinginputs as langFENrangrnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR w KQkq - 0 1rnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR8qK10 w - - 0 10myfen
210 The main parts of the board
Each chessboard is build by printing three ldquolayersrdquo on top of each other
1 The background layer
This is a pgf-picture that lies under the board It can be used for background colors or fancyborders or other background decoration
May 1 2014 11 chessboard 17
2 The main board layer
This is the main part of the board It lies above the background picture It uses only ldquonormalrdquoLATEX objects like rules and chars Labels movers and figures are all build together in thislayer
3 The mark layer
This layer is again a pgf picture now over the board It can be used to draw crosses arrowsetc on the board
The sections 3 to 5 describe how to manipulate the main layer The section 6 describes howto handle the pgf pictures
3 Setting the contents of the board
31 The maximum number of fields
maxfield=langfieldrang maxfield=j10 h8
Chessboards have 8times8 fields So this is the default If you want another size you shoulddeclare a new right upper corner with maxfield=langFieldrang eg maxfield=j10 for a 10times10board Donrsquot use this key if you want only to print a partial board there is another key toachieve this Use it to change the maximum size of a board All fields and areas you use inother arguments should lie inside this maximum size
I was told that some games numbers the fields starting with 0 So I added this option Whenset to true the rank numbers start with 0 and a file named Z is added left to the file a
clearareas=langlist of areasrang clearareas=a1-c3g7-h8
clearfile=langfilerang clearfile=g
clearfiles=langlist of filesrang clearfiles=gh
clearrank=langrankrang clearrank=5
clearranks=langlist of ranksrang clearranks=87
clearfield=langfieldrang clearfield=c6
clearfields=langlist of fieldsrang clearfields=b5c6
You canrsquot prevent that chessboard fills up the board with the running game so if you needan empty board you should clear it ndash either with the keys mentioned here or by using oneof the keys described later that clears the board before adding new pieces
setwhite=langList of piece positionsrang setwhite=Ke4 Qe1 kd6
addwhite=langList of piece positionsrang addwhite=Ke4 Qe1 kd6
setblack=langList of piece positionsrang setblack=Ke4 Qe1 kd6
addblack=langList of piece positionsrang addblack=Ke4 Qe1 kd6
It is a bit cumbersome to have to be careful to use uppercase chars for the white andlowercase chars for the black piece With the keys setwhite addwhite setblack andaddblack you can add white and black pieces without caring about the cases Like the keysfor adding pieces the keys starting with set first clears the board so if you donrsquot want toloose all the set pieces you should use such a key only once
With this keys you can add pieces to the board by given a FEN The setfen will clear theboard addfen will left pieces outside the fields described by the FEN undisturbed
The package skak has the command storegamelangnamerang that stores the FEN of the currentgame in an internal command and the command savegamelangnamerang that stores the FENin a file langnamerangfenThe package chessboard defines similar keys The key storefen=langnamerang stores the FEN inan internal command with the same name as used by storegamelangnamerang That meansthat you can exchange the games stored by the package skak and the package chessboardbut it also means that the package chessboard can overwrite games stored with the packageskak So be careful
storefen=langnamerang storefen=game1
savefen=langname of filerang savefen=game
storefen saves the current position as FEN to a internal command savefen saves thecurrent position as FEN to a file
startstore=langfieldrang startstore=b7
stopstore=langfieldrang stopstore=f2
storearea=langarearang storearea=c2-d4
With this keys you can restrict the area that is stored or saved But attention the packageskak absolutly doesnrsquot like ldquoillegalrdquo FENs that doesnrsquot describe a full 8times8 board
May 1 2014 17 chessboard 17
mover=langw|brang mover=w
castling=langcastling possibiliesrang castling=Kq
enpassant=langfield|-rang enpassant=c4
halfmove=langnumberrang halfmove=14
fullmove=langnumberrang fullmove=20
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
FEN describes a chess position It consist of 6 fields separated by spaces The first fieldrepresents the placement of the pieces on the board The second field represents the activecolor A lower case ldquowrdquo is used if White is to move a lower case ldquobrdquo is used if Black is theactive player The third field represents castling availability The fourth field is the en passanttarget square The fifth field is a nonnegative integer representing the halfmove clock Thesixth and last field is a positive integer that gives the fullmove number
In the first field the board contents are specified starting with the eighth rank and endingwith the first rank (ldquoin typesetting directionrdquo when the board has the standard orientation)For each rank the squares are specified from file a to file h White pieces are identified byuppercase piece letters (ldquoPNBRQKrdquo) and black pieces are identified by lowercase piece letters(ldquopnbrqkrdquo) Empty squares are represented by the digits one through eight the digit usedrepresents the count of contiguous empty squares along a rank A solidus character ldquordquo isused to separate data of adjacent ranks
chessboard handles FEN-input but also only ldquoFEN-likerdquo-input If given a complete FENchessboard will store all fields in commands and evaluate the first field to fill the boardBut if they are less than six fields chessboard will not complain but simply fill up themissing fields with some default values
In the first field there donrsquot need to be exact 8 pieces in each rank and exactly 8 rank descrip-tions When there are more pieces than needed chessboard will ignore them When thereare less pieces than needed then chessboard will leave the remaining fields in this rankuntouched
The FEN can also be stored in a command So all chessboard will accept all the followinginputs as langFENrangrnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR w KQkq - 0 1rnbqkbnrpppppppp8888PPPPPPPPRNBQKBNR8qK10 w - - 0 10myfen
210 The main parts of the board
Each chessboard is build by printing three ldquolayersrdquo on top of each other
1 The background layer
This is a pgf-picture that lies under the board It can be used for background colors or fancyborders or other background decoration
May 1 2014 11 chessboard 17
2 The main board layer
This is the main part of the board It lies above the background picture It uses only ldquonormalrdquoLATEX objects like rules and chars Labels movers and figures are all build together in thislayer
3 The mark layer
This layer is again a pgf picture now over the board It can be used to draw crosses arrowsetc on the board
The sections 3 to 5 describe how to manipulate the main layer The section 6 describes howto handle the pgf pictures
3 Setting the contents of the board
31 The maximum number of fields
maxfield=langfieldrang maxfield=j10 h8
Chessboards have 8times8 fields So this is the default If you want another size you shoulddeclare a new right upper corner with maxfield=langFieldrang eg maxfield=j10 for a 10times10board Donrsquot use this key if you want only to print a partial board there is another key toachieve this Use it to change the maximum size of a board All fields and areas you use inother arguments should lie inside this maximum size
I was told that some games numbers the fields starting with 0 So I added this option Whenset to true the rank numbers start with 0 and a file named Z is added left to the file a
clearareas=langlist of areasrang clearareas=a1-c3g7-h8
clearfile=langfilerang clearfile=g
clearfiles=langlist of filesrang clearfiles=gh
clearrank=langrankrang clearrank=5
clearranks=langlist of ranksrang clearranks=87
clearfield=langfieldrang clearfield=c6
clearfields=langlist of fieldsrang clearfields=b5c6
You canrsquot prevent that chessboard fills up the board with the running game so if you needan empty board you should clear it ndash either with the keys mentioned here or by using oneof the keys described later that clears the board before adding new pieces
setwhite=langList of piece positionsrang setwhite=Ke4 Qe1 kd6
addwhite=langList of piece positionsrang addwhite=Ke4 Qe1 kd6
setblack=langList of piece positionsrang setblack=Ke4 Qe1 kd6
addblack=langList of piece positionsrang addblack=Ke4 Qe1 kd6
It is a bit cumbersome to have to be careful to use uppercase chars for the white andlowercase chars for the black piece With the keys setwhite addwhite setblack andaddblack you can add white and black pieces without caring about the cases Like the keysfor adding pieces the keys starting with set first clears the board so if you donrsquot want toloose all the set pieces you should use such a key only once
With this keys you can add pieces to the board by given a FEN The setfen will clear theboard addfen will left pieces outside the fields described by the FEN undisturbed
The package skak has the command storegamelangnamerang that stores the FEN of the currentgame in an internal command and the command savegamelangnamerang that stores the FENin a file langnamerangfenThe package chessboard defines similar keys The key storefen=langnamerang stores the FEN inan internal command with the same name as used by storegamelangnamerang That meansthat you can exchange the games stored by the package skak and the package chessboardbut it also means that the package chessboard can overwrite games stored with the packageskak So be careful
storefen=langnamerang storefen=game1
savefen=langname of filerang savefen=game
storefen saves the current position as FEN to a internal command savefen saves thecurrent position as FEN to a file
startstore=langfieldrang startstore=b7
stopstore=langfieldrang stopstore=f2
storearea=langarearang storearea=c2-d4
With this keys you can restrict the area that is stored or saved But attention the packageskak absolutly doesnrsquot like ldquoillegalrdquo FENs that doesnrsquot describe a full 8times8 board
May 1 2014 17 chessboard 17
mover=langw|brang mover=w
castling=langcastling possibiliesrang castling=Kq
enpassant=langfield|-rang enpassant=c4
halfmove=langnumberrang halfmove=14
fullmove=langnumberrang fullmove=20
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
This is the main part of the board It lies above the background picture It uses only ldquonormalrdquoLATEX objects like rules and chars Labels movers and figures are all build together in thislayer
3 The mark layer
This layer is again a pgf picture now over the board It can be used to draw crosses arrowsetc on the board
The sections 3 to 5 describe how to manipulate the main layer The section 6 describes howto handle the pgf pictures
3 Setting the contents of the board
31 The maximum number of fields
maxfield=langfieldrang maxfield=j10 h8
Chessboards have 8times8 fields So this is the default If you want another size you shoulddeclare a new right upper corner with maxfield=langFieldrang eg maxfield=j10 for a 10times10board Donrsquot use this key if you want only to print a partial board there is another key toachieve this Use it to change the maximum size of a board All fields and areas you use inother arguments should lie inside this maximum size
I was told that some games numbers the fields starting with 0 So I added this option Whenset to true the rank numbers start with 0 and a file named Z is added left to the file a
clearareas=langlist of areasrang clearareas=a1-c3g7-h8
clearfile=langfilerang clearfile=g
clearfiles=langlist of filesrang clearfiles=gh
clearrank=langrankrang clearrank=5
clearranks=langlist of ranksrang clearranks=87
clearfield=langfieldrang clearfield=c6
clearfields=langlist of fieldsrang clearfields=b5c6
You canrsquot prevent that chessboard fills up the board with the running game so if you needan empty board you should clear it ndash either with the keys mentioned here or by using oneof the keys described later that clears the board before adding new pieces
setwhite=langList of piece positionsrang setwhite=Ke4 Qe1 kd6
addwhite=langList of piece positionsrang addwhite=Ke4 Qe1 kd6
setblack=langList of piece positionsrang setblack=Ke4 Qe1 kd6
addblack=langList of piece positionsrang addblack=Ke4 Qe1 kd6
It is a bit cumbersome to have to be careful to use uppercase chars for the white andlowercase chars for the black piece With the keys setwhite addwhite setblack andaddblack you can add white and black pieces without caring about the cases Like the keysfor adding pieces the keys starting with set first clears the board so if you donrsquot want toloose all the set pieces you should use such a key only once
With this keys you can add pieces to the board by given a FEN The setfen will clear theboard addfen will left pieces outside the fields described by the FEN undisturbed
The package skak has the command storegamelangnamerang that stores the FEN of the currentgame in an internal command and the command savegamelangnamerang that stores the FENin a file langnamerangfenThe package chessboard defines similar keys The key storefen=langnamerang stores the FEN inan internal command with the same name as used by storegamelangnamerang That meansthat you can exchange the games stored by the package skak and the package chessboardbut it also means that the package chessboard can overwrite games stored with the packageskak So be careful
storefen=langnamerang storefen=game1
savefen=langname of filerang savefen=game
storefen saves the current position as FEN to a internal command savefen saves thecurrent position as FEN to a file
startstore=langfieldrang startstore=b7
stopstore=langfieldrang stopstore=f2
storearea=langarearang storearea=c2-d4
With this keys you can restrict the area that is stored or saved But attention the packageskak absolutly doesnrsquot like ldquoillegalrdquo FENs that doesnrsquot describe a full 8times8 board
May 1 2014 17 chessboard 17
mover=langw|brang mover=w
castling=langcastling possibiliesrang castling=Kq
enpassant=langfield|-rang enpassant=c4
halfmove=langnumberrang halfmove=14
fullmove=langnumberrang fullmove=20
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
I was told that some games numbers the fields starting with 0 So I added this option Whenset to true the rank numbers start with 0 and a file named Z is added left to the file a
clearareas=langlist of areasrang clearareas=a1-c3g7-h8
clearfile=langfilerang clearfile=g
clearfiles=langlist of filesrang clearfiles=gh
clearrank=langrankrang clearrank=5
clearranks=langlist of ranksrang clearranks=87
clearfield=langfieldrang clearfield=c6
clearfields=langlist of fieldsrang clearfields=b5c6
You canrsquot prevent that chessboard fills up the board with the running game so if you needan empty board you should clear it ndash either with the keys mentioned here or by using oneof the keys described later that clears the board before adding new pieces
setwhite=langList of piece positionsrang setwhite=Ke4 Qe1 kd6
addwhite=langList of piece positionsrang addwhite=Ke4 Qe1 kd6
setblack=langList of piece positionsrang setblack=Ke4 Qe1 kd6
addblack=langList of piece positionsrang addblack=Ke4 Qe1 kd6
It is a bit cumbersome to have to be careful to use uppercase chars for the white andlowercase chars for the black piece With the keys setwhite addwhite setblack andaddblack you can add white and black pieces without caring about the cases Like the keysfor adding pieces the keys starting with set first clears the board so if you donrsquot want toloose all the set pieces you should use such a key only once
With this keys you can add pieces to the board by given a FEN The setfen will clear theboard addfen will left pieces outside the fields described by the FEN undisturbed
The package skak has the command storegamelangnamerang that stores the FEN of the currentgame in an internal command and the command savegamelangnamerang that stores the FENin a file langnamerangfenThe package chessboard defines similar keys The key storefen=langnamerang stores the FEN inan internal command with the same name as used by storegamelangnamerang That meansthat you can exchange the games stored by the package skak and the package chessboardbut it also means that the package chessboard can overwrite games stored with the packageskak So be careful
storefen=langnamerang storefen=game1
savefen=langname of filerang savefen=game
storefen saves the current position as FEN to a internal command savefen saves thecurrent position as FEN to a file
startstore=langfieldrang startstore=b7
stopstore=langfieldrang stopstore=f2
storearea=langarearang storearea=c2-d4
With this keys you can restrict the area that is stored or saved But attention the packageskak absolutly doesnrsquot like ldquoillegalrdquo FENs that doesnrsquot describe a full 8times8 board
May 1 2014 17 chessboard 17
mover=langw|brang mover=w
castling=langcastling possibiliesrang castling=Kq
enpassant=langfield|-rang enpassant=c4
halfmove=langnumberrang halfmove=14
fullmove=langnumberrang fullmove=20
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
clearareas=langlist of areasrang clearareas=a1-c3g7-h8
clearfile=langfilerang clearfile=g
clearfiles=langlist of filesrang clearfiles=gh
clearrank=langrankrang clearrank=5
clearranks=langlist of ranksrang clearranks=87
clearfield=langfieldrang clearfield=c6
clearfields=langlist of fieldsrang clearfields=b5c6
You canrsquot prevent that chessboard fills up the board with the running game so if you needan empty board you should clear it ndash either with the keys mentioned here or by using oneof the keys described later that clears the board before adding new pieces
setwhite=langList of piece positionsrang setwhite=Ke4 Qe1 kd6
addwhite=langList of piece positionsrang addwhite=Ke4 Qe1 kd6
setblack=langList of piece positionsrang setblack=Ke4 Qe1 kd6
addblack=langList of piece positionsrang addblack=Ke4 Qe1 kd6
It is a bit cumbersome to have to be careful to use uppercase chars for the white andlowercase chars for the black piece With the keys setwhite addwhite setblack andaddblack you can add white and black pieces without caring about the cases Like the keysfor adding pieces the keys starting with set first clears the board so if you donrsquot want toloose all the set pieces you should use such a key only once
With this keys you can add pieces to the board by given a FEN The setfen will clear theboard addfen will left pieces outside the fields described by the FEN undisturbed
The package skak has the command storegamelangnamerang that stores the FEN of the currentgame in an internal command and the command savegamelangnamerang that stores the FENin a file langnamerangfenThe package chessboard defines similar keys The key storefen=langnamerang stores the FEN inan internal command with the same name as used by storegamelangnamerang That meansthat you can exchange the games stored by the package skak and the package chessboardbut it also means that the package chessboard can overwrite games stored with the packageskak So be careful
storefen=langnamerang storefen=game1
savefen=langname of filerang savefen=game
storefen saves the current position as FEN to a internal command savefen saves thecurrent position as FEN to a file
startstore=langfieldrang startstore=b7
stopstore=langfieldrang stopstore=f2
storearea=langarearang storearea=c2-d4
With this keys you can restrict the area that is stored or saved But attention the packageskak absolutly doesnrsquot like ldquoillegalrdquo FENs that doesnrsquot describe a full 8times8 board
May 1 2014 17 chessboard 17
mover=langw|brang mover=w
castling=langcastling possibiliesrang castling=Kq
enpassant=langfield|-rang enpassant=c4
halfmove=langnumberrang halfmove=14
fullmove=langnumberrang fullmove=20
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
setwhite=langList of piece positionsrang setwhite=Ke4 Qe1 kd6
addwhite=langList of piece positionsrang addwhite=Ke4 Qe1 kd6
setblack=langList of piece positionsrang setblack=Ke4 Qe1 kd6
addblack=langList of piece positionsrang addblack=Ke4 Qe1 kd6
It is a bit cumbersome to have to be careful to use uppercase chars for the white andlowercase chars for the black piece With the keys setwhite addwhite setblack andaddblack you can add white and black pieces without caring about the cases Like the keysfor adding pieces the keys starting with set first clears the board so if you donrsquot want toloose all the set pieces you should use such a key only once
With this keys you can add pieces to the board by given a FEN The setfen will clear theboard addfen will left pieces outside the fields described by the FEN undisturbed
The package skak has the command storegamelangnamerang that stores the FEN of the currentgame in an internal command and the command savegamelangnamerang that stores the FENin a file langnamerangfenThe package chessboard defines similar keys The key storefen=langnamerang stores the FEN inan internal command with the same name as used by storegamelangnamerang That meansthat you can exchange the games stored by the package skak and the package chessboardbut it also means that the package chessboard can overwrite games stored with the packageskak So be careful
storefen=langnamerang storefen=game1
savefen=langname of filerang savefen=game
storefen saves the current position as FEN to a internal command savefen saves thecurrent position as FEN to a file
startstore=langfieldrang startstore=b7
stopstore=langfieldrang stopstore=f2
storearea=langarearang storearea=c2-d4
With this keys you can restrict the area that is stored or saved But attention the packageskak absolutly doesnrsquot like ldquoillegalrdquo FENs that doesnrsquot describe a full 8times8 board
May 1 2014 17 chessboard 17
mover=langw|brang mover=w
castling=langcastling possibiliesrang castling=Kq
enpassant=langfield|-rang enpassant=c4
halfmove=langnumberrang halfmove=14
fullmove=langnumberrang fullmove=20
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
The package skak has the command storegamelangnamerang that stores the FEN of the currentgame in an internal command and the command savegamelangnamerang that stores the FENin a file langnamerangfenThe package chessboard defines similar keys The key storefen=langnamerang stores the FEN inan internal command with the same name as used by storegamelangnamerang That meansthat you can exchange the games stored by the package skak and the package chessboardbut it also means that the package chessboard can overwrite games stored with the packageskak So be careful
storefen=langnamerang storefen=game1
savefen=langname of filerang savefen=game
storefen saves the current position as FEN to a internal command savefen saves thecurrent position as FEN to a file
startstore=langfieldrang startstore=b7
stopstore=langfieldrang stopstore=f2
storearea=langarearang storearea=c2-d4
With this keys you can restrict the area that is stored or saved But attention the packageskak absolutly doesnrsquot like ldquoillegalrdquo FENs that doesnrsquot describe a full 8times8 board
May 1 2014 17 chessboard 17
mover=langw|brang mover=w
castling=langcastling possibiliesrang castling=Kq
enpassant=langfield|-rang enpassant=c4
halfmove=langnumberrang halfmove=14
fullmove=langnumberrang fullmove=20
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
The package skak has the command storegamelangnamerang that stores the FEN of the currentgame in an internal command and the command savegamelangnamerang that stores the FENin a file langnamerangfenThe package chessboard defines similar keys The key storefen=langnamerang stores the FEN inan internal command with the same name as used by storegamelangnamerang That meansthat you can exchange the games stored by the package skak and the package chessboardbut it also means that the package chessboard can overwrite games stored with the packageskak So be careful
storefen=langnamerang storefen=game1
savefen=langname of filerang savefen=game
storefen saves the current position as FEN to a internal command savefen saves thecurrent position as FEN to a file
startstore=langfieldrang startstore=b7
stopstore=langfieldrang stopstore=f2
storearea=langarearang storearea=c2-d4
With this keys you can restrict the area that is stored or saved But attention the packageskak absolutly doesnrsquot like ldquoillegalrdquo FENs that doesnrsquot describe a full 8times8 board
May 1 2014 17 chessboard 17
mover=langw|brang mover=w
castling=langcastling possibiliesrang castling=Kq
enpassant=langfield|-rang enpassant=c4
halfmove=langnumberrang halfmove=14
fullmove=langnumberrang fullmove=20
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
With this keys you can set the rest of the FEN-fields Apart from mover the values are onlyused if you save FENs The values are also set if you use in the argument of a setfen oraddfen key complete FENs instead of only the position part
37 Getting the positions of pieces
getpiecelists=langrang getpiecelists
New in version 15 there is a key that retrieves the position of the pieces on the board Foreach piece type there is a list called cblistlangpiecerang The lists can be used everywhere wherea list of fields is expected Eg it is possible to use the lists to highlight all pawns (see section613)
Unlike almost all other commands of chessboard this commands are saved globally Thismakes it possible to use the lists after the board
newchessgamechessboard[getpiecelists]
White pieces kingcblistK queencblistQrookcblistR bishopcblistBknightcblistN pawncblistP
Black pieces kingcblistk queencblistqrookcblistr bishopcblistbknightcblistn pawncblistp
White pieces Ke1 Qd1 Ra1h1 Bc1f1 Nb1g1pa2b2c2d2e2f2g2h2
Black pieces Ke8 Qd8 Ra8h8 Bc8f8 Nb8g8pa7b7c7d7e7f7g7h7
May 1 2014 18 chessboard 17
38 Using saved and stored games
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
When you are using the package skak you can use the saved games to set the start positionof a game with the the package skak-commands restoregamelangnamerang (restores the gamestored with storegame) and loadgamelangnamerang (loads the game saved with savegame)This only works if you have saved the position of a normal 8times8-board
restorefen=langnamerang restorefen=game1
loadfen=langnamerang loadfen=game
You can also use the saved games to set positions on chessboard restorefen willuse games saved with storegame and storefen loadfen will load games saved withsavegame and savefen
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
With this key you can change the language used for input of pieces The key doesnrsquot affect thecbDefineLanguage
cbDefineTranslation input language of the package skak It also doesnrsquot affect the language of saved and restoredgames chessboard will always switch to english in this cases Up to now only germantranslations are built in (I donrsquot know how chess pieces are called in other languages) but itisnrsquot difficult to add other languages The code for german should be quite selfexplanatory
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
For many of the following commands you will have to enter a length This can be anabsolute length like 1in 2cm 4pt But often you will prefer a relative length In mostcases the font related length 1ex 1em and baselineskip will be the same as a half ofthe square width the width of the square and the total height of a square3 The packageuses internally the three lengths offered by the package chessfss ndash lencfsssquarewidthlencfsssquaretotalheight and lencfsssquaredepth ndash In most cases they willonly give inside chessboard (locally) the correct sizes but if you use the key psset theyare set globally
42 Some words about box sizes
In TEX almost everything is either a box (a character box a line box a page box a box with atabular in it ) or a space And larger objects are build by putting boxes and spaces in asurrounding box In the real world a box has always to be larger as its content In the virtualTEX-world a lot of magic is possible The content can be much larger than the surroundingbox or even be partly or completely outside the surrounding box
x shows the current linefbox a boxraisebox3ex[0pt][0pt]
makebox[0pt]large content outside the box
x and here something after the fbox
x
large content outside the box
x
3I learned on the hard way that you shouldnrsquot rely that fonts sets em and ex correctly eg the font skak doesnrsquotdo it and so the units default to zero which can be quite confusing So I decided to set the fontdimen valuesexplicitly
May 1 2014 21 chessboard 17
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
So the outside size of a box can be quite different from the inside size And the outsidebaseline of a box can be at quite different place as the inside baseline
In the concrete case of chessboard the outside size of the board is determined throughthe size of the font the fields shown and the margin All other things like border labelhighlighting mover will not affect this size The baseline of a chess board is always at thebottom of the bottom rank Margins labels or borders or anything else will not change thisIf you want to move the baseline you will have to use a raisebox
43 Margins
The ldquooutside sizerdquo (ldquothe bounding boxrdquo) of a chess board is the size of the printed fields plusa margin
With this keys you can set and change the thickness of the margin As you can see you canset each margin differently but there are also keys to set more than one margin at one time
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
The borders are made with rules You will perhaps notice that on screen the edges looks likeas if they donrsquot contact properly This is a problem of the rather bad resolution of a screenWhen you zoom in you can see that the edges are fine If this bothers you you can try thefancy borders made with the pgf-commands decribed later As they are made with one linethey seem to have better edges ndash but you canrsquot color them individually and it isnrsquot yet possibleto disable the borders of single sides
With this keys you can set and change the thickness of the border The border doesnrsquot changethe bounding box of the board If there isnrsquot an adequate margin it will stick outside
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
With this keys you can change the size of the board font The keys tinyboard etc gives thesame sizes as the similar commands tinyboard of the package skak they also change thesize of the font of the labels
You can also change the size of the board font with the commands described in thedocumentation of the package chessfss But you should be aware that the keys used insetchessboard or chessboard will always win over the commands from the packagechessfss
46 Changing the boardfont
Instead of using the keys described below you can also change the board font with thecommands described in the documentation of the package chessfss But you should beaware that the keys used in setchessboard or chessboard will always win over thecommands from the package chessfss
With the above key you can change the board font by setting the family This works quitesimilar as for text font where you can switch eg from times to helvetica by changing thefont family The font families skak and skaknew will work from the start You must installother families before being able to use them
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
Setting the series to bold (b) only works for a quite small set of fonts which have the chars intwo weights But to tell the truth I donrsquot find the result very satisfying
There are no keys to change the shape of the font as I really donrsquot know what an italic(itshape) or slanted board font should be (And I never saw such a font)
With this key you can change the encoding of the board font While in a normal documentyou probably seldom or never need to bother with encodings they are highly useful inconnection chess board if you want to add colors to the chars on the board When usingother encodings that the standard LSB the chars on the board are composed with specialchars that allows to color eg the lines of the black field differently to the figure on the fieldI will come back to this when I describe how to color the chars
There are simple encodings called LSB LSB1 LSB2 which works with almost everyfont family And there are special encodings LSBC1 LSBC2 which works only withprofessional chess fonts with special chars Happily the default board font the free fontskaknew is such a professional chess font
If you want to use one of the extended encodings LSB1 LSB2 etc and LSBC1 LSBC2 etc youmust load the definition files eg with usepackage[LSB1T1]fontenc You find moreinformations in the documentation of the package chessfss
May 1 2014 26 chessboard 17
47 Coloring and emphasizing the board chars
471 In short
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
bull Coloring the board or parts of the chars is a two step process
First you set the colors you want then you apply them
bull Colors can be applied to the whole board (to set the default colors of the white andblack pieces and fields) This done with the keys setfontcolors and addfontcolors
bull Colors can be applied to part of the board together with other commands likebfseries (eg to emphasize special fields or ranks) by first enabling color emphasingwith the key coloremph and then by setting the area or field that should get the colorswith eg the key empharea
472 Introduction About composed chars and encodings
In simple chess fonts each field with and without a figure on it is one char You can colorsuch a char but ndash as in the case of normal chars ndash only in one color
A jThis is certainly not very satisfying You probably would like to be able to color the whitefigures diffently from the black ones and the black fields in a third color
To be able to do this one has to use more than one char to build a field and to print them ontop of each other Look eg at this example
ZTKIt is build by putting four different objects on top of each other
At start there is a standard yellow colorbox
Above there is a black empty square colored in blue
ZThen comes a solid filled and colored char with the same shape as the king
T
May 1 2014 27 chessboard 17
Table 1 The contruction rules of encoding LSBC3
Encoding LSBC3
Layer fieldmask field piecemask piece result
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
WhiteSquare z zBlackSquare z Z zZWhiteOnWhite 1 T K 1TKWhiteOnBlack 1 bull T K 1bullTKBlackOnWhite 1 T k 1TkBlackOnBlack 1 bull T k 1bullTk
At last there is the char for the king
KSo
+Z+ T +K= ZTKThere are a lot of other possibilities to compose the board fields Some more ldquopoor manrsquosrdquocompositions that use only chars present in every chess font other that need special maskingchars which only special chess fonts provide
Each such construction is connected to a font encoding By changing the encoding of theboard font you change the rules that compose the board chars and so you change also theoptions to color the chars
In the package chessfss I have defined a bundle of such ldquoconstruction rulesrdquo (=encodings) touse and color composed board chars As it would be a strain if each of this construction ruleswould let to a different set of commands to color the chars I had to systemize the constructionrules For this I have divided the possible individual components of a composed chars infour logical layers and assign to each layer generic color commands that are used in thedefinition of the composed chars and can be used to color the components The four layersare named fieldmask field piecemask and piece
As an example table 1 shows a tabular that demonstrates how the encoding LSBC3 is builtAs you can see the chars are built by putting up three or four chars on top of each other (Thegreen and yellow colors are not the default settings) The documentation of the packagechessfss shows the other encodings
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
Table 2 shows the internal commands used to color the different part of a composed charYou will probably never need them but they will give you an idea what can be colored (Ihope that is clear that it makes only sense to change the colors of layers that are used in theactual encoding ndash you canrsquot color an solid fieldmask that isnrsquot there)
I would like to draw your attention to two things
1 The field-layers distinguish between black and white field while the piece layer distin-guish between black and white pieces and the piecemask offers all possible combina-tions
2 The fieldmask and the piecemask are colored by default and so they will overwrite orblock out external colors from colorbox or textcolor commands
Uses commands from chessfssstysetboardfontencodingLSBC3setboardfontsize2cm
1TK 1TKSo coloring the board is not really difficult one must only redefine the internal commandsmentioned above to the wanted color Thatrsquos what the setboardfontcolors command ofthe package chessfss does and it will work fine with chessboard
Naturally I also wanted to add keys for chessboard and setchessboard to change thecolors This is a bit more complicated because I wanted not only to be able to change the
May 1 2014 29 chessboard 17
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
colors of the whole board but also of single fields or areas And I had also to add keys tochange the color in the two pgf pictures Finding names for all this keys and effects wasnrsquoteasy And I hope that it isnrsquot to confusing
473 Setting the default colors of the board
clearfontcolors=langarbitraryrang clearfontcolors
When you set with the following keys a color for one of the font layers chessboard addssimply the color definition to an internal command (the ldquofont color stackrdquo) When you uselater a key to apply the colors to the board or an area this internal command is inserted atthe start of the board or the fields of the area The internal command can get quite long ifyou set a lot of colors With the key clearfontcolors you can empty the internal command(this will not destroy the colors that you have already applied)
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
With this keys you set the colors of the different parts of a composed char The colors aresaved to an internal stack A key like whitepiececolor saves the color for one of the layercolor commands piecemaskcolor will set the color for all four piecemasks in one go
The keys colorwhite and colorblack of the previous version of this package are copies ofthe keys whitepiececolor and blackpiececolor
474 Applying the colors to the whole board
setfontcolors=langarbitraryrang setfontcolors
addfontcolors=langarbitraryrang addfontcolors
This keys will put the ldquofont color stackrdquo in a command that is executed at the start of theboard So the colors will affect any fields that donrsquot get individual colors with the commanddescribed in the next subsection setfontcolors will replace any font colors that have beenset before addfontcolors will add the new colors to perhaps already existing ones
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
With this key you can set a command that should be applied to an area The commands canbe whatever you want (it is a good idea not use something that takes up some space) In myopinion the only senseful commands are color and ndash for the few fonts that have a boldboardfont ndash bfseries You can use the key eg for simple coloring
You canrsquot color with emphstyle the fieldmask and the piecemask of chars as they have adefault color that takes precedence
coloremph=langtrue|falserang coloremph
With this key you enable or disable color emphasising When set to true font colors setearlier will be added to emphstyle and so used to color the area The colors are added afterthe commands of the key emphstyle and so will eventually overwrite them This allowsmore complicated coloring
whiteonwhitepiecemaskcolor=greenwhitepiececolor=redblackpiececolor=blueemphstyle=coloryellowdoesnrsquot affect the default white colorof the piecemaskempharea=a1-c8coloremphempharea=empharea]
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
The key colorpieces doesnrsquot work anymore it will issue only a warning Use emphfieldsinstead
May 1 2014 33 chessboard 17
476 Transparencyopacity
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
Pgf has commands to set the opacity of a color This works only for some drivers and outputformats (eg with pdfLATEX) but it also works outside pgf pictures in running text The maindrawbacks are that the opacity settings gets lost at a pagebreak and that TEX-groups andboxes are not respected that means that you must reset the opacity explicitly It is possibleto add to boxes that use internally colorbegingroupcolorendgroup5 some codethat resets the opacity outside the box to 1 As chessboard uses only such safe boxes it ispossible to smuggle transparency in parts of the composed chars But the whole is not verysafe so use it at your own risk
In the package chessfss I used the name sidefont for the label I did it mostly because I didnrsquotdare to use the command labelfont I was quite sure that somewhere in the packagesfor LATEX someone else had already used this name When using keys name clash are not a
5Almost all LATEX-boxes but not eg mbox and makebox when used without optional argument
May 1 2014 34 chessboard 17
problem as internally a unique prefix is used so I decided to use names starting with ldquolabelrdquoin this package
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
The labels on the left side are set raggedleft the ones on the right side raggedright at thedistance given by the keys This width donrsquot change the size of the board The top andbottom labels are centered
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
With this keys you can set the distance of the baselines of the top and bottom labels fromthe board sides baselineskip ex and em refer in this keys not to the size of the boardbut to the size of the label font ndash I thought this would be easier to handle
With this keys you can set the font used by the labels As a default (this is set in the packagechessfss) the sans serif font of the document is used You can also use the the packagechessfss commands to change the font
This key sets the font size of the label The default value is set by the key normalboard Therearenrsquot keys to set the size of each label separatly If you really need different sizes use the keyhlabelfont etc (and be careful when using font relative sizes)
setchessboardlabelfont=bfseriessetsidefontfamilyptm from chessfssstychessboard[labelfontsize=6pt]
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
labelbottomformat=langcommandsrang labelbottomformat h
hlabelformat=langcommandsrang hlabelformat 1
vlabelformat=langcommandsrang vlabelformat h
labelformat=langcommandsrang labelformat
With this keys you can control how the number of the files and ranks are printed ranklabeland filelabel are counters that contain the current rank and file You can use them freely(even change if you want)
The commands can be a lot of things You can eg use them to color the labels or to movethe labels around When you use commands with optional arguments you must put bracesaround the value of the key
viii rmblkansvii opopopopvi 0Z0Z0Z0Zv Z0Z0Z0Z0iv 0Z0Z0Z0Ziii Z0Z0Z0Z0ii POPOPOPOi SNAQJBMR
1 2 3 4 5 6 7 8
49 The mover
The ldquomoverrdquo is a sign at the side of the board that indicates which player is to movechessboard gets this information either from the FEN (if it contains the informationas is the case when the FEN comes from the package skak) or through the following key
mover=langw|brang mover=b
You can use this key more than once eg to control the mover field in the FEN that you savethe last value is used for the print
showmover=langtrue|falserang showmover=false true
This key switch the print of the mover sign on and off
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
This key sets the fontsize of the mover It only has an effect if the mover sign comes from afont ndash and if the definition doesnrsquot change the fontsize
The value is saved in an inner command with the name boardvalmoversize you canuse this command in your own mover definitions
With this keys you can move the mover vertically Positive values will move the bottommover up and the top mover down6 0pt will align the bottom mover along the baseline andthe top of the upper mover along the upper side of the board
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
hideareas=langlist of areasrang hideareas=a1-c3g7-h8
hidefile=langfilerang hidefile=g
hidefiles=langlist of filesrang hidefiles=gh
hiderank=langrankrang hiderank=5
hideranks=langlist of ranksrang hideranks=87
hidefield=langfieldrang hidefield=c6
hidefields=langlist of fieldsrang hidefields=b5c6
With this keys you can hide pieces on certain fields The pieces are not deleted eg whenyou save the position to FEN they will be there But the content of hidden fields donrsquot appearif you add pieces to this fields
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
showpieces=langlist of piece charsrang showpieces=K b
showwhite=langarbitraryrang showwhite
showblack=langarbitraryrang showblack
showall=langarbitraryrang showall
And this keys lets reappear hidden piecestypes Attention hidden pieces on hidden fieldsreappear only if you use the key to show the field and the key to show the piece
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
You must load a color package like xcolor or color to be able to use colors7
Coloring and decorating the board is a bit complicated as there is so much that can getdifferent colors and so much different possibilities for marks arrows fancy borders and soon So it can take some time to find out how to achieve a certain effect
Donrsquot forget that not every effect is sensible or even works everywhere Transparencyopacityeg donrsquot work for every driver or output format or printer or previewer (the documentationof pgf says that it works for dvips only with new ghostscript versions) Some colors looksgood on screen but bad if printed with a greyscale printer Colors can change if you useanother monitor Some color combinations are a problem for color blinds
The package skak has some own highlighting commands They use postscriptpstrickscommands and they only work if you load the package skak with the option ps That meansthat you have to use the texrarrdvirarrpsrarrpdf-way to process the document If youwant to use pdfLATEX directly you have to use a package like pst-pdf to first make pdf graphicsfrom all boards and then include this graphics during the pdfLATEX-run I find this quitecumbersome and sometimes it is even difficult to get it to work
So I decided to use pgf to implement my own highlighting commands But I also tried tooffer a possibility to use the commands of the package skak
The pgf-commands used by the package chessboard need only pgfcoresty and pgfbaseshapes-packagesty from the pgf-bundle If you need pgf-commands from other parts of the bundleyou will have to load the styles yourself
pgf=langtrue|falserang pgf true
Pgf-commands works fine with LATEX and pdfLATEX but in some case (eg if you usechessboard in an environment that calls the environment preview) they can induceerrors So I added a key to disable all the pgf-commands It is also useful to disable most ofthe highlighting
61 The pgf-pictures
The decorations in the two other layers (background layer and mark layer) use pgf-commands ndash or to be more precise the two other layers are pgf-pictures
In the first version of the package chessboard the background picture wasnrsquot used much Ihad only implemented some code to color the fields But then I got the request to add some
7I must correct myself the pgf-package will load xcolor so you should load a color package only if you want touse it with other options
May 1 2014 45 chessboard 17
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
more commands for fancy borders which did mean that I had to transfer the code whichdraws borders in the foreground picture to the background picture And I got a request forcoloring fields in the foreground picture which did mean that I had to transfer the code fromthe background to the foreground
So I decided to rewrite and extend the codes so that each highlightingdrawing in the pgf-pictures can be done in either the background or the foreground or in both I donrsquot know ifsomeone will ever have a need for a cross under the figures but why shouldnrsquot I offer somecode to do it
I also tried to unify the keys that affect the pgf-pictures to improve the possibilities for theuser to control which pgf-picture is affected and put a bit more order in the keys At the endquite a lot of the code has been rearranged and changed
611 Naming of the pgf related keys
There are more or less three set of keys
bull Keys which affect only the foreground picture The keys starts with or contains thestring ldquomarkrdquo
bull Keys which affect only the background picture The keys starts with or contains thestring ldquobackrdquo
bull Keys that saves or set properties that are used in both picture eg to change the coloror the linewidth Such keys start or contain in most cases the string ldquopgfrdquo (with someexceptions like the key for clipping and trimming) For a lot of such keys there exista shorter (but less descriptive) name without the ldquopgfrdquo In most cases there isnrsquot adifference between the two
612 Executing the drawing commands
A chessboard consists of fields on which figures make moves and so the decoration of theboard is field and move orientated
There are three different types of graphical object
bull You can draw something on a set of single fields eg put a cross on each of the fieldsor put a border around each field To get these pictures on or under the field the innercommands first shift the origin to the middle of field and then inserts the code storedin the style definition in the foreground or background image
bull You can draw something on or around a region ndash a rectangle made of fields ndash egby putting a border around the center or a rank or the whole board Here the innercommands shift the origin to the left upper corner of the region The name of theother corner is available in the style definition through 1
May 1 2014 46 chessboard 17
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
bull And you can mark a move The main difference between a move and a region is thatthe order of the ldquocornersrdquo given in the argument matters For moves the origin is inthe first corner (the from field)
The drawing is done by first setting with various key the style and the properties of the pgfobject and then executed by telling chessboard which fields moves or regions should getthe drawings
613 Drawing on and under fields
markboard=langarbitraryrang markboard
markarea=langarearang markarea=a1-c3
markareas=langlist of areasrang markareas=a1-c3d5-e5
markfiles=langfilerang markfiles=g
markfiles=langlist of filesrang markfiles=gh
markrank=langrankrang markrank=7
markranks=langlist of ranksrang markranks=87
markfield=langfieldrang markfield=c6
markfields=langlist of fieldsrang markfields=b5c6
backboard=langarbitraryrang backboard
backarea=langarearang backarea=a1-c3
backareas=langlist of areasrang backareas=a1-c3d5-e5
backfiles=langfilerang backfiles=g
backfiles=langlist of filesrang backfiles=gh
backrank=langrankrang backrank=7
backranks=langlist of ranksrang backranks=87
backfield=langfieldrang backfield=c6
backfields=langlist of fieldsrang backfields=b5c6
This keys executes the pgf-commands stored in the style command for each single field
May 1 2014 47 chessboard 17
In the following example you should look at the difference it makes if you put a cross or aborder in the background or the foreground
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
With this keys you set the style the drawing commands will use markstyle sets onlythe style for the foreground (the ldquomarkrdquo picture) backstyle sets only the style for thebackground picture pgfstyle sets the style for both pictures (style is not a shorter versionof pgfstyle)
If the value starts with [ the text until ] is interpreted as an option of the style It depends onthe definition of the style if and how this option is used (until now the text style the circlestyle and (since version 15) the curvemove style use such options) Attention to preventchessboard to interpret the ] as the end of its optional argument you must put bracesaround the whole value if you want to use options
Not every style is useful for everything eg it doesnrsquot make sense to put a border around amove The following tabular shows the predefined styles and the types for which they work
fields regions movescross 4
circle 4
text 4 4
border(s) 4 4
color 4 4
straightmove 4
knightmove 4
curvemove 4
With this commands you can define your own styles The commands take two argumentcbDefinePgfFieldStyle
cbDefinePgfRegionStyle
cbDefinePgfMoveStyle
the first is the name of the style the second should be the pgf-commands needed to draw
In previous version of the package the commands were called cbDefineMarkFieldStylecbDefineMarkRegionStyle and cbDefineMarkMoveStyle I have changed the namesto indicate that the commands will define the styles for the background picture too Theolder commands still work but I suggest that you switch to the new names
The listing shows first an example for a field mark then an example for a region where thesecond corner is accessed through the 1 and at last the definition for the text mark ndash hereit is necessary to rotate the text if the key inverse is true and the definition shows how theoptional argument of the pgfstyle key can be use with 2
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
Borders can be put around fields and regions There exist also partial borders for one two orthree margins of an area this borders are drawn and named ldquoclockwiserdquo ldquoleftrdquo ldquorightrdquo ldquotoprdquoand ldquobottomrdquo refer to the position of the border if the white player is at the bottom If youuse the key inverse the positions of the lines donrsquot change in relation to the players colors
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
Text can be used for fields and regions It is the only style where it isnrsquot enough to simplychose the style you must also give a value to the text content with the key text (donrsquotconfuse the key ldquotextrdquo with the style ldquotextrdquo)
The option of the style is passed to the optional argument of the pgftext command soeverything that is allowed there can be put in the option In the definition of the text contentyou can use informations about the current field or the current region currentbk eggives the black king corner of the region (when you draw in a region) or the field name (whenyou draw in a field) The opposite corner ist currentwq the white queen corner
As a default the text is centered on the middle of the field or the region You can use theoptions to move it around please look in the documentation of pgf to find out what ispossible
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
This style puts a colored square on or under the field or region At the start it was meant tocolor the background of the fields (and so it was only defined for the background) If usedfor the foreground on should set an adequate opacity
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
curvemove New in version 15 there is the more sophisticated curvemove which draws anarbitrary bezier curve between start and end field
curvemove accept an optional argument in key val syntax (If you use it donrsquot forget to putbraces arround the value)
First there are keys that lets you change the support points of the bezier curve The curveuse a local coordinate system The x-axis goes along the line from the start point to the endpoint The x-values set with the keys listed below are relative to the length of this arrow fromstart to end while the y-values are absolute (unit it the width of a square) Positive y valuesgive a curve going clockwise negative y values give a curve going anticlockwise With theclockwise=false you can change the sign of the y values
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
Second there are keys to change locally (only for the curve) the look of the arrow Theywork like the keys for chessboard with the same name arrow pgfarrow linewidthpgflinewidth shortenstart pgfshortenstart shortenend pgfshortenend
At last there is a key style which you can use to reuse saved keyval-lists Until now onlystyle knight exists and there is no user command to define new ones You want to use ownkeys sent me either a feature request or do it by defining the low level command
As the previous examples showed you can change quite a lot things of the pictures Nowhere a complete description of the needed keys The keys donrsquot draw anything directlyThey only put commands or definitions like colorred pgfsetfillopacity03 ordefboardpgfarrowto in the pgf-picture(s)
Let us now start with the keys which put a command in the pictures
color=langcolorrang color=red
pgfcolor=langcolorrang pgfcolor=red
This keys stores a color command (colorred) in the pgf picture(s)
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
The following keys puts only a definition in the pgf-pictures The values will only affect thestyles that use the internal commands in their definitions
padding=langlengthrang padding=01ex
pgfpadding=langlengthrang pgfpadding=01ex
This keys save defboardpgfpaddinglanglengthrang to the pgf-picture(s) The value can beused in various situations to change the offset of a line or a border of the area that is coveredby a color
Used currently by the border styles the styles that color fields in the background or theforeground to enlarge or reduce the covered area and the circle (the length is added to a startdiameter)
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
This keys save defboardpgfarrowlangarrow typerang to the pgf-picture(s) Styles can usethe command to set the arrow tips Look at the documentation of pgf to learn about theexisting arrow types (and how to define new ones)
Default is latex Used currently by the move styles
This keys save the definitions defboardpgfshortenstartlanglengthrang ordefboardpgfshortenendlanglengthrang or both to the pgf-picture(s) The commands can
May 1 2014 58 chessboard 17
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
be used eg in a pgfsetshortenstart command to shorten a line a the start or the end
As default the lengths are 0pt Used eg by the styles straightmove knightmove cross andthe partial borders The lengths are added to some start values that I thought reasonable Ifyou use large length (over 1ex) this can change the meaning of move marks as the mark willstart in another field
This keys save defboardpgflinewidthlanglengthrang to the pgf-picture(s) The commandcan be used eg in pgfsetlinewidth The keys marklinewidth and backlinewidth areremains from an older version There put the commands only in one picture and theyignore the values of the usepgf keys
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
The first two keys save defboardpgfcornerlanglengthrang to the pgf-picture(s) Thelast key will save the same definition only to the background picture and it will ignorethe value of the usebackpgf and usepgf keys boardpgfcorner can be used eg inpgfsetcornersarced to round the corners of a border To get sharp corners use the value0pt
The value is used currently only used in the border styles
With this key you can add arbitrary (pgf)-commands to the pictures Use it with care Whenyou use the key without an argument it will end a pgf scope and so reset colors and linewidthand some of the other values to their defaults
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
With this key you can control in which picture the commands or definitions are saved whenusing the keys described above
The default is to save everything in both pictures This means that is also adds somesuperfluous code to the other picture but I donrsquot think this is a problem In most cases youwonrsquot need the key
619 A special shortcut key for background border
pgfborder=langarearang pgfborder=c3-e4
With this key you can put a border around the area in the background picture The keysaves the current style calls the backstyle and the backregions keys to draw the borderand then restores the old style If you donrsquot give a value to the key the border is around theprintarea
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
chessboard[showmover=falseborder=falsehlabelwidth=06emvlabellift=13emprintarea=c3-f6pgfstyle=crosscolor=redlinewidth=1expadding=1expgfbordermarkfield=d4color=bluelinewidth=05expadding=25expgfborderpadding=0excolor=greentrim=falseto show the next borderpgfborder=boardmarkfield=e5]
6 0Z0Z5 Z0Z04 0Z0Z3 Z0Z0
c d e f
6110 Special shortcut keys for background color
colorbackboard=langarbitraryrang colorbackboard
colorbackarea=langarearang colorbackarea=a1-c3
colorbackareas=langlist of areasrang colorbackareas=a1-c3 f1-f2
colorbackfile=langfilerang colorbackfile=h
colorbackfiles=langlist of filesrang colorbackfiles=gh
colorbackrank=langrankrang colorbackrank=5
colorbackranks=langlist of ranksrang colorbackranks=87
colorbackfield=langfieldrang colorbackfield=g4
colorbackfields=langlist of fieldsrang colorbackfields=b5c6
colorwhitebackfields=langlist of fieldsrang colorwhitebackfields=b5c6
colorblackbackfields=langlist of fieldsrang colorblackbackfields=b5c6
This keys are shortcuts to color the background of the board They save the current stylecolor the fields and then restore the style
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
Removing pgf decoration from the board is easy if you used the optional argument ofchessboard But what should you do if you had added eg a mark with setchessboardfor the next four board and now want to get rid of it for the fifth That isnrsquot so easy as thecode is burried quite deep in a large list
On the whole there are three possibilities
bull Use grouping to keep the marks local to some boards
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
With this keys you can add one clipping path to each pgf pictures The clipping paths arealways around the print area The argument of the keys is key-value-list with the possiblekeys true false to enable or disable the clipping and the four keys left top right andbottom which take as value a length and are used to set the padding
As in other keys the value true can be omitted but this also means that you have to usethe value false explicitly if you only want to set some of the padding values but not enableclipping
May 1 2014 65 chessboard 17
newchessgamesetchessboard
trim=falseprintarea=b2-g7clip=left=05extop=05ex
right=-05exbottom=-05exfalse
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
border=falselinewidth=03empgfborderpgfstyle=colorcolor=blue50backrank=6backfile=ccolor=red50markrank=4markfile=fpgfstyle=textcolor=blacktext=a text in the foregroundmarkfield=b4text=a text in the backgroundbackfield=f6
chessboard
chessboard[markclip]
chessboard[backclip]
chessboard[clip]
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
a text in the background7 popopo6 Z0Z0Z05 0Z0Z0Z4 Z0Z0Z03 0Z0Z0Z2 OPOPOP
b c d e f g
a text in the foreground
6113 Trimming
Clipping cuts simply through the pgf-pictures and throws everything away that is outsidethe printarea This has the drawback that in the picture there could be eg remains of amove arrow that started outside the shown board
Trimming is an attempt for a more intelligent approach Objects like crosses circles textborders and arrows are discarded completely if they lie partly or completely outside the
May 1 2014 66 chessboard 17
defined scope of fields
Trimming to a area
trimarea=langarea|emptyrang trimarea
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
This sets and activates an trimarea If you omit a value printarea is used If you donrsquot give anarea but use the keyword empty everything following the key will be trimmed If you want todisable trimming use trimarea=board (or trim=false) As a default the trimarea is set tothe print area (and so activated)
The value of trimarea will affect all following objects drawn with the pgfstyle and therelated mark and back keys
Field related objects will be drawn if the field lies in the area Region related objects willbe drawn if the complete region lies in the area Move related objects will be drawn if thecomplete move lies in the area
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
As shown in the previous examples you can set a manual trimarea But you should be awarethat you can get unexpected results if this area is larger than the printarea
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
The key affects only the field related pgf-objects Regions and moves will ignore it The keyapplycolor from previous versions has now a similar effect8 This means that the key haschanged its behaviour it will now affect also the foreground picture
chessboard[printarea=c3-f6trim not really needed defaultpgfstyle=colortrimtocolor=whitecolor=redbackboardtrimarea=b2-g7trimtocolor=blackcolor=gray50backboard]
6 nZ0Z5 Z0o04 0ZPZ3 Z0ZN
c d e f
8I couldnrsquot retain the older behaviour due to the changes made in the code
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
It isnrsquot really difficult to use a graphic as background of the board You must use a boardfontencoding that hasnrsquot fields and fieldmasks And then you must use trial and error to findout which scalefactor and which viewport is fine There is absolutly no way to do thisautomatically as the border of the board in the graphic is unknown If you change the boardsize or the size of the left margin you will have to adjust the values
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
When used with the option ps the package skak puts in the middle of the right bottom field(that is either h1 or a8) a postscript node with the name BM The highlighting commands ofthe package skak use this node
To be able to use the commands also with chessboard you must load the package skakwith the option ps
As arguments in the commands of the package skak you can only use the fields of a 8times8-board
psset=langtrue|falserang psset false
This key sets the node BM at the place where the package skak expect it and it sets thepsunits to the size of the board This can affect other pspictures as the changes are madeafter the board and so arenrsquot local to the board (the commands of the package skak musthave a fighting chance to get the correct values)
psskak=langtrue|falserang psskak false
This key redefines some internal commands of the package skak I had to do it in order toget the highlighting commands to work I donrsquot think that it will destroy anything but didnrsquotwant to activate the changes unasked The changes are also not local to the board (but localto the group)
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
chessboard doesnrsquot know anything about chess rules It canrsquot do things like ldquoshow me thepossible moves of the rockrdquo ldquoshow me the allowed movesrdquo or ldquohighlight the last moverdquo Butas the examples show it accepts commands as arguments in the highlighting keys so itcan use the intelligence of external commands or applications Eg highlighting of the lastmove would be easy if the package skak would somehow save the last from-field and the lastto-field ndash something it doesnrsquot do now
7 Extending the game
71 Adding new pieces
With this command you can add new pieces that can be used on the boardcbDefineNewPiece
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
The optional argument langgamerang has not much use yet as there is only one sensible value skakwhich is the default anyway So leave it out
langcolorrang should by either white or black it will put the character in the list used by eg thekey hidewhite
langcharrang is the character used in FEN and the other input arguments Use a uppercase char forwhite pieces and a lowercase char for the black pieces or the keys like addwhite wonrsquot workcorrectly
langon whiterang and langon blackrang should contain the commands needed to print the piece on whiteand black fields The symbols should be scalable So you should either use symbols from afont or use some resizing command from the graphicx package
I have tried to prepare chessboard for other games A lot of internal commands can bechanged simply by changing the ldquoname of the gamerdquo Up to now there isnrsquot another game soI donrsquot know if this will really work
It should be easy to make boards for checkers if I find a font somewhere Chinese chess isa bit more complicated as one would have to decide how to make the background linesGo is more complicated as the pieces are sometimes numbered I donrsquot know yet if I could
May 1 2014 73 chessboard 17
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
implement a good input handling ndash but as there is a quite good package named igo I donrsquotthink I will really look into it
The main problem in any cases is the missing partner The package chessboard isnrsquot ldquointelli-gentrdquo As already mentioned above it doesnrsquot know anything about the rules of chess To beable to show ldquothe running gamerdquo it needs a partner that does the calculation
8 Compability with other packages
81 skak
The package chessboard works fine with the package skak You can use chessboard every-where instead of showboard etc
82 texmate
The new texmate version use the package skak to follow the game There is no problem to usechessboard where the manual suggest showboard texmate also defines its own diagramcommands They use internaly showboard I havenrsquot made much tests until now but itlooks like after a simple letshowboardchessboard you can use chessboard insteadThe main problem is that you canrsquot use the argument of chessboard You will have to setthe board properties with setchessboard
83 beamer
I wouldnrsquot have thought it but I had no problem to use chessboard with beamer
The following listing shows an example If your pdf-reader can handle annotations you can
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input
It also possible to use animate to get ldquomovingrdquo boards (you need a recent pdf-viewer to seethe effect) But it is quite tiresome to input all the moves Thatrsquos why I wrote the packagexskak It offers a possibility to store all positions of a game with the package skak and thento loop through them For an example please read the documentation of xskak Here anexample of the more tiresome input