Beginnings of installer for 4.4.0. HGM asked me to forward the nsi file,
[xboard.git] / winboard / install / files / root / WinBoard / doc / shortcuts.html
diff --git a/winboard/install/files/root/WinBoard/doc/shortcuts.html b/winboard/install/files/root/WinBoard/doc/shortcuts.html
new file mode 100644 (file)
index 0000000..e69162e
--- /dev/null
@@ -0,0 +1,200 @@
+<html>\r
+<header>\r
+<title>WGP: Shortcuts for WinBoard</title>\r
+</header>\r
+<body>\r
+<table cellpadding="20"><tr><td>\r
+<h1>The WinBoard Gold Pack 4.4.0</h1>\r
+<h2>For the ultimate WinBoard experience!</h2>\r
+</td><td>\r
+<img src="mini.gif">\r
+</td></tr></table>\r
+<h3>Customizing WinBoard through Shortcuts</h3>\r
+<p>\r
+The most convenient way to run invoke WinBoard is usually through PSWBTM,\r
+as this combines an easy way to select the engine with a large choice of engines.\r
+A viable alternative for things you do very often \r
+(e.g. play on FICS, or play your own engine on ICC)\r
+is to use a shortcut.\r
+Such a shortcut hardly offers any flexibility, as it always starts WinBoard with exactly\r
+the same combination of options.\r
+But it does allow you to start this combination with a single mouse click,\r
+which can be convenient for something you do frequently.\r
+And the WinBoard menus offer you a possibility to tailor some settings later.\r
+</p><p>\r
+If you browse to the WinBoard directory of this package (~\WinBoard),\r
+starting from "My Computer" on the desk top,\r
+You will see a number of black-knight icons.\r
+Except for the one marked "winboard" these are all shortcuts\r
+(recognizable from the small arrow in their lower left).\r
+They were defined as examples for how shortcuts can be used to ease some common tasks.\r
+</p><p>\r
+A good example to look how this works at is the "PGN viewer" shortcut.\r
+Double-click this, and you will see WinBoard pop up.\r
+Only the WinBoard main and move-history window will be there.\r
+Compare this to what you get when you click the winboard icon itself (i.e. not a shotcut):\r
+this will pop up the start-up dialog first, where you would have to tick that you want\r
+to use WinBoard to view or edit games only, after which it would come up in the default mode,\r
+with game history, engine output and evaluation graph all open up.\r
+(Unless you changed this default after downloading.)\r
+So to get into the same mode as was pre-programmed in the "PGN Viewer" shortcut,\r
+you would first have to close these auxiiary windows (in the "Mode" menu). \r
+So the shortcut does save quite some effort.\r
+</p><p>\r
+In a shortcut you can include any command-line options with the command that invokes WinBoard\r
+(in the target field that you see when you right-click the shortcut, and select "properties").\r
+The shortcuts in this package are all based on the use of "indirection" file arguments.\r
+That means that the actual arguments for, say, the "PGN Viewer" icon,\r
+are collected into a file "viewer.ini".\r
+The only option on the command-line in the shortcut is then "@viewer".\r
+Such a name preceded by a '@' sign is interpreted by WinBoard as the name of an .ini file\r
+(in this case viewer.ini), which is then read to get the actual option settings.\r
+This allows for far more options than can be put in the target line of the shortcut,\r
+and allows you to easily modify the options with a text editor like NotePad,\r
+rather than in the cramped confines of the shortcut properties dialog.\r
+</p><p>\r
+So when you want to change the settings of the shortcuts,\r
+you only have to change the contents of the corresponding .ini file.\r
+The shortcuts themselves only contain\r
+</p>\r
+~\WinBoard\winboard.exe @INIFILENAME\r
+<p>\r
+in their target field, \r
+where the twiddle stands for the path where you installed the Gold Pack.\r
+(Windows XP adapts this automatically, first time you use the shortcut.)\r
+And this can always stay that way.\r
+(Note that Windows XP and Vista do not show you the "@INIFILENAME" in the target field, \r
+when you open its properties dialog, which is a bit confusing.)\r
+</p>\r
+<h3>Changing the Shortcut Settings</h3>\r
+<p>\r
+There is thus no reason to ever touch the shortcuts themselves.\r
+All you have to do is to edit or replace the corresponding.ini file.\r
+For instance, for the shortcut to play against Fairy-Max,\r
+the settingsfile "fairy.ini" contains:\r
+</p>\r
+<pre>\r
+;\r
+; parameters for playing against an engine\r
+;\r
+/cp\r
+/firstChessProgram="fmax 22"\r
+/firstDirectory="../Fairy-Max"\r
+/secondChessProgram="fmax 22"\r
+/secondDirectory="../Fairy-Max"\r
+;\r
+;\r
+; define window layout\r
+;\r
+/autoLogo=true\r
+/moveHistoryUp=true\r
+/evalGraphUp=false\r
+/engineOutputUp=false\r
+/hideThinkingFromHuman=true\r
+;\r
+; define window positions\r
+;\r
+/winWidth=426\r
+/winHeight=539\r
+/moveHistoryX=426\r
+/moveHistoryY=0\r
+/moveHistoryW=250\r
+/moveHistoryH=539\r
+;\r
+;\r
+; prevent these settings from becoming default\r
+; \r
+/saveSettingsOnExit=false</pre>\r
+<p>\r
+One thing that is apparent is that a .ini file can contain "comments"\r
+describing what the options do, in lines starting with a semicolon.\r
+From top to bottom, the options tell WinBoard that we want it \r
+to run a Chess program (so it skips the startup dialog),\r
+which one, and where to find it.\r
+Note that WinBoard always wants to have two Chess programs in this mode,\r
+so we give it the same twice.\r
+(The second program is only used when you select Two-Machines Mode.)\r
+In the next section we tell WinBoard that it should try to find logos\r
+to display with the players,\r
+that of the three auxiliary windows only the move history should be open,\r
+and that the Human opponent should not be alowed to see what the engine\r
+is thinking.\r
+</p><p>\r
+Then follows a section which describes exactly where to locate the windows,\r
+in this case only the move-history window.\r
+The position of this is given (in pixels) compared to the position of\r
+the main window.\r
+Note it does not specify where to position the main window,\r
+or what boardSize to use.\r
+So for this the default value will be used.\r
+(Usually what was used last time, as remembered in the winboard.ini file.)\r
+For reference, though, the width and height of the main window for\r
+which the position information on the other windows refers,\r
+is mentioned first, as /winWidth and /winHeight.\r
+This allows WinBoard to conclude at startup that the move-history window\r
+was touching the main window on the right edge \r
+(since winWidth = moveHistoryX).\r
+So that it can retain this attachment if we start up WinBoard with\r
+a main window of a different width.\r
+(E.g. because we are playing Gothic Chess on a 10x8 board.)\r
+</p><p>\r
+At the bottom there is an option that says all this should not be copied \r
+to the win     board.ini file automatically.\r
+After all, because these settings are collected in a shortcut,\r
+you can summon them at the click of a mouse.\r
+So there is no reason to make them disturb the carefuly chosen settings \r
+of your previous session,\r
+which might take you a lot of effort to reproduce.\r
+</p><p>\r
+OK, that was pretty nasty, especially the coordinates part.\r
+You don't want to calculate coordinates by hand, and find out by trial and\r
+error what looks nice.\r
+A more convenient way of adjusting this, \r
+is to start WinBoard not through a shortcut, but through the startup dialog,\r
+and then drag and size the windows where you want them \r
+(or close them if you don't want them).\r
+You then save the settings in winboard.ini\r
+(usually done automatically, when you close WinBoard,\r
+but you can do it also with the "Options -> Save Settings Now" menu).\r
+Now you can open winboard.ini with the text editor,\r
+and at the end you will see all the coordinates of the windows as\r
+you just layed them out.\r
+Simply copy this information (starting with the /winWidth parameter)\r
+to the .ini file of the shortcut you are customizing.\r
+</p>\r
+<h3>Making a Shortcut from Scratch</h3>\r
+<p>\r
+If you want to create an entirely new shortcut, \r
+e.g. for a task you commonly perform, but which was not delivered with this package,\r
+you can use the following procedure:\r
+</p><p>\r
+First start up WinBoard, and bring it in exactly the state you would want it\r
+to start up in through the shortcut.\r
+Then save the settings on the winboard.ini file,\r
+make a copy of winboard.ini, and rename that copy to "MyShortcut.ini" (say).\r
+Then open this MyShortcut.ini in NotePad (usually by double-left-clicking it).\r
+Now you can add option settings to it which are normally not remembered\r
+from session to session (because they are not saved in winboard.ini),\r
+such as the variant (e.g. /variant=fischerandom),\r
+or the chess program and its folder (e.g. /fcp=Fruit /fd="..\Fruit" /fUCI).\r
+</p><p>\r
+Right-click the "winboard" knight icon (which is not a shortcut),\r
+and select "Make Shortcut" from the popup menu.\r
+Change the name of the newly appearing shortcut to "MyShortcut".\r
+Then right-click this shortcut, and select "Propeties".\r
+The text in the "target" field of the popup will now just be the name of the winboard.exe.\r
+Click this text at the end to put the cursor there (posibly with help of the arrow keys).\r
+Then add to this line " @MyShortcut.ini", so the line becomes:\r
+</p>\r
+~\WinBoard\winboard.exe @MyShortcut.ini\r
+<p>\r
+and click "OK". This completes the process.\r
+</p><p>\r
+This is pretty much all that can be said about how to mak shortcuts;\r
+the main problem is to figure out what the options are that do what you want done.\r
+Looking in the winboard.ini file often can provide inspiration, and when all else fails,\r
+as a final resort, you can read the manual!\r
+</p>\r
+\r
+</body>\r
+</html>
\ No newline at end of file