"readme-PGN" for "40H-PGN-2026" Tools & Utilities. 

"40H-PGN" is a collection of Command Prompt utility tools by Norman 
Pollock (USA) that is free to download for personal use. The tools 
are primarily for use with "pgn" data files in "Windows" or in a 
"Java Runtime Environment".

"40H-PGN" tools and instructions are copyright (c) 2007-2026 by
Norman Pollock. All rights reserved.

"40H-PGN" can be freely downloaded and used for non-commercial
purposes as long as "40H-PGN" is kept intact and no changes are made
to any files. Any commercial distribution or commercial use of 
"40H-PGN" is strictly forbidden.

Disclaimer: The "40H-PGN" package is distributed "as is". No warranty
or guarantee of any kind is expressed or implied. The user assumes all
risks of usage. The author is not responsible for any damage or losses
of any kind caused by the use or misuse of the tools or this
"readme-PGN" file.

Current download sites for "40H Tools":

    40hchess.epizy.com 

    nk-qy.info/40h  (Thanks to Frank Quisinsky)  
    
Please bookmark.
  
Contact: Norman Pollock rc1242@yahoo.com
  
====================================================================

FAQ:

1. What is the purpose of "40H" tools?

   "40H" tools enable users to do specific chess tasks. 
   
2. What computer skills are needed to use the "40H" tools?  

   The user has to be able to use command-line commands in a
   "Command Prompt" window.

3. Where are the full usage instructions for each "40H" tool?

   Please read the full usage instructions before using a tool.
   FULL USAGE INSTRUCTIONS are the last section of this readme.
   A quick way to go there is by using a text search (ctrl+F).

4. If I only want to download one tool, why do I have to download
   a compressed file containing many tools? 
   
   "40H" tools are organized as a collection of individual tools 
   instead of one big tool with many task parameters. Any tools 
   that you do not want are easily deleted. Just delete their 
   "exe" file.
   
5. What does the term "40H" have to do with chess?

   40H is a hexadecimal and computer science number that is equal
   to the number of squares in a chessboard. 40H = 64 decimal.

6. Do the "40H" tools require Internet access?

   Only to download the tools. 

7. On which platforms will the "40H" tools work?

   "40H" tools come in 2 formats: "Windows" executables (".exe") 
   and "Java Class Files". Download "40H-Java Class Files" for 
   non-Windows platforms. 
   
8. Are the "40H" tools portable?

   Yes. You can even save them on a flash drive and use them on 
   different PCs. They are single files and no "dlls" are required.
   They do not require a "setup" program and they do not affect the 
   registry. They can be removed by simple deletion.

9. Are the "40H" tools 64-bit and do they use multiprocessing?

   They are each 32-bit tools and they do NOT use multiprocessing.
   
10. Are the "40H" downloads checked for viruses/malware?

   "40H" downloads are checked at www.virustotal.com
   
11. Is the "readme" file included in the download?

   Yes, and it is also on the website. The version on the website 
   has the latest updates and corrections.
      
====================================================================

OVERVIEW OF TOOLS (FULL INSTRUCTIONS AT THE END OF THIS FILE)

Each "40H-PGN" tool consists of a single file. Each tool executes 
from a command-line in a "Command Prompt" window.

The "40H-PGN" tools do not change any input file. Output appears
in a new file(s).

There are 55 tools in "40H-PGN".

1. "cleanUp" removes games that have certain irregularities mainly
in the "Tag Section". The removed games are saved in a separate file
and can be repaired using a text editor.

2. "clusterList" lists the different player clusters of the input 
"pgn" file. It also lists the number of games and the number of 
distinct opponents for each player.

3. "colorList" lists each player's results by color played - games 
as White, and games as Black.

4. "eco500" creates 500 files from a "pgn" file. The files are named
"ecoA00" through "ecoE99". Each game is extracted into the output 
file whose name corresponds to the first three characters of its 
ECO code. Games without an "ECO" tag are extracted to "ecoN.pgn".

5. "ecoExtract" extracts games whose ECO code matches a user-specified
ECO code, or is within a user-specified ECO range. Only the first 
three characters of the ECO codes are used for comparisons.

6. "ecoList" lists each ECO code used, the number of games, the White
score percentage, and the number of White wins, draws, and losses.

7. "ecoPlayer" produces a list based on a user-specified player. For
each color and for each ECO code used, it lists the number of games,
the score percentage, and the number of wins, draws, and losses.

8. "ecoSplit" separates the input file into six files based on the 
first character of the ECO code. There is an output file for "A", 
"B", "C", "D", "E" and "no ECO".

9. "eloCheck" removes games that are missing either the "WhiteElo" 
or "BlackElo" tag or both. The resulting output file can be used for
Elo computations without concern for distortions caused by missing
Elo tags.

10. "eloExtend" inserts missing Elo tags for players who already have
at least one Elo tag. "eloExtend" inserts the average of the existing 
Elo tags. Existing Elo tags are not overwritten.

11. "eloGap" extracts games in which the players' Elo gap (absolute 
value of Elo difference) is less than or equal to a user-specified 
maximum gap.

12. "eloInsert" inserts Elo tags with user-specified Elo ratings for 
user-specified players. Existing Elo tags are overwritten.
 
13. "eloList" lists player names, number of games, average Elo, 
minimum Elo, maximum Elo, opponents' average Elo and player 
performance Elo.

14. "eloRemove" removes all "WhiteElo" and "BlackElo" tags.
 
15. "emBayes" uses Elo ratings from "BayesElo" by Remi Coulom to
insert new Elo tags. The user has the option to keep existing
Elo tags.

16. "emOrdo" uses rounded Elo ratings from "Ordo 1.0" by Miguel 
Ballicora to insert new Elo tags. The user has the option to keep 
existing Elo tags.

17. "emStat" uses Elo ratings from "EloStat 1.3" by Frank Schubert 
to insert new Elo tags. The user has the option to keep existing
Elo tags.

18. "fenRemove" removes games containing a "FEN" tag except when
the "FEN" position is the standard opening position.

19. "gameMerge" joins 2, 3, 4, or 5 "pgn" files by inserting one game 
from each successive input file, and then repeating until all games 
have been inserted. 

20. "gameNum" inserts consecutive "game number" comments between the 
"Tag Section" and the "MoveText Section".

21. "gameSplit" separates the input "pgn" file into a user-specified
number (2-10000) of files. All games are kept intact within one of 
the output files. The number of games in each output file is "equal", 
plus or minus 1 game.

22. "groupExtract" extracts games in which each player's name begins 
with a name_search-string located in a user-created text file named 
"group". 

23. "listExtract" extracts games in which at least one of the player 
names begin with a name_search-string in a user-created text file 
named "list". 

24. "minDate" extracts games that occurred within a user-specified
time span.

25. "minElo" extracts games where the players' Elo values are in an
user-specified range or ranges.

26. "minOccur" extracts games of players who meet or exceed a user-
specified minimum number of games in the input file.

27. "minPly" extracts games in which the number of plies (half-moves)
is within a user-specified range. "minPly" uses the value in the
"PlyCount" tag to obtain the number of plies in a game.

28. "nameChange" performs user-specified player name changes based
on a user-created text file named "changes".

29. "nameColor" adds a token, "(wh)" or "(bl)", to each player's name 
depending on the color being played. For example, "Karpov, A. (wh)" 
and "Karpov, A. (bl)".

30. "nameExtract" extracts games in which at least one player's name 
begins with a user-specified name_search-string. 

31. "nameList" lists player names and games played in 3 different
output files. It also has the option to output names in "all caps".

32. "nameSimilar" lists groups of player names where each group's 
names start with the same token or the same three characters. The 
number of games for each player is listed.

33. "numExtract" extracts games whose game number matches a game
number in a user-specified text file "numbers".

34. "pairExtract" extracts games in which each player's name begins 
with a different name_search-string from the same pair in a user-
created a text file named "pairs". 

35. "pairList" double lists each player pairing. The order of players 
is reversed in the second pairing. Results are included. The pairings 
are sorted by player names. 

36. "pairSplit" extracts the games of each player pair into its own 
file. Only the first 1000 player pairs (in sorted order) are processed 
at each "pairSplit" execution. The remaining games are collected into 
an "exclude" file which can be processed at a later time.

37. "pgn2stream" converts a "pgn" file into a "move steam" file.
A "move stream" is a full chess game condensed to a single line.
It consists of the moves and the result, and optionally, the move 
numbers.

38. "playerExtract" extracts the games of a user-specified player. 
It also outputs the player's games by color and result.

39. "plyCount" counts the number of plies (half-moves) of each game
and inserts a new "PlyCount" tag if one is missing. Existing
"PlyCount" tags are unchanged. Also produces a listing of plycounts
and the number of games.

40. "resultList" lists player names, number of games, number of 
wins, draws, losses, score percentages, points, and S-B tie-break 
points.

41. "resultSplit" separates the input file into four files based on 
the results of the games. There is an output file for "White Wins",
"Draws", "Black Wins", and "no result".

42. "stream2pgn" converts a "move stream" file into a "pgn" file. 
A "move stream" is a full chess game condensed to a single line.
It consists of the moves and the result, and optionally, the move 
numbers.

43. "summary" produces statistics involving games, players, dates, 
results, white/black, Elo ratings, plycounts, and ECOs. Optionally,
"summary" can produce statistics for the number of player clusters 
and the number of player pairings.

44. "tagCreate" inserts a user-specified tag type (other than 
"Event") into the Tag Section of each game. The "Event" tag must 
already be present. All previous tags of the inserted tag type 
are overwritten.

45. "tagExtract" extracts games based on a user-specified tag type
and a user-specified search string. The search string can either 
be a single token or a complete tag value.

46. "tagFix" repairs a limited number of tag irregularities. 

47. "tagInsert" replaces all tag values of a user-specified tag type 
with user-specified values in a text file. The tag type must be 
present in every game of the "pgn" file.

48. "tagList" lists each tag type that occurs in the "pgn" file 
and the number of its occurrences.

49. "tagNull" replaces all values of a user-specified tag type with 
its null value EXCEPT for the "FEN" tag. 

50. "tagOrder" rearranges the tag types into a generally accepted 
order. The first 13 tag types are ordered as follows: "Event", 
"Site", "Date", "Round", "White", "Black", "Result", "WhiteElo", 
"BlackElo", "ECO", "SetUp" and "FEN". Then come various other tags 
in their original order, followed by the "PlyCount" tag.

51. "tagRemove" can remove all instances of a user-specified tag 
type EXCEPT for "Event" and "FEN". 

52. "tagValue" lists the data values of a user-specified tag type 
and the number of occurrences of each data value. 

53. "trim" produces an output "pgn" file that puts each "full move" 
on the same line while also removing comments if present. "trim" 
lets you set the maximum output width in the "MoveText Section" from 
40 to 100 characters. The default is 76 characters.

54. "truncate" counts the number of plies (half-moves) and then 
removes any plies occurring after a user-specified number. If a game 
has fewer plies than the user-specified number, that game is output 
without change. Results are not removed.

55. "upset" extracts games between two players having an Elo 
difference equal to or greater than the "min_Elo_difference", which 
by default, is 250. Output is in three files for wins, draws, and 
losses.

---------

Note the "40H-EPD" tools have 7 batch script "PGN" tools that are 
different from any of the "40H-PGN" tools. 

Here is a summary of the batch script tools in "40H-EPD":

  pgn3fold.cmd: 
             extracts "pgn" games containing a 3-fold repetition 
             of a position. Uses "pgn-Extract", "epd3fold" and 
             "numExtract".
  
  pgnFin.cmd:
             lists the final position of each "pgn" game in "epd" 
             format. Uses "pgn-Extract" and "epdFin".
             
  pgnInsuff.cmd:            
             extracts games ending in a position with insufficient 
             material for a checkmate. Uses "pgn-Extract", "epdInsuff" 
             and "numExtract".
 
  pgnMask.cmd:   
             extracts "pgn" games containing a user-specified 
             position structure in "epd" format. Uses "pgn-Extract",
             "epdMask" and "numExtract".

  pgnMaterial.cmd:   
             extracts "pgn" games containing a position with piece/
             quantity values from the user-specified file "pieces".
             Uses "pgn-Extract", "epdMaterial" and "numExtract".
  
  pgnPly.cmd:
             lists the position in each "pgn" game that occurred 
             after a user-specified ply. Outputs in "epd" format.
             Uses "pgn-Extract" and "epdPly".
             
  pgnPosition.cmd:
             extracts "pgn" games containing a position within a 
             user-specified file of "epd" positions. Uses 
             "pgn-Extract", "epdPosition" and "numExtract".

Full instructions are available in the instructions for the related
"40H-EPD" tool. The 7 batch script "pgn" tools are included in the 
"40H-EPD" download.

All files executed within the batch script must either be in the 
Working Folder or on the System Path. An input data file must be 
in the Working Folder or be specified with a pathname.

====================================================================

INTRODUCTION:

Download the "40H-PGN" file. It is packed in 7-zip format. You can 
unpack it using "7-zip", available at:  http://www.7-zip.org

Unpacking the "40H-PGN" download file results in 55 "Windows" 
executable files. 

This "readme-PGN" file is oriented to users of the "Windows" 
executable files. Users of the "Java" class files have to make 
adjustments for use in a Java Environment.

Each "40H-PGN" tool is a "command-line tool", which means that 
it executes on a command-line in a "Command Prompt" window. 

The "40H-PGN" tools were written in "Java" and then compiled 
using "gcj 3.4". All coding is original.

Each "40H-PGN" tool consists of a single self-contained file. 
No external "dlls" are required. Each "40H-PGN" tool is portable
and just has to be copied to be installed. It does not need a setup
program and it does not write any data to the registry.

Unless otherwise indicated, each "40H-PGN" tool inputs a "pgn" 
file. "40H-PGN" tools DO NOT MAKE ANY CHANGES to input files. 

Output appears in a new file(s). Output files are pre-named. Users 
should rename the output file(s) before they are overwritten by 
the next execution of the tool.

"40-PGN" tools assume the games in the "pgn" input files are 
written in Standard Algebraic Notation ("SAN") and adhere to the 
"Standard PGN Specification Guide".

The "Standard PGN Specification Guide" ("PGN Standards") is currently 
at:

  http://www.saremba.de/chessgml/standards/pgn/pgn-complete.htm

The 55 "40H-PGN" tools are: cleanUp, clusterList, colorList, eco500, 
ecoExtract, ecoList, ecoPlayer, ecoSplit, eloCheck, eloExtend, 
eloGap, eloInsert, eloList, eloRemove, emBayes, emOrdo, emStat, 
fenRemove, gameMerge, gameNum, gameSplit, groupExtract, listExtract, 
minDate, minElo, minOccur, minPly, nameChange, nameColor, nameExtract, 
nameList, nameSimilar, numExtract, pairExtract, pairList, pairSplit,
pgn2stream, playerExtract, plyCount, resultList, resultSplit, 
stream2pgn, summary, tagCreate, tagExtract, tagFix, tagInsert, 
tagList, tagNull, tagOrder, tagRemove, tagValue, trim, truncate and 
upset.
 
Thanks to Jim Ablett for helping me get started on this project and
for showing me how to create "Windows" executables for the tools.

======================================================================

LIMITATIONS:

"40H-PGN" tools ONLY execute from a command-line within a Command 
Prompt. See http://dosprompt.info/ for Command Prompt support.

"40H-PGN" tools are subject to the capacities of the maximum array
sizes that are specified in their coding. These maximum array sizes 
are adequate for most "pgn" input files. However if you use a very 
large "pgn" input file, there is a possibility that an overflow
error will occur or that execution will take an extended amount of
time.

"40H-PGN" tools are limited by the available system memory. If you
can close unrelated tools that are open, then more system memory 
will be available.

In either of the above two situations occur, the user could try any 
of the following workarounds:
(1) Use "trim" to remove comments if present; 
(2) Use "gameSplit" to separate the input "pgn" file into smaller
files; 
(3) Use "listExtract" (or "groupExtract") to extract the games 
of the most important players.

If the input "pgn" data file does not conform to "PGN Standards",
"40H-PGN" tools may not perform properly. 

"40H-PGN" tools treat each unique player name string as a distinct
player. Therefore two players using the same name string are treated 
as the same player. Likewise, if one player has two different name 
strings, he is treated as being two different players.

"40H-PGN" tools might give incorrect statistical results if the 
input "pgn" file contains any games where the two players' names 
are identical. Use the "40H-PGN" tool "cleanUp" to remove such games.
   
"40H-PGN" tools might not perform properly if the Elo tags are in 
certain non-standard arrangements. For example, having the "WhiteElo"
tag precedes the "White" tag, or having the "Result" tag precede the 
"WhiteElo" tag, can cause incorrect output. Using "tagOrder" will 
correct this problem.

"40H-PGN" tools that make calculations based on Elo ratings may not
perform properly if one or both Elo ratings are missing from any game.
Using "eloCheck" will remove games that are missing an Elo tag.

"40H-PGN" tools cannot detect illegal moves, inconsistent results,
and incorrect results. Use "Joined" by Andreas Stable to detect many 
types of irregularities that sometimes can be fixed using a text 
editor. Also, use "PGN-Extract" by David Barnes to detect and fix 
many types of irregularities. In extreme cases, "PGN-Extract" will 
delete a game having a serious irregularity. "PGN-Extract" also 
changes Long Algebraic Notation to Standard Algebraic Notation 
("SAN").

"40H-PGN" tools cannot detect duplicate games (games with the same 
moves). Use "PGN-Extract" by David Barnes to detect and remove 
duplicate games. "40H-PGN" tools cannot detect "twin" games (games 
with almost the same moves). Use a combination of "pgnPly" and 
"epdOccur", from "40H-EPD", to detect possible "twin" games. 

"40H-PGN" tools cannot "ECO" classify games or sort games. Use
"SCIDvsPC" by Steven Atkinson (based on "SCID" by Shane Hudson 
& Pascal Georges), for these purposes. 

"40H-PGN" tools cannot detect "blunders" within a game. Use "Game 
Analyser" by Thomas McBurney for this purpose. 

Use this setup for "SCIDvsPC": 
Go to "Tools"
Go to "Exporting All Filter Games"
Go to "Export Filter to PGN"  
then
Use the "yes" choice for
"Space after Move Numbers"
"Insert newlines every 80 chars",
"Convert null moves to comments".
then
Use the "no" choice (or "no" column) for all other options.

The following "40H-PGN" tools depend upon the output of external
tools: "emBayes" ("BayesElo version 0056"), "emOrdo" ("Ordo 1.0"), 
and "emStat" ("EloStat 1.3"). Other versions of the external tools 
may not work properly. "40H-PGN" has no control over the external 
tools.

Newer versions of external tools mentioned in this document may or 
may not work properly with "40H" tools. In addition, the 
availability to download those tools may change. For example, a web 
site may change to a new address, or even discontinue. Any such event 
could affect "40H" tools. It is therefore suggested that you continue 
to keep a copy of any (old) version of an external tool that works 
properly with "40H" tools.

====================================================================

INSTALLATION, FILES, AND FOLDERS:

Create a folder named "40H" if it does not already exist. Extract 
the download into the "40H" folder. The extraction will unpack the 
55 tools into a "40H-PGN" subfolder named "40H-PGN-2026".

For users who only will be using the "40H-PGN" tools occasionally,
the simplest arrangement is to copy the desired tool to the folder
where the input file(s) are located, and then run in that folder. 

Likewise, you could copy the input file(s) to the folder where the 
"40H-PGN" tools are located and then run in that folder.

For users who will be using "40H-PGN" tools often, copy/move the 
"40H-PGN" tools to a folder that is already on the System Path. 
(Type "path" in a command window to see the System Path.) This 
way you can run any of the "40H-PGN" tools from any folder without 
having to specify the path. 

If you do not have such a folder on your System Path, you would 
first have to create the folder and then edit the Path Variable. 
Use "search" in "Settings" to find "System Environment Variables".
Then click on "Environment Variables", then "Path" in "System 
Variables", and then "edit". This may vary depending on Windows 
version.

To summarize:

(1) If the tool and input file(s) are in the same folder, and you
are working in that folder, you are good. 

(2) If the tool is in a folder on the System Path, and you are 
working in the folder containing the input file(s), you are good.

(3) You should always be working in the folder containing the input 
file(s). This folder is referred to as the "Working Folder". It is 
also the folder where output files will be created. 

(4) Pathnames are needed if an input file is not in the Working 
Folder.

Input files are not changed. For extra safety, the user should save 
all input "pgn" files on another storage medium. 

Output appears in a new file(s).

A "40H-PGN" tool cannot use its output "pgn" file as an input file 
unless the filename is changed.

Running a "40H-PGN" tool without mentioning all required files and
parameters will list the version number of the tool, the syntax,
an example of usage, and the names of the output files.

Output files are TEMPORARY files. They are created in the Working 
Folder. Be sure to rename/copy/move any output files that you want 
to keep. The next execution of the tool in that folder will 
overwrite the previous output file(s).

Do not change an original output file to "read-only" as that will 
prevent the creating tool from executing in that folder.

Many "40H-PGN" output filenames are in the form "out*.pgn". Many 
times the records NOT extracted to "out*.pgn" are output to files 
whose filenames are in the form "exclude*.pgn". Sometimes the user 
is more interested in "exclude*.pgn" than in "out*.pgn".

"40H-EPD" tools accept "UTF-8" encoded "epd" files. However, all
"40H-EPD" output files are "Latin-1" encoded. "Latin-1" is the 
"PGN Standard". 

====================================================================

EXECUTION:

Each tool executes from a command-line in a "Command Prompt"
window. The general format for running a tool is:

  tool_name  [data_filename] pgn_filename [parameter(s)]
  
Examples:

  1. summary alpha.pgn 

  2. eloInsert elovals alpha.pgn  (uses data file)

  3. emStat rating.dat alpha.pgn keep  (uses data file & parameter)

After entering the proper command-line, and making sure all files
are accessible, press <enter> to start execution.

Some tools, like "clusterList", "pairList" and "trim", take more 
time to execute compared to other "40H-PGN" tools. This can be
noticeable with very large input files.

Output is in a new file(s) in the Working Folder. The original 
input file is not changed.

Be sure to follow the specific instructions for each tool.

====================================================================

HANDLING OUTPUT ISSUES

If you are getting inaccurate output from a "40H" tool, or having
some other problem, be sure you are using the latest "40H" version 
and the latest version of any ancillary tool. 

Then be sure the "pgn" input file is following "PGN Standards".

The following tools can check or clean up a "pgn" file:
 
  (1) "PGN-Extract" by David Barnes 
      for example:
        pgn-extract -s -N -C -V -ooutfile.pgn infile.pgn
  (2) "tagFix" in "40H-PGN"
  (3) "cleanUp" in "40H-PGN"
  (4) "Joined" by Andreas Stable (only indicates problems)
  (5) "Notepad++" by Don Ho (finds hidden characters when set 
      to show all characters, and can load very large "pgn" 
      files)
      
Occasionally some "40H" tools (plyCount, trim, truncate) exit early 
when processing very large "pgn" input files of over 500,000 games. 

Here are some work-arounds the User can try.

First, make sure there are no unlimited length lines in the "pgn"
file. If there are, use the following on the input file (alpha.pgn) 
before using the tool that is exiting early:

  PGN-Extract -s -w80 -obeta.pgn alpha.pgn

Second, rerun the "40H" tool after a 30-second wait. If using a 
Batch/Script, use a pause command before using the tool with the 
problem:

  timeout /t 30 
        
====================================================================

EXTERNAL TOOLS:

Future updates of external tools might or might not work
properly with "40H-PGN" tools. Listed below with each tool
is a recent version number that is compatible with "40H-PGN"
tools. 

Users need a "PGN Viewer" to see a game or a position. The 
"PGN Viewer" could also be a GUI (graphical user interface).

"PGN-Extract" by David Barnes is a PGN/EPD/FEN utility tool that 
performs many functions. 

"PGN-Extract" is free to download. The current download site is:

  http://www.cs.kent.ac.uk/people/staff/djb/extract.html
  
"SCIDvsPC" is an excellent utility tool with many functions.
Be sure that it outputs "pgn" files with multi-line "MoveText" 
sections. This can be set by going to 
Tools/Export All Filter Games/Export Filter to PGN/ 
and then checking "yes" for "Insert newlines every 80 chars?".

"Arena" (version 3.5.1) by Martin Blume is a UCI/Winboard Graphical 
User Interface.

"Arena" is free to download. Its current download site is:

  http://www.playwitharena.com/

====================================================================

BATCH SCRIPTS ("cmd" or "bat" files)

Using batch scripts can greatly increase the convenience of the 
"40H-PGN" suite. It can be used to string together several tools.

All files mentioned within the batch script should be in the Working 
Folder or on the Path.

====================================================================

EN PASSANT INDICATORS

"En passant" indicators, "ep", "e.p." and "/ep", are sometimes present
in a "pgn" game. These indicators are optional, rarely occur, and 
serve no purpose. A computer engine or a good chess player can easily 
see if an "en passant" move had occurred without needing an indicator. 
Also, if external "pgn" software is not adapted to "en passant" 
indictors, there could be errors in the counting of plies or the input 
of the "pgn" file. 

It is recommended that the user remove these indicators if they are
present. The "40H-PGN" tool "trim" removes them, as well as removing 
comments and variations. 

The "40H-PGN" tools "truncate" and "plyCount" remove these indicators
during processing to prevent plycount errors. The indicators are not
sent to the output file.

Other "40H-PGN" tools accept files with these indicators and output
the indicators, but these tools do not do any processing that is 
affected by the indicators. 

======================================================================

CHECKING RESULTS

Before using a "40H-PGN" tool that relies upon game results, it is
a good idea to first run "pgn-extract" (by David Barnes) with the 
"fixresulttags" option. This will check for several possible errors 
and correct them if necessary. For example:

  pgn-extract -s --fixresulttags -otemp.pgn input.pgn
  resultSplit temp.pgn

====================================================================

FULL USAGE INSTRUCTIONS:

=========================(1) cleanUp ===============================

"cleanUp" removes games that have certain irregularities mainly in 
the "Tag Section". The removed games are saved in a separate file 
and can be repaired using a text editor. 

The output file is "out2.pgn". Removed games are in "exclude2.pgn".

The possible "irregularities" are: a required tag not occurring 
or occurring more than once, games with no result ("*") in either 
the "Tag Section" or at the end of "MoveText" section, a null value 
for a player name, an illegal "Date" value, and self-play games.

Syntax:   cleanUp filename.pgn

Example:  cleanUp alpha.pgn

Output:   out2.pgn, exclude2.pgn

Comments:

     1. "cleanUp" does NOT remove games that do not have moves.
        To remove such games, and games with just a few moves, use
        "minPly".
        
=========================(2) clusterList ===========================

"clusterList" lists the different player clusters in the input "pgn"
file. It also lists the number of games and the number of distinct 
opponents for each player.

A "cluster" consists of all the games played by a closed network 
of players. A "pgn" file can have more than one cluster. In that
scenario, a player whose games are in one cluster, did not play 
(in the "pgn" file) any games against a player whose games are in 
another cluster, and there is no linkage through games played to
each other.

A player's number of distinct opponents tells how many other 
players in his cluster played at least one game against him.
"pairList" can identity those players.

There are two output files. "outCluster" separates the players by
cluster. "outCluster2" lists all the players together. If the input
"pgn" file has only 1 cluster, then the two output files will be 
the same.

"clusterList" assigns an identification number to each cluster in
order to distinguish one cluster from another. 

Syntax:   clusterList filename.pgn

Example:  clusterList alpha.pgn

Output:   outCluster, outCluster2 

Comments:

     1. "groupExtract" can be used to extract a cluster.
     
=========================(3) colorList =============================

"colorList" lists each player's results by color played - games as 
White, and games as Black.

Games without a result ("*") are ignored.

"playerExtract" will extract a player's games by color.

"nameColor" adds a token to each player's name to distinguish games
played with White and Black.

Syntax:   colorList filename.pgn

Example:  colorList alpha.pgn

Output:   outColor

Comments:

     1. Use "cleanUp" to remove games without a result ("*").

=========================(4) eco500 ================================

"eco500" creates 500 files from a "pgn" file. The files are named
"ecoA00" through "ecoE99". Each game is extracted into the output 
file whose name corresponds to the first three characters of its 
ECO code. Games without an "ECO" tag are extracted to "ecoN.pgn".

"eco500" works with game ECO codes of 3, 4 or 5 characters. 
ECO codes of 4 or 5 characters are referred to as "extended 
ECO codes". Examples: A41e, E99b2. However "eco500" only uses the 
first 3 characters for extracting games. 

Files are formed even if they are empty.

Syntax:   eco500 filename.pgn

Example:  eco500 alpha.pgn

Output:   ecoA00.pgn,..., ecoA99.pgn, ecoB00.pgn,..., ecoE99.pgn, 
          ecoN.pgn

Comment:

     1. ECO codes are case-sensitive.

     2. "ecoExtract" and "ecoSplit" also extract games based on 
        ECO codes.

=========================(5) ecoExtract ============================

"ecoExtract" extracts games whose ECO code matches a user-specified
ECO code, or is within a user-specified ECO range. Only the first 
three characters of the ECO codes are used for comparisons.

The output file is "outQ.pgn". Games not extracted to "outQ.pgn" 
are in "excludeQ.pgn".

"ecoExtract" works with game ECO codes of 3, 4, or 5 characters. 
ECO codes of 4 or 5 characters are referred to as "extended" ECO 
codes. Examples: A41e, E99b2. However "ecoExtract" only uses the 
first 3 characters of the ECO code for extracting games.

The first character of an "ECO" code must be in the range "A" to "E". 
The second and third characters must be in the range "0" to "9".

Example: ecoExtract alpha.pgn B21

This will extract all games whose ECO code starts with "B21". For
example, this will include ECO codes "B21", "B21d", "B21c2".

Example: ecoExtract alpha.pgn B21 D30

This will extract all games whose ECO code starts from "B21" to 
"D30" inclusive. For example, this will include ECO codes "B21",
"B21h", "B99", "B99m", "C00", "D06", "D30", "D30k2".

To extract just the games of a specific extended ECO code, it may
be better to use "tagExtract". Example:

  tagExtract alpha.pgn ECO "B21d"  

Syntax:    ecoExtract filename.pgn eco_string1 [eco_string2]

Examples:  ecoExtract alpha.pgn B21

           ecoExtract alpha.pgn B21 C14

Output:    outQ.pgn, excludeQ.pgn

Comments:

     1. "eco_string1" and "eco_string2" are case-sensitive.

     2. "ecoList" can be used to check the ECO output of 
        "ecoExtract".

=========================(6) ecoList ===============================

"ecoList" lists each ECO code used, the number of games, the White
score percentage, and the number of White wins, draws, and losses.

Games without a Result and/or without an ECO code are not included
in the output.

"ecoList" works with ECO codes having a maximum of 5 characters.

The user can lower the maximum characters of the ECO codes by
specifying a parameter value from 1 to 4. If an ECO code's length
exceeds the maximum, the excess is truncated. For example, if the
parameter value is "3", ECO code value "C14a" will be truncated 
to "C14".

Syntax:    ecoList filename.pgn [1|2|3|4]

Examples:  ecoList alpha.pgn

           ecoList alpha.pgn 3

Output:    outEco 

Comments:

     1. Use "cleanUp" to remove games without a result ("*").

=========================(7) ecoPlayer =============================

"ecoPlayer" produces a list based on a user-specified player. For
each color and for each ECO code used, it lists the number of games,
the score percentage, and the number of wins, draws, and losses.

Matches between the user-specified player's name and names in the 
"pgn" file are not case-sensitive. For example, if the user-specified
player name is "karpov, anatoly", it will match "KARPOV, Anatoly" in
the "pgn" file.

Games without a Result and/or an ECO code are not included in the
output.

"ecoPlayer" works with ECO codes having a maximum of 5 characters.

The user can lower the maximum characters of the ECO codes by
specifying a parameter value from 1 to 4. If an ECO code's length
exceeds the maximum, the excess is truncated. For example, if the
parameter value is "3", ECO code value "C14a" will be truncated 
to "C14".

Syntax:    ecoPlayer filename.pgn player_name [1|2|3|4]

Examples:  ecoPlayer alpha.pgn "Burn, Amos"

           ecoPlayer alpha.pgn "Burn, Amos" 3

Output:    outEP

Comments:

     1. Name matches are not case-sensitive.
        
     2. If the "player_name" parameter value contains an embedded
        space, then it must be enclosed in quotation marks.

     3. Use "cleanUp" to remove games without a result ("*").

=========================(8) ecoSplit ==============================

"ecoSplit" separates the input file into six files based on the first
character of the ECO code. There is an output file for "A", "B", "C", 
"D", "E" and "no ECO".

"ecoA.pgn" contains games with an ECO code starting with "A",
"ecoB.pgn" contains games with an ECO code starting with "B",
"ecoC.pgn" contains games with an ECO code starting with "C",
"ecoD.pgn" contains games with an ECO code starting with "D",
"ecoE.pgn" contains games with an ECO code starting with "E",
"ecoN.pgn" contains games with no ECO code,

Games remain in their original order and are not sorted.

Syntax:   ecoSplit filename.pgn 

Example:  ecoSplit alpha.pgn 

Output:   ecoA.pgn, ecoB.pgn, ecoC.pgn, ecoD.pgn, ecoE.pgn, ecoN.pgn

=========================(9) eloCheck ==============================

"eloCheck" removes games that are missing either the "WhiteElo" or 
"BlackElo" tag or both. The resulting output file can be used for
Elo computations without concern for distortions caused by missing
Elo tags.

The removed games are placed in "excludeW.pgn". The user has the
option to insert the missing Elo tags and then put the edited games 
into "outW.pgn".

Before using "eloCheck", the user can see if any Elo tags are 
missing by using "summary".

After using "eloCheck", the output file "outW.pgn" is suitable for
use with "eloGap" and "eloList" and any other tool that does
Elo computations.

Syntax:   eloCheck filename.pgn 

Example:  eloCheck alpha.pgn 

Output:   outW.pgn, excludeW.pgn

=========================(10) eloExtend ============================

"eloExtend" inserts missing Elo tags for players who already have at 
least one Elo tag. "eloExtend" inserts the average of 
the existing Elo tags. Existing Elo tags are not overwritten.

"outS.pgn" contains the output games. "manifest-s" lists the Elo 
tags that were inserted.

Syntax:  eloExtend filename.pgn

Usage:   eloExtend alpha.pgn

Output:  out8.pgn, manifest-8

Comments:

     1. The inserted Elo values are rounded to the nearest whole 
        number.

     2. Another tool for inserting missing Elo tags is "eloInsert".
     
=========================(11) eloGap ==============================

"eloGap" extracts games in which the players' Elo gap (absolute value 
of Elo difference) is less than or equal to a user-specified maximum 
gap.

For example:
    
      eloGap alpha.pgn 100
  
extracts all games in alpha.pgn with an Elo gap from 0 to 100.  

The output file is "outF.pgn". Games not extracted to "outF.pgn" 
are sent to "excludeF.pgn".

"eloGap" does not extract games missing an Elo rating. Use 
"eloCheck" to remove games with a missing Elo rating.

Syntax:   eloGap filename.pgn elo_distance

Example:  eloGap alpha.pgn 100

Output:   outF.pgn, excludeF.pgn

Comments:

     1. Use "summary" to see if any Elo ratings are missing.
         
=========================(12) eloInsert ============================

"eloInsert" inserts Elo tags with user-specified Elo ratings for 
user-specified players. Existing Elo tags are overwritten.

The user creates a text file named "elovals" that contains the 
player names and Elo values on successive lines. 

name1
Elo for name1
name2
Elo for name2
name3
Elo for name3

"eloInsert" name matches are not case-sensitive. For example, 
"Acs, Peter" in "elovals" will match "ACS, peter" in the "pgn" file.

If the same player name occurs more than once, only the last Elo
rating is used.

"elovals" must be located in the Working Folder and cannot be 
referenced using a pathname.

Syntax:    eloInsert elovals filename.pgn

Example:   eloInsert elovals alpha.pgn

Output:    outI.pgn

Comments:
      
     1. The filename "elovals" is case-sensitive.
     
     2. Name matches are not case-sensitive.
     
     3. A "name" must be on an odd-numbered line in "elovals", 
        and an Elo value must be on an even-numbered line. There 
        must not be any blank lines at the start or in the middle
        of "elovals".

     4. Player names do not have to be in order.

     5. Quotation marks must not be used in "elovals".

=========================(13) eloList ================================

"eloList" lists player names, number of games, average Elo, minimum Elo, 
maximum Elo, opponents' average Elo and player performance Elo.

Three output files: 

"outElo" is sorted by player name 
"outElo2" is sorted by player Average Elo
"outElo3" is sorted by player Performance Elo

The column abbreviations in the output files:

"Elo" represents the average player Elo rating in the input file.
"Max" represents the maximum player Elo rating in the input file.
"Min" represents the minimum player Elo rating in the input file.
"Opp" represents the opponents' average Elo rating in the input file.
"Perf" represents the player performance Elo rating in the input file.

"eloList" is intended for use with "pgn" input files that have both 
Elo tags present for every game. If any Elo tags are missing then 
computation results may be unreliable. Using "summary" will show 
if any Elo tags are missing. And using "eloCheck" will remove games 
with a missing Elo tag.

The "Performance Elo" rating is an ESTIMATE of the player's Elo rating 
for his performance IN THE INPUT FILE. The computation of "Performance 
Elo" is based on the player's results, his Elo ratings and his 
opponents' Elo ratings, IN THE INPUT FILE. 

Comparing a player's "Performance Elo" rating to the player's "Average 
Elo" rating, will give an "opinion" as to whether or not the player 
performed as expected.

Syntax:   eloList filename.pgn

Example:  eloList alpha.pgn

Output:   outElo, outElo2, outElo3

Comments:

     1. Use "summary" to see if any Elo ratings are missing.
     
     2. use "eloCheck" to remove games with missing Elo tags.

=========================(14) eloRemove =============================

"eloRemove" removes all "WhiteElo" and "BlackElo" tags.

"eloRemove" removes both "WhiteElo" and "BlackElo" tags. It cannot
remove just one of them.

Use "EloStat" with "emStat", or "BayesElo" with "emBayes", or 
"Ordo" with "emOrdo", to compute and insert new Elo tags.

Syntax:   eloRemove filename.pgn

Example:  eloRemove alpha.pgn

Output:   out5.pgn

=========================(15) emBayes ==============================

"emBayes" uses Elo ratings from "BayesElo" (version 0056) by Remi 
Coulom to insert new Elo tags. The user has the option to keep 
existing Elo tags.

In default mode, "emBayes" overwrites existing Elo tag data values.

With the optional parameter "keep", existing Elo tag data values 
are not changed.

The user must use the filename "bayes.dat" for the output file 
from "BayesElo" because "emBayes" requires it.

Here is a sample sequence of commands for using "BayesElo":

    BayesElo
    readpgn alpha.pgn
    elo
    mm
    exactdist
    offset 2500
    ratings >bayes.dat
    x
    x

Note that there is NO space between ">" and "bayes.dat". 

The "offset" value (2500) is the starting Elo value and also the 
average of each player's Elo value weighted by games played.

"bayes.dat" must be located in the Working Folder and cannot be 
referenced using a pathname.  

Syntax:    emBayes bayes.dat filename.pgn [keep]

Examples:  emBayes bayes.dat alpha.pgn

           emBayes bayes.dat alpha.pgn keep        

Output:    outB.pgn

Comments:

     1. A player with multiple name variations should have the 
        variations consolidated before using "BayesElo". See 
        "nameList", "nameSimilar" and "nameChange".

     2. This version of "emBayes" is for use with "BayesElo 0056". 
        Updates or variants of "BayesElo" might not work properly
        with "emBayes".

=========================(16) emOrdo ===============================

"emOrdo" uses rounded Elo ratings from "Ordo 1.0" by Miguel 
Ballicora to insert new Elo tags. The user has the option to keep 
existing Elo tags.

"Ordo 1.0" produces Elo ratings to one decimal place. "emOrdo" 
rounds those Elo values to the nearest integer to conform with 
"PGN Standards".

In default mode, "emOrdo" overwrites existing Elo tag data values.

With the optional parameter "keep", existing Elo tag data values are 
not changed.

The user must use the filename "rating.txt" for the output file from 
"Ordo 1.0" because "emOrdo" requires it.

Here is a sample command for using "Ordo 1.0":

  Ordo -a 2500 -o rating.txt -p alpha.pgn
  
The "-a" value (2500) is the starting Elo value and also the average 
of each player's Elo value WITHOUT weighting for games played.
  
"rating.txt" must be located in the Working Folder and cannot be 
referenced using a pathname.

Syntax:    emOrdo rating.txt filename.pgn [keep]

Examples:  emOrdo rating.txt alpha.pgn

           emOrdo rating.txt alpha.pgn keep

Output:    outD.pgn

Comments:

     1. A player with multiple name variations should have the 
        variations consolidated before using "Ordo 1.0". See 
        "nameList", "nameSimilar" and "nameChange".

     2. This version of "emOrdo" is for use with "Ordo 1.0". 
        Updates or variants of "Ordo" might not work properly
        with "emOrdo".
        
     3. "emOrdo" can produce "emStat" type output.
        
          Ordo -a 2500 -E -G -p alpha.pgn
          
        Then use the output file "rating.dat" with "emStat":
        
          emStat rating.dat alpha.pgn

=========================(17) emStat ===============================

"emStat" uses Elo ratings from "EloStat 1.3" by Frank Schubert to
insert new Elo tags. The user has the option to keep existing Elo 
tags.

In default mode, "emStat" overwrites existing Elo tag data values.

With the optional parameter "keep", existing Elo tag data values 
are not changed.

"emStat" requires the data file "rating.dat" produced by 
"EloStat 1.3".

Here is a sample sequence of commands for using "EloStat 1.3":

    EloStat
    1
    alpha
    2500
    0

Note that when you enter the name of the "pgn" file (alpha.pgn), you
do not enter the "pgn" extension.

The "Start Elo" value (2500) is the starting Elo value and also the 
average of each player's Elo value weighted by games played.

"rating.dat" must be located in the Working Folder and cannot be 
referenced using a pathname.

Syntax:    emStat rating.dat filename.pgn [keep]

Examples:  emStat rating.dat alpha.pgn

           emStat rating.dat alpha.pgn keep

Output:    outE.pgn

Comments:

     1. When using "EloStat 1.3" set "Minimum number of games" to 
        "0" so that "rating.dat" will contain Elo ratings for all 
        players.

     2. A "pgn" data file for "EloStat 1.3" is limited to 1500
        player names. Above that, "EloStat 1.3" will exit.

     3. A player name in a "pgn" data file for "EloStat 1.3" is
        limited to 39 characters. Above that, the name is discarded.

     4. A player with multiple name variations should have the 
        variations consolidated before using "EloStat 1.3". See 
        "nameList", "nameSimilar" and "nameChange".

     5. This version of "emStat" is for use with "EloStat 1.3". 
        Updates or variants of "EloStat" might not work properly 
        with "emStat".

=========================(18) fenRemove ============================

"fenRemove" removes games containing a "FEN" tag except when the 
"FEN" position is the standard opening position.

The output file is "out6.pgn". Removed games are in "exclude6.pgn".

The "FEN" of the standard opening position:

  rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1

Use "tagFix" to remove "FEN" & "SetUp" tags for the standard opening
position.

Syntax:   fenRemove filename.pgn 

Example:  fenRemove alpha.pgn

Output:   out6.pgn, exclude6.pgn

Comments:

     1. "fenRemove" removes almost all "Chess960" ("Fischer Random 
        Chess") games. The only games it does not remove are the
        games where the "FEN" position is the standard opening 
        position, a 1 out of 960 possibility.

=========================(19) gameMerge ================================

"gameMerge" joins 2, 3, 4, or 5 "pgn" files by inserting one game from 
each successive input file, and then repeating until all games have 
been inserted. 

Example: Suppose fileA.pgn has 3 games, fileB.pgn has 2 games and 
fileC.pgn has 4 games. 

  gameMerge fileA.pgn fileB.pgn fileC.pgn

  The output file "outMR.pgn" will consist of:

  game1 from fileA.pgn followed by
  game1 from fileB.pgn followed by
  game1 from fileC.pgn followed by
  game2 from fileA.pgn followed by
  game2 from fileB.pgn followed by
  game2 from fileC.pgn followed by
  game3 from fileA.pgn followed by
  game3 from fileC.pgn followed by
  game4 from fileC.pgn

Syntax:    gameMerge file1.pgn file2.pgn [file3.pgn file4.pgn file5.pgn]

Examples:  gameMerge alpha.pgn beta.pgn
           gameMerge alpha.pgn beta.pgn gamma.pgn
           gameMerge alpha.pgn beta.pgn gamma.pgn delta.pgn
           gameMerge alpha.pgn beta.pgn gamma.pgn delta.pgn epsilon.pgn

Output:    outMR.pgn

Comments:

     1. Do not confuse merging files with concatenation. Concatenation 
        joins files together by linking them together in a series.

     2. In "Windows", to concatenate multiple files into one file, use
        the "copy" or "xcopy" command in the command line.

=========================(20) gameNum.exe ==========================

"gameNum" inserts consecutive "game number" comments between the 
"Tag Section" and the "MoveText Section".

The default starting game number is "1". The user can select another
starting number.

A sample inserted comment: {game 4783}

Syntax:    gameNum filename.pgn [start_num]

Examples:  gameNum alpha.pgn

           gameNum alpha.pgn 101

Output:    out4.pgn

Comments:

     1. Game number comments can be removed using "trim". However,
        "trim" will also remove all other comments.      

=========================(21) gameSplit =============================

"gameSplit" separates the "pgn" data file into a user-specified 
number (2-10000) of files. All games are kept intact within one 
of the output files. The number of games in each output file are 
"equal", plus or minus 1 game.

For example, if the "pgn" data file has 98 games and the user runs
"gameSplit" to split the data into 6 files, then the output files 
will contain:  17, 17, 16, 16, 16, and 16 games respectively.

The output files can be used to reconstruct the "pgn" data file:

      copy /b gs*.pgn beta.pgn

Syntax:   gameSplit filename.pgn split_num

Example:  gameSplit alpha.pgn 2345

Output:   gs0000.pgn, gs0002.pgn, ..., gs2344.pgn

Example:  gameSplit alpha.pgn 10000

Output:   gs0000.pgn, gs0001.pgn, ..., gs9999.pgn

Comments:

     1. Do not put a comma in the "split_num".
     
     2. If the "split_number" is equal to the number of games in
        the "pgn" file, then each output file will contain 1 game.
        
     3. Use "copy /b" to concatenate the files back to the original. 
        The "/b" option prevents the "eof" character from being 
        appended to the end of the file.

=========================(22) groupExtract =========================

"groupExtract" extracts games in which each player's name begins with 
a name_search-string located in a user-created text file named "group". 

"group" is organized in columnar format:

name1
name2
name3
name4

Sample content for "group":

Carlsen, Magnus  
Caruana, Fabiano 
Ding, Liren      
Aronian, Levon  
Nepomniachtchi, Ian   

Before creating "group", users should use "nameList" to check for 
accurate spelling and to see if any player name on the list has 
multiple spellings. 

More than one player could have a name beginning with the same
name_search-string. 

"groupExtract" matches are NOT case-sensitive. Therefore "KARPOV"
will match "Karpov".

The order of the name_search-strings does NOT matter. 

Extracted games are sent to "outG.pgn". Games not extracted are sent
to "excludeG.pgn". 

"manifest-g" lists the full names of the players in each game of 
"outG.pgn". The user should check "manifest-g" to see if any unwanted 
games were extracted.

"group" must be located in the Working Folder and CANNOT be referenced
using a pathname.

Syntax:   groupExtract group filename.pgn

Example:  groupExtract group alpha.pgn
      
Output:   outG.pgn, manifest-g, excludeG.pgn

Comments:
     
     1. The filename "group" is case-sensitive.
     
     2. A name_search-string can contain several tokens, for example:

        Stockfish 2.2.2 x64 2CPU
        
     3. A "group" name_search-string can be as small as one character.       
     
     4. "group" can contain blank lines, but that is not recommended.

     5. Do not use quote marks ("") around search-strings in "group".
       
=========================(23) listExtract ==========================

"listExtract" extracts games in which at least one of the player 
names begin with a name_search-string in a user-created text file 
named "list". 

"list" is organized in columnar format:

name1
name2
name3
name4

Sample content for "list":

Carlsen, Magnus  
Caruana, Fabiano 
Ding, Liren      
Aronian, Levon  
Nepomniachtchi, Ian   

Before creating "list", users should use "nameList" to check for 
accurate spelling and to see if any player name on the list has 
multiple spellings. 

More than one player could have a name beginning with the same
name_search-string. 

Games where the two players each have a name beginning with a 
name_search-string in "list", are output only once.

"listExtract" matches are NOT case-sensitive. Therefore "KARPOV"
will match "Karpov".

The order of the name_search-strings does NOT matter. 

Extracted games are sent to "outL.pgn". Games not extracted are sent
to "excludeL.pgn". 

"manifest-l" lists the full names of the players in each game of 
"outL.pgn". The user should check "manifest-l" to see if any unwanted 
games were extracted.

"list" must be located in the Working Folder and CANNOT be referenced
using a pathname.

Syntax:   listExtract list filename.pgn

Example:  listExtract list alpha.pgn
      
Output:   outL.pgn, manifest-l, excludeL.pgn

Comments:

     1. The filename "list" is case-sensitive.
     
     2. A name_search-string can contain several tokens, for example:

        Stockfish 2.2.2 x64 2CPU

     3. A "list" name_search-string can be as small as one character.       
        
     4. "list" can contain blank lines, but that is not recommended.   

     5. Do not use quote marks ("") around name_search-strings in 
        "list".
     
=========================(24) minDate ==============================

"minDate" extracts games that were played within an inclusive 
user-specified time span.

The output file is "outA.pgn". Games not extracted to "outA.pgn" 
are in "excludeA.pgn".

If only one date is specified, that date is considered to be the
starting date. If two dates are specified, the first date is
the starting date, and the second date is the ending date.

Games with an unknown year ("????") are not extracted.

If the month and/or day is unknown ("??"), then "01" is assumed.

Games whose date is not in the format "yyyy.mm.dd" are not extracted.

Syntax:    minDate filename.pgn starting_date [ending_date]

Examples:  minDate alpha.pgn 2004.05.01

           minDate alpha.pgn 2004.05.01 2005.12.31

Output:    outA.pgn, excludeA.pgn

Comments:

     1.  When searching a "pgn" file, "minDate" treats a "??" value
         for month or day as equivalent to "01", and a "????" value
         for year as equivalent to "0001".

=========================(25) minElo ===============================

"minElo" extracts games where the players' Elo values are in an
inclusive user-specified range or ranges.

When one range is specified, both players' Elo values must be in 
that range.

When two ranges are specified, one Elo must be in the first range, 
and the other Elo value must be in the second range.

The output file is "outM.pgn". Games not extracted to "outM.pgn" 
are in "excludeM.pgn".

Only games having TWO Elo ratings can be extracted. A missing Elo
rating in a game prevents that game from being extracted.

The user must specify 1, 2, or 4 Elo values as parameters.

If 1 Elo value is specified, a game will be extracted if both of 
its Elos are greater than or equal to the parameter value.

For example:

           minElo alpha.pgn 2500

will extract all games whose two Elos are at least 2500.

If 2 Elo values are specified as parameters, a game will be extracted
if both of its Elos values are in the inclusive range formed by the 
parameter values. 

For example:

           minElo alpha.pgn 2500 2700

will extract all games where both Elos are in the range of 2500 
to 2700, inclusive.

If 4 Elo values are specified as parameters, a game will be extracted 
if its two Elos are each in a different inclusive range formed by the 
parameter values. 

For example:

           minElo alpha.pgn 2500 2700 2400 2600

will extract all games where one Elo is in the inclusive range of
2500 to 2700, and the other Elo is in the inclusive range of 2400 
to 2600.

"0" is the minimum Elo value recognized in "minElo".

For example:

           minElo alpha.pgn 0 2000

will extract all games where both Elos are less than or equal to 2000.

"5000" is the maximum Elo value recognized in "minElo".

For example:

           minElo alpha.pgn 2500

           minElo alpha.pgn 2500 5000

will each extract all games where both Elo values are at least 2500.

Syntax:    minElo filename.pgn min_elo1 [max_elo1] [min_elo2 max_elo2]

Examples:  minElo alpha.pgn 2400

           minElo alpha.pgn 2400 2600

           minElo alpha.pgn 2400 2600 2500 2700

Output:    outM.pgn, excludeM.pgn

Comments: 

     1. When specifying an Elo range, the first Elo should not be
        larger than the second Elo. If it is, no games will be
        extracted.

     2. To extract games where only ONE player's Elo rating must be 
        in a specified Elo range, use "0 5000" as the other Elo 
        range:

           minElo alpha.pgn 2500 2600 0 5000

     3. When using 2 Elo ranges, the order of the ranges is
        not important:

           minElo alpha 2300 2400 2600 2700 

        will produce the same output as

           minElo alpha 2600 2700 2300 2400

=========================(26) minOccur =============================

"minOccur" extracts games of players who meet or exceed a user-
specified minimum number of games in the input file.

The output file is "outO.pgn". Games not extracted to "outO.pgn" are 
in "excludeO.pgn".

Also produced are lists "beforeList" and "afterList". They list the
names of players and the number of games, both before and after
running "minOccur".

Some players who meet or exceed the minimum number of games in the
input file may not meet or exceed the same minimum number of games 
in the output file. This occurs if some of their opponents were
removed because THEY did not meet or exceed the minimum number of 
games in the input file. Because of this situation, you should run 
"minOccur" again and again (after renaming "outO.pgn") until you 
reach an execution of "minOccur" where no players are removed.

Syntax:   minOccur filename.pgn minimum_games

Example:  minOccur alpha.pgn 100

Output:   outO.pgn, beforeList, afterList, excludeO.pgn

Comments:

     1. Sometimes you have to rerun "minOccur" several times in 
        order for ALL remaining players to meet or exceed the 
        minimum number of games. Rename "outO.pgn" before each 
        execution of "minOccur".

=========================(27) minPly ===============================

"minPly" extracts games in which the number of plies (half-moves) is
within an inclusive user-specified range. "minPly" uses the value in 
the "PlyCount" tag to obtain the number of plies in a game.

If there are missing "PlyCount" tags, use "plyCount" before "minPly".
It will insert any missing "PlyCount" tags.

Example: minPly alpha.pgn 21 30
          
outputs all games whose plycount is from 21 to 30, inclusive.

The output file is "outY.pgn". Games not extracted to "outY.pgn" are 
in "excludeY.pgn".

Syntax:   minPly filename.pgn minimum_plies [maximum_plies]

Example:  minPly alpha.pgn 61

          minPly alpha.pgn 61 100

Output:   outY.pgn, excludeY.pgn

Comments:

     1. "minPly" does not extract games that do not have a "PlyCount"
         tag. Use "plyCount" prior to "minPly" to insert missing 
         "PlyCount" tags.

     2. To remove games with 0, 1, or 2 plies, use the command-line:

          minPly alpha.pgn 3

=========================(28) nameChange ===========================

"nameChange" performs user-specified player name changes based on a
user-created text file named "changes".

"nameChange" can be used to consolidate variations of a player's name
into one form.

"outC.pgn" contains the output games with the name changes.
"manifest-c" lists all the name changes. It is very important to check
"manifest-c" that the names were changed as planned.

Create the text file "changes" in columnar form as follows:

name1 to be changed
replacement name1
name2 to be changed
replacement name2
name3 to be changed
replacement name3

There must not be any blank lines at the start or in the middle of 
the "changes" file.

The same "name to be changed" should not occur more than once.
However, if he does, only the last "replacement name" is used.

If the same "name to be changed" occurs more than once, only the 
last "replacement name" is used.

The same "replacement name" can appear more than once.

"changes" must be located in the Working Folder and cannot be 
referenced using a pathname.

"tagFix" will change the name tag values if there is a structural
issue with the tag. It is a good idea to use "tagFix" before using
"nameChange".

Syntax:   nameChange changes filename.pgn

Example:  nameChange changes alpha.pgn

Output:   outC.pgn, manifest-c

Comments:

     1. The filename "changes" is case-sensitive.

     2. "name to be changed" and "replacement name" in "changes" are 
        case-sensitive.
        
     3. A "name to be changed" must be on an odd-numbered line, and
        a "replacement name" must be on an even-numbered line. There
        must not be any blank lines at the start or in the middle of 
        "changes".

     4. Player names do not have to be in order.

     5. Quotation marks must not be used in "changes".

     6. After using "nameChange", the user should scan "manifest-c"
        to check that the changes went as planned.        

=========================(29) nameColor ============================

"nameColor" adds a token, "(wh)" or "(bl)", to each player's name 
depending on the color being played. For example, "Karpov, A. (wh)" 
and "Karpov, A. (bl)".

Using the color tokens makes it easier to create lists and do
calculations based on the color played.

"colorList" lists player results for White and Black.

Syntax:   nameColor filename.pgn 

Example:  nameColor alpha.pgn

Output:   outK.pgn

Comments:

     1. " (wh)" and " (bl)" can be removed using "find and replace" 
        in a text editor.

     2. "playerExtract" will extract a player's games by color.

=========================(30) nameExtract ==========================

"nameExtract" extracts games in which at least one player's name 
begins with a user-specified name_search-string. 

The name_search-string must match the beginning of the player's name 
including any embedded spaces and punctuation. However, the match does 
NOT have to be case-sensitive. For example, the search string "FiScH"
will match "Fischer, Robert", "Fischer, R." and "FISCHER, Robert J.".

Use "nameList" before using "nameExtract" to check the spelling of 
player names. 

More than one player could have a name beginning with the same
name_search-string. Games between such players are output only once.

The name_search-string must be within quotation marks if it contains
an embedded space. 

The output file is "outN.pgn". Games not output to "outN.pgn" are
output to "excludeN.pgn".

"manifest-n" lists the full names of the players in each game of 
"outN.pgn". The user should check "manifest-n" to see if any 
unwanted games were extracted.

"nameExtract" is similar to "listExtract". "listExtract" does the
same type of search but uses a text file containing one or more
user-specified name_search-strings.

Syntax:   nameExtract filename.pgn name_search-string

Example:  nameExtract alpha.pgn Stockfish

Output:   outN.pgn, manifest-n, excludeN.pgn

Comments:

     1. Matches between "name_search-string" and the beginnings of 
        the names in the "pgn" file are not case-sensitive.
        
     2. "name_search-string" must be enclosed within quotation marks 
        if it has an embedded space. 
            
     3. "nameExtract" is useful for extracting all versions of 
        a user-specified chess engine. For example, if the
        name_search-string is "Stockfish", then games of all
        versions of "Stockfish" would be extracted.            
                   
     4. "nameExtract" extracts the games of multiple players whose
        names have the same beginning. Use "playerExtract" to extract
        the games of just one specific player.

=========================(31) nameList =============================

"nameList" lists player names and games played in three different 
output files. It also has the option to output names in "all caps".

The first output file "outName", lists the names in sorted order,
without any headings and the number of games played.

The second output file "outName2", lists the players' names, number 
of games played, the beginning and ending dates of the players' 
games, and is sorted by names.

The third output file "outName3", lists the same data in "outName2",
but sorted by the number of games in descending order.

The value "01" is used for missing months or days in the Date value,
provided there is a valid year present. If a player does not have at 
least one game with a valid year, then its beginning and ending dates 
are "????.??.??". These games can be removed using the "40H" tool 
"cleanUp".

The optional parameter "CAP" outputs all names in uppercase. This is
useful in clearing up multiple spellings due to case differences. If 
the number of names with CAPS is less than without CAPS, then there 
is a duplicate name due to a case difference.

Syntax:   nameList filename.pgn [CAP]

Example:  nameList alpha.pgn

          nameList alpha.pgn CAP

Output:   outName, outName2, outName3

Comments:

     1. "CAP" is case-sensitive.
     
     2. "nameList" and "nameSimilar" can be used to find spelling 
        variations of a player name. "nameChange" can be used to 
        consolidate the spelling to one variation.
       
=========================(32) nameSimilar ==========================

"nameSimilar" lists groups of player names where each group's names
start with the same token or the same three characters. The number 
of games for each player is listed.

"nameSimilar" is useful in finding name variations of the same 
player. For example, "Karpov, Anatoly" and "Karpov, A.", or 
"Kasparov, Garry" and "Kasparov, Gary", or "Korchnoi, Viktor" and
"Kortchnoj, V."

Sometimes a player's multiple names will have a capitalization
difference and would not be found by "nameSimilar". For example,
"Fritz" and "FRITZ". In this case, the "CAP" option of "nameList"
may be helpful.

Sometimes a player's multiple names will have a major spelling 
difference and would not be found by "nameSimilar". For example, 
"Yusupov, Artur" and "Jussupow, Artur". In this case, the player
chose to change his name.

Use "nameChange" to change the spelling of a player's name.
 
Syntax:   nameSimilar filename.pgn

Example:  nameSimilar alpha.pgn

Output:   outSimilar

=========================(33) numExtract ===========================

"numExtract" extracts games whose game number matches a game number
in a user-specified text file "numbers".

The output file is "outZ.pgn". Games not extracted to "outZ.pgn" are 
in "excludeZ.pgn".

The output file "excludeZ.pgn" would be the desired output file if 
the user wanted to remove the games whose numbers are in "numbers",
from the input file.

The user has to create a text file named "numbers" containing the 
game numbers of the games to be extracted. One number per line.
For example:

93
164
72
106

Games will be output in their original order even if the game
numbers are not in numerical order. For example, in the above
example, the games will be output as follows:

game 72
game 93
game 106
game 164

Duplicate numbers are ignored. Blank lines are ignored.

"numbers" must be located in the Working Folder and cannot be 
referenced using a pathname.

Syntax:   numExtract numbers filename.pgn

Example:  numExtract numbers alpha.pgn

Output:   outZ.pgn, excludeZ.pgn

=========================(34) pairExtract ==========================

"pairExtract" extracts games in which each player's name begins with 
a different name_search-string from the same pair in a user-created 
text file named "pairs". 

For each name_search-string, more than one player could have a name 
starting with that search-string. 

The output file is "outP.pgn". Games not extracted to "outP.pgn" are 
in "excludeP.pgn".

"manifest-p" lists the full names of the players of each game in 
"outP.pgn". The user should check "manifest-p" to see if any unwanted 
games were extracted.

Use "nameList" before using "pairExtract" to check the spelling of 
player names. 

To use "pairExtract", the user has to first create a text file named
"pairs". This file will contain successive pairs of name_search-
strings.

"pairs" is organized in columnar format:

name1 of pair1
name2 of pair1
name1 of pair2
name2 of pair2

"pairs" should not contain any blank lines.

"pairs" must have an even number of data lines.

The order of names within a pair does not matter.

Sample content of a "pairs" file:

Kasparov
Karpov
Topalov
Kramnik

In the above example, all games between players (regardless of color
arrangement) whose names start with "Kasparov" and "Karpov", or
"Topalov" and "Kramnik", will be extracted to "outP.pgn". The two
player names have to match different search-strings. 

"pairExtract" matches are not case-sensitive. Therefore the pair:

kASPARov
KARpov

will get the same matches as the pair:

Kasparov
Karpov

"pairExtract" is useful for removing intra-family games between 
computer engines. Intra-family games are games between versions of
the same engine or its derivatives. For example, the following pairs 
will extract intra-family games between Stockfish versions and 
intra-family games between Komodo versions:

Stockfish
Stockfish
Komodo
Komodo

In this case "excludeP.pgn" would be the useful output file because 
it will NOT contain the intra-family games.

"pairs" must be located in the Working Folder and cannot be referenced
using a pathname.

Syntax:   pairExtract pairs filename.pgn

Example:  pairExtract pairs alpha.pgn
      
Output:   outP.pgn, manifest-p, excludeP.pgn

Comments:

     1. The filename "pairs" is case-sensitive.
     
     2. Matches between names in "pairs" and the beginning of the
        names in the "pgn" file are not case-sensitive.

     3. A name_search-string can contain several tokens, for example:

          "Kasparov, Garry"

     4. A "pairs" name_search-string can be as small as one character.       

     5. Quotation marks must not be used within "pairs".
            
=========================(35) pairList ===========================

"pairList" double lists each player pairing. The order of players 
is reversed in the second pairing. Results are included. The pairings 
are sorted by player names. 

Each pairing lists the results between the two players. There are two 
listings for each pairing so that the user can find the pairing using 
either player's name first.

Color played is ignored. If you wish to see the results by color 
played, use "nameColor" before using "pairList".

Results are read from the point of view of the first player listed. 
For example:

Smyslov, Vasily : Spassky, Boris V.    11  :  2+ :  5= :  4- :  40.91%

In this example, Smyslov is listed first. "11" is the number of games 
played. "2+" indicates that Smyslov won "2" games. "5=" indicates "5" 
draws. "4-" indicates that Smyslov lost "4" games. "40.91%" is 
Smyslov's score percentage.

The second listing of the above pairing is:

Spassky, Boris V. : Smyslov, Vasily    11  :  4+ :  5= :  2- :  59.09%

Syntax:   pairList filename.pgn 

Example:  pairList alpha.pgn

Output:   outPairs

Comment:
      
     1. "pairList" can be used as a replacement for a crosstable if
        the number of players is large.
        
     2. "clusterList" lists the number of distinct opponents for 
        each player.
        
=========================(36) pairSplit ============================

"pairSplit" extracts the games of each player pair into their own 
file. Only the first 1000 player pairs (in sorted order) are processed
at each "pairSplit" execution. The remaining games are collected into 
an "exclude" file which can be processed at a later time.

The games of the player pairs are put into the files "box000.pgn",
"box001.pgn", ... , "box999.pgn", assuming there are at least 1000 
player pairs. If less than 1000 player pairs, the number of files 
equals the number of pairs. If there are more than 1000 player
pairs, then the leftover games are extracted to "excludeBox.pgn".

The output file "manifest-box" lists each player pairing (in sorted
order) with the file containing its games. The number of games of each
player pairing is also listed.

The games in "excludeBox.pgn" can be processed by "pairSplit" but only 
after renaming "excludeBox.pgn". Also, the previous output files in 
the working folder must be renamed/copied/moved or the next execution 
of "pairSplit" will overwrite them.

One execution of "pairSplit" is sufficient to create a file for each
player pairing in a 45-player round-robin tournament (990 files). 

Syntax:   pairSplit filename.pgn

Example:  pairSplit alpha.pgn

Output:   box000.pgn --> box999.pgn, excludeBox.pgn, manifest-box

Comments:

     1. "pairList" can tell you how many player pairs are in the 
        data file so you can determine in advance how many executions 
        of "pairSplit" will be needed.

=========================(37) pgn2stream ===========================

"pgn2stream" converts a "pgn" file into a "move steam" file.
A "move stream" is a full chess game condensed to a single line.
It consists of the moves and the result, and optionally, the
move numbers.

Examples (shortened):

1. h3 e5 2. c4 Nc6 3. e3 Nf6 4. a3 d5 5. cxd5 Nxd5 6. Qc2 a6 7. Nf3 Be6 1/2-1/2 
a3 d5 e3 c5 Bb5+ Bd7 Bxd7+ Nxd7 f4 e6 Nf3 Bd6 O-O 1-0 

"outStream" is the output file containing move numbers.

"outStream2" is the output file without move numbers.

"pgn2stream" does NOT convert games with a "FEN" tag to a "move 
stream". Instead, a blank line is output. That maintains the 
relationship between the game number and the line number. The user 
can remove all "FEN" games before using "pgn2stream" by using 
"fenRemove" on the input file.

"pgn2stream" removes comments, nags, variations, and major symbolic
annotation symbols (!, !!, ?, ??, !?, ?!, +-, -+, +/-, -/+, +=,
=+, +/=, =/+, =, ~, and N), if present.

Using "gameNum" on the input file before using "pgn2stream" will 
help coordinate the game number and the line number in the "move 
stream" file.

Syntax:   pgn2stream filename.pgn 

Example:  pgn2stream alpha.pgn

Output:   outStream, outStream2

Comment:

     1. "stream2pgn" converts a "move stream" file to a "pgn" file. 
        Using "pgn2stream" after using "stream2pgn", will insert 
        move numbers into the original input (if any were missing).
     
=========================(38) playerExtract ==========================

"playerExtract" extracts the games of a user-specified player. It also 
outputs the player's games by color and result.

The name_search-string must match the player's name exactly including
any embedded spaces and punctuation. However, the match does NOT have 
to be case-sensitive. For example, the search string "stockfish 12" 
will match "StockFish 12". 

The name_search-string must be within quotation marks if it contains
an embedded space. 

The player's games are output to "outPlayer.pgn". Games not output
to "outPlayer.pgn" are output to "excludePlayer.pgn". 

The output file "excludePlayer.pgn" would be the desired output file 
if the user wanted to remove the games of the user-specified player 
from the input file.

The player's games as White and Black are extracted to "outWhite.pgn" 
and "outBlack.pgn" respectively.

The player's wins, draws and losses are extracted to "outWin.pgn", 
"outDraw.pgn" and "outLose.pgn" respectively. The player's games 
without a result are extracted to "outNoRes.pgn".

Use "nameList" before using "playerExtract" to check the spelling 
of the players' names. 

Self-play games will cause some sort of output error based on color 
or the result. Those games will be output only once to 
"outPlayer.pgn". Use "cleanUp" to remove self-play games (and games 
without a result) before using "playerExtract". 

Syntax:   playerExtract filename.pgn name_search-string

Example:  playerExtract alpha.pgn "Karpov, Anatoly"

Output:   outPlayer.pgn, outWhite.pgn, outBlack.pgn, outWin.pgn, 
          outDraw.pgn, outLose.pgn, outNoRes.pgn, excludePlayer.pgn
           
Comments:

     1. "playerExtract" matches between the name in 
        "name_search-string" and the names in the "pgn" file are not 
        case-sensitive.

     2. "name_search-string" must be enclosed within quotation marks 
        if it has an embedded space. 
           
     3. "playerExtract" extracts the games of one specific player. 
        Use "nameExtract" to extract the games of multiple players 
        whose names have the same starting characters.
     
=========================(39) plyCount =============================

"plyCount" counts the number of plies (half-moves) of each game and
inserts a new "PlyCount" tag if one is missing. Existing "PlyCount"
tags are unchanged. 

"plyCount" also produces "outPlies" which is a listing of plycounts 
and the number of occurrences.

"plyCount" only counts those plies that are physically present in 
the "MoveText Section". Moves embedded in the "FEN" position are not 
counted.

"plyCount" removes "en passant" indicators "ep", "e.p." and "/ep", 
if present, to prevent them from adding to the ply count.

Syntax:   plyCount filename.pgn

Example:  plyCount alpha.pgn

Example:  PGN-Extract -s -w80 -obeta.pgn alpha.pgn
          plyCount beta.pgn

Output:   outX.pgn, outPlies

Comment:

     1. On occasion, plyCount, trim and truncate have an early exit
        output problem with a very large "pgn" file. See section
        "Handling Output Issues" above.
                       
=========================(40) resultList ===========================

"resultList" lists player names, number of games, number of wins, 
draws, losses, score percentages, result points, and S-B tie-break 
points.

Games without a Result ("*") are ignored in the output.

The output file "outRes" contains player names, the number of games, 
the number of wins, draws, losses, and score percentages. It is 
sorted by player name. 

The output file "outRes2" contains the same data as "outRes" but is 
sorted by descending score percentage.

The output file "outRes3" contains player names, the number of games, 
the number of wins, draws, losses, result points, S-B points, and 
score percentages. 

"outRes3" is sorted by descending result points, and secondly by 
decreasing S-B (Sonneborn-Berger) tie-break points.

"outRes3" is intended for use with "Round-Robin" or "Swiss System"
tournaments where a "result table" is desired. "outRes3" contains
all information that is normally associated with a "result table"
except for results between each pair of players. Use the "40H-PGN" 
tool "pairList" to see the results between each pair of players.

Although many round-robin tournaments use "S-B" as one of their 
tie-breakers. many others do not.

Syntax:   resultList filename.pgn

Example:  resultList alpha.pgn

Output:   outRes, outRes2, outRes3

Comments:

     1. "cleanUp" will remove games without a result ("*").
     
=========================(41) resultSplit ==========================

"resultSplit" separates the "pgn" data file into four files based on 
the results of the games. There is an output file for "White Wins",
"Draws", "Black Wins", and "no result".

"resW.pgn" contains games that White won.
"resD.pgn" contains games that ended in a draw.
"resB.pgn" contains games that Black won.
"resN.pgn" contains games without a Result.

Syntax:   resultSplit filename.pgn 

Example:  resultSplit alpha.pgn 

Output:   resW.pgn, resD.pgn, resB.pgn, resN.pgn 

Comments:

     1. Use "cleanUp" to remove games without a result ("*").

     2. "resultSplit" extracts all the "no result" games in the 
        input file, while"playerExtract" extracts the "no result" 
        games of a specified player.    

=========================(42) stream2pgn ===========================

"stream2pgn" converts a "move stream" file into a "pgn" file. 
A "move stream" is a full chess game condensed to a single line.
It consists of the moves and the result, and optionally, the
move numbers.

"steam2pgn" can also convert a modified "move stream" that is missing
the move numbers and/or the result.

Examples (shortened):
 
a3 f5 e3 Nf6 f4 e6 Nf3 b6 Be2 Bb7 O-O Be7 d3 O-O Ne5 d6 Bf3 c6 Nc4 1-0
h3 e5 c4 Nc6 Nc3 g6 Nf3 Bg7 g3 Nge7 d3 d5 cxd5 Nxd5 Bd2 Be6 Bg2 O-O  
1. a3 f5 2. e3 Nf6 3. f4 e6 4. Nf3 b6 5. Be2 Bb7 6. O-O Be7 7. d3 O-O 8. Ne5 d6 9. Bf3 c6 10. Nc4 1-0
1. h3 e5 2. c4 Nc6 3. Nc3 g6 4. Nf3 Bg7 5. g3 Nge7 6. d3 d5 7. cxd5 Nxd5 8. Bd2 Be6 9. Bg2 O-O  

outputs:

[Event "?"]
[Site "?"]
[Date "????.??.??"]
[Round "1"]
[White "?"]
[Black "?"]
[Result "1-0"]

1. a3 f5 2. e3 Nf6 3. f4 e6 4. Nf3 b6 5. Be2 Bb7 6. O-O Be7 
7. d3 O-O 8. Ne5 d6 9. Bf3 c6 10. Nc4 1-0

[Event "?"]
[Site "?"]
[Date "????.??.??"]
[Round "2"]
[White "?"]
[Black "?"]
[Result "*"]

1. h3 e5 2. c4 Nc6 3. Nc3 g6 4. Nf3 Bg7 5. g3 Nge7 6. d3 d5 
7. cxd5 Nxd5 8. Bd2 Be6 9. Bg2 O-O *

[Event "?"]
[Site "?"]
[Date "????.??.??"]
[Round "3"]
[White "?"]
[Black "?"]
[Result "1-0"]

1. a3 f5 2. e3 Nf6 3. f4 e6 4. Nf3 b6 5. Be2 Bb7 6. O-O Be7 
7. d3 O-O 8. Ne5 d6 9. Bf3 c6 10. Nc4 1-0

[Event "?"]
[Site "?"]
[Date "????.??.??"]
[Round "4"]
[White "?"]
[Black "?"]
[Result "*"]

1. h3 e5 2. c4 Nc6 3. Nc3 g6 4. Nf3 Bg7 5. g3 Nge7 6. d3 d5 
7. cxd5 Nxd5 8. Bd2 Be6 9. Bg2 O-O *

"stream2pgn" ignores blank lines in the input file.

"stream2pgn" will not work properly if there are Tags before the 
move stream. Use "trim" instead.

The "Round" tag value in "outST.pgn" is the line number of the "move
stream" in the input file, assuming no blank lines. 

Using "gameNum" on the output file "outST.pgn" will help coordinate 
the game number and line number in the "move stream" file, assuming 
no blank lines.

Syntax:   stream2pgn move_stream_filename 

Example:  stream2pgn gamelines

Output:   outST.pgn

Comments:
     
     1. Each "move stream" MUST be on a SINGLE line of the text file.
        Sometimes a text editor will use a soft word-wrap if the 
        single line exceeds its low character limit (1024 for example). 
        However, the "move stream" line may still be a single line in 
        the text file. In this case, use a different text editor to 
        avoid this situation.    
        
=========================(43) summary ==============================

"summary" produces statistics involving games, players, clusters, 
dates, Elo ratings, results, ECO values, and plycounts.

The Elo average and standard deviation statistics are based on the
games, not the players. For example, the average of White Elo is the
sum of the White Elo values in all the games, divided by the number
of games with a White Elo value.

The value "01" is used for missing months or days in the Date value
provided there is a valid year present. The "40H" tool "cleanUp" can
remove games without a valid year.

All Standard Deviation calculations in "summary" use the "Population" 
formula.

Plycount statistics are based on PlyCount tags. Use "plyCount" to 
insert missing "PlyCount" tags.

Syntax:    summary filename.pgn

Examples:  summary alpha.pgn

Output:    to the display, outSummary

Comments:

     1. Try using "tagFix" on the input "pgn" file if there is 
        unusual output.

=========================(44) tagCreate ============================

"tagCreate" inserts a user-specified tag type (other than "Event") 
into the Tag Section of each game. The "Event" tag must already be
present. 

The new tags are inserted at the bottom of the Tag Section of each 
game. Prior tags of that tag type are removed. The Tag Section can 
then be re-ordered using "tagOrder". 

The user-specified tag type and its value must be written on the 
first line of a text file named "newtag". Further lines are ignored.

Example of the first line in "newtag":

  [Source "Reinfeld 1001"]
  
"Source" is the tag type and "Reinfeld 1001" (with quotes) is the 
tag value.  

All tags of this type will have the same tag value. To customize 
the values use a text editor or "tagInsert".

The output file is "out9.pgn".

"tagCreate" can only insert one new tag type on each execution. 
If you want to insert another tag type, rename "out9.pgn" before 
using it as an input file to "tagCreate".

Syntax:   tagCreate newtag filename.pgn

Examples: tagCreate newtag alpha.pgn 

          tagCreate newtag alpha.pgn
          tagOrder out9.pgn

Output:   out9.pgn, out3.pgn

Comments:

     1. The filename "newtag" is case-sensitive.   
        
     2. New "Elo" tags can also be inserted using "embayes", 
        "emOrdo" or "emStat". 
        
     3. New "ECO" tags can also be inserted using "SCID vs PC" 
        or "PGN-Extract". 
        
     4. New "PlyCount" tags can also be inserted using "plyCount". 

     5. "newtag" is used instead of command line parameters 
        due to issues with embedded quotation marks.
        
=========================(45) tagExtract =========================

"tagExtract" extracts games based on a user-specified tag type and 
a user-specified search string. The search string can either be a 
single token or a complete tag value.

"tagExtract" is the only tool in "40H-PGN" tools that can extract
games based on any tag-type. It is not tag type specific.

"tagExtract", in Standard mode, extracts games where there is a 
match between a user-specified search token and a token in a tag 
value of the user-specified tag type. Some tokens may have a 
punctuation mark attached, such as a comma or a period. The match
is not case-sensitive.

"tagExtract", in Optional mode (parameter "entire"), extracts 
games where there is a match between the user-specified search 
string and a complete tag value of the user-specified tag type. 
The search string MUST be enclosed in quotation marks if it has 
an embedded space. The match is not case-sensitive.

Using "tagValue" before using "tagExtract" provides a list of all 
the tag values of a user-specified tag.
 
It is not recommended to use "tagExtract" to extract the games of 
a specific player because you would have to extract twice, once with
"White" and once with "Black". Instead, use either "playerExtract" 
or "nameExtract".

The output file is "outT.pgn". "manifest-t" lists the players in 
the games in "outT.pgn". Games not extracted to "outT.pgn" are put 
into "excludeT.pgn". 

Syntax:   tagExtract filename.pgn tag_name search_string [entire]

Examples: tagExtract alpha.pgn Event Open

          tagExtract alpha.pgn Site "New York, N.Y." entire

Output:   outT.pgn, excludeT.pgn, manifest-t

Comments:

     1. "tag_name" is "case-sensitive".
     
     2. In "Standard" mode, matches between the token in 
        "search-string" and the tokens in the "tag_name" tags are 
        not case-sensitive. 
        
     3. In "Optional" mode with the parameter "entire", matches 
        between the "search-string" and the tag values in the 
        "tag_name" tags are not case-sensitive.

     4. Quotation marks are not necessary for a single token except 
        in rare circumstances. For example: "&".
                     
=========================(46) tagFix ==============================

"tagFix" repairs a limited number of tag irregularities. 

"tagFix" produces "out7.pgn" and "manifest-f". "manifest-f" lists 
the repairs and should be examined after each execution to be sure
that no unexpected repairs were performed. 

"tagFix" removes hidden control characters at the beginning of a
"UTF-8" encoded "pgn" file.

"tagFix" removes backslash ("\") character(s) at the end of any tag
value. For example, [Site "New York\\"] becomes [Site "New York"].
Without this fix, Windows would consider the closing quotation mark
to be part of the tag data value.

"tagFix" removes beginning or ending space(s) (" ") in a tag value. 
For example:

  [Site     "  New   York  "   ] becomes [Site "New   York"]. 

The extra space in the middle of a tag data value is not removed.

"tagFix" removes a comma (",") at the end of a "White" or "Black" 
tag value.

"tagFix" removes a period (".") at the end of a "White" or "Black"
tag value provided the last token of the name has at least two 
characters (not counting the period). For example: "Jones, AC." 
becomes "Jones, AC", but "Smith, B." is unchanged.

If needed, "tagFix" inserts a "space" after a "comma" in the name 
value of a "White" or "Black" tag. For example:
 
  [White "Spassky,Boris"] becomes [White "Spassky, Boris"].
  
If needed, "tagFix" inserts a "period" after an isolated uppercase 
alphabetical character in the data value of a "White" or "Black" 
tag provided the data value contains a comma. For example:

  [Black "Smith, A"] becomes [Black "Smith, A."].
  
  [White "Jones, A B"] becomes [White "Jones, A. B."]
  
"tagFix" will not insert a period in [White "Wilson, AB"].

"tagFix" will not insert a period after an isolated non-alphabetical 
character such as in [Black "Naum 4"]. 

"tagFix" will not insert a period after an isolated single lowercase 
alphabetical character such as in [White "Jones, y"] or as in
[White "Jones y Smith, Tom"]. 

"tagFix" will not insert a period after a single alphabetical 
character followed by a comma, as in [Black "A, Robert"].

"tagFix" will not insert a period if the name does not have a comma,
as in [White "King George V"]. However [White "King, George V"] will
be changed to [White "King, George V.].
 
For "FEN" and "SetUp" tags, "tagFix" does the following:

  1. Removes "FEN" & "SetUp" tags for the standard opening position.
  2. Removes individual "SetUp" tags not accompanied by "FEN" tags.
  3. Ensures that "FEN" tags are accompanied by "SetUp" tags with
     value "1". 

"tagFix" inserts a null value ("?" or "*" or "????.??.??") for a 
missing tag data value ("").

Syntax:   tagFix filename.pgn

Example:  tagFix alpha.pgn

Output:   out7.pgn, manifest-f

Comments:

     1. Examine "manifest-f" to look for any unexpected change(s) 
        made by "tagFix".

=========================(47) tagInsert ============================

"tagInsert" replaces all tag values of a user-specified tag type with
user-specified values in a text file. The chosen tag type must be 
present in every game of the "pgn" file.

The user-specified file is named "tagdata". Tag values must be on 
successive lines, with no lines blank. The line number of the tag 
value has to correspond to the number of the game where it will be 
inserted.

If the chosen tag type is not present at all or is not present in
some games, you can use "tagCreate" to fix the problem. It will,
after removing any existing tags of the tag type, insert a new tag
in every game. The values of the new tags are unimportant because 
"tagInsert" will be replacing those values.

"tagInsert" might NOT work properly if the number of tag values 
in "tagdata" is NOT equal to the number of games in the "pgn" file.
If they are not equal, a WARNING message with the different numbers
will be displayed. See the comment below.

If the new tags have many different values then use "tagInsert". 
Use "tagCreate" when all the new tags have the same value. Also
a text editor can be used.

Syntax:   tagInsert filename.pgn tag_type tagdata

Example:  tagInsert alpha.pgn Round tagdata

Output:   out1.pgn

Comments:
    
     1. "tag_type" and the filename "tagdata" are case-sensitive.

     2. Sometimes the number of data values in "tagdata" is not what
        you expect because of a missing <enter> at the end of the 
        last data line, or because of extra blank data lines.
        
     3. The best way to create a long column of data values is to use 
        an Excel worksheet. Then save it as a text file.

=========================(48) tagList ==============================

"tagList" lists each tag type that occurs in the "pgn" file and its 
number of occurrences.

Syntax:   tagList filename.pgn

Example:  tagList alpha.pgn 

Output:   outTag

=========================(49) tagNull ==============================

"tagNull" replaces all values of a user-specified tag type with its 
null value EXCEPT for the "FEN" tag. 

The tag type is listed as a parameter. For example:

  tagNull alpha.pgn Round

Unless specified below, the null value for a tag is "?".

For the "Date" tag and "...Date" tags (for example "EventDate"), 
the null value is "????.??.??".

For the "Result" tag, and the result value at the end of the
"MoveText" Section, the null value is "*". 

For the "Time" tag, the null value is "??:??:??".

For the "SetUp" tag, the null value is "0".

"tagNull" will NOT replace the values of "FEN" tags as that will 
usually make the PGN game description ILLEGAL. "fenRemove" removes 
GAMES with a "FEN" tag except if the "FEN" value is the standard 
opening position. "tagFix" removes "FEN" tags whose value is the 
standard opening position.

"tagNull" replaces ALL previous tag values with its null value. The 
number of null values inserted equals the number of tag occurrences.
       
If you want to set more than one tag type to its default value, then
you have to rerun "tagNull" for each tag type. Be sure to rename 
"outH.pgn" before the next execution of "tagNull". 

For example:

  tagNull alpha.pgn Event
  copy outH.pgn temp.pgn
  tagNull temp.pgn Site
  copy outH.pgn temp.pgn
  tagNull temp.pgn Round

The file "outH.pgn" will now have the tag types Event, Site, and Round
set to their default values.

Syntax:   tagNull filename.pgn tag_name

Example:  tagNull alpha.pgn Round

Output:   outH.pgn 

Comment:

     1. "tag_name" is case-sensitive.

     2. It is very important that all tags have a value. Even one tag 
        instance without a value could cause some programs to crash.
            
=========================(50) tagOrder =============================

"tagOrder" rearranges the tag types into a generally accepted order. 
The first 12 tag types are ordered as follows: "Event", "Site", "Date", 
"Round", "White", "Black", "Result", "WhiteElo", "BlackElo", "ECO", 
"SetUp" and "FEN". They are then followed by the other tags in their 
original order, with the exception of "PlyCount", which is last.

Syntax:    tagOrder filename.pgn 

Examples:  tagOrder alpha.pgn 

Output:    out3.pgn 

Comment:

     1. Only the first seven tag types are "required" by "PGN"
        specifications: "Event", "Site", "Date", "Round", "White", 
        "Black" and "Result". 
    
=========================(51) tagRemove ============================

"tagRemove" can remove all instances of a user-specified tag type EXCEPT 
for "Event" and "FEN". 

The tag type to be removed is listed as a parameter. For example:

  tagRemove alpha.pgn ECO

"Event" is a required tag type that "tagRemove" will NOT remove. It 
is NOT recommended to remove the other required tags types: "Site", 
"Date", "Round", "White", "Black" and "Result". 

"tagRemove" can remove many miscellaneous tags types at one time by 
using the parameter "misc". "misc" will remove all tag types EXCEPT: 
"Event", "Site", "Date", "Round",  "White", "Black", "Result", 
"WhiteElo", "BlackElo", "ECO", "SetUp", "FEN", "PlyCount", 
"Termination", "TerminationDetails", and "TimeControl".

Be careful using the parameter value "misc". It may remove important
tag types that you want to keep. Users should first use "tagList" 
to check which tag types are present.

"tagRemove" will NOT remove "FEN" tags as that will usually make the 
PGN game description ILLEGAL. See "fenRemove" and "tagFix" for
more information.

If you wish to remove more than one tag type without using "misc", 
then you have to run "tagRemove" for each tag type to be removed. 
Be sure to rename/copy "outJ.pgn" before the next execution of 
"tagRemove". For example:

  tagRemove alpha.pgn Site
  copy outJ.pgn temp.pgn
  tagRemove temp.pgn Round
  copy outJ.pgn temp.pgn
  tagRemove temp.pgn ECO

The output file "outJ.pgn" will no longer have the tag types "Site", 
"Round" and "ECO".

Syntax:   tagRemove filename.pgn [tag_name | misc]

Example:  tagRemove alpha.pgn WhiteElo

Example:  tagRemove alpha.pgn misc

Output:   outJ.pgn

Comments:

     1. "tag_name" and "misc" are case-sensitive.

     2. "eloRemove" removes all "WhiteElo" and "BlackElo" tags.

     3. An alternative to removing tags is to use "tagNull" to
        insert null values for a user-specified tag.

=========================(52) tagValue =============================
                                                   
"tagValue" lists the data values of a user-specified tag type and 
the number of occurrences of each data value. 

Syntax:   tagValue filename.pgn tag_name

Example:  tagValue alpha.pgn Event

Example:  tagValue alpha.pgn Termination

Output:   outVal

Comments:

     1. "tag_name" is case-sensitive.

=========================(53) trim =================================

"trim" produces an output "pgn" file that puts each "full move" on
the same line while also removing comments if present. "trim" lets
you set the maximum output width in the "MoveText Section" from 40 
to 100 characters. The default is 76 characters.

"trim" removes comments, nags, variations, and major symbolic
annotation symbols (!, !!, ?, ??, !?, ?!, +-, -+, +/-, -/+, +=,
=+, +/=, =/+, =, ~, and N), if present.

"trim" removes "en passant" indicators "ep", "e.p." and "/ep",
if present.

If needed, "trim" inserts a space (" ") after a move number.
For example, "1.e4" becomes "1. e4".

"trim" changes any occurrences of numerical castling notation 
("0-0", "0-0-0") to alphabetical ("O-O", "O-O-O").

"trim" changes any occurrences of "1. ..." to "1...", and similarly
for any other move number.

"trim" starts each new line of moves with a move number.

"trim" converts one-line "MoveText" sections into multiple lines. 

Syntax:    trim filename.pgn [output_width]

Examples:  trim alpha.pgn

           trim alpha.pgn 60

Output:    outR.pgn

Comment:

     1. On occasion, plyCount, trim and truncate have an early exit
        output problem with a very large "pgn" file. See section
        "Handling Output Issues" above.
                       
=========================(54) truncate =============================

"truncate" counts the number of plies (half-moves) and then removes 
any plies occurring after a user-specified number. If a game has 
fewer plies than the user-specified number, that game is output 
without change. Results are not removed.

"truncate" removes existing "PlyCount" tags. New "PlyCount" tags can
 be inserted using "plyCount".

"truncate" removes comments, nags, variations, and major symbolic
annotation symbols (!, !!, ?, ??, !?, ?!, +-, -+, +/-, -/+, +=,
=+, +/=, =/+, =, ~, and N), if present.

"truncate" removes "en passant" indicators "ep", "e.p." and "/ep",
if present, so that they do not distort the ply count.

Syntax:   truncate filename.pgn maximum_plies

Example:  truncate alpha.pgn 50

Output:   outU.pgn

Comments:

     1. To remove all game moves but leave the results:

          truncate alpha.pgn 0

     2. On occasion, plyCount, trim and truncate have an early exit
        output problem with a very large "pgn" file. See section
        "Handling Output Issues" above.
                       
=========================(55) upset ================================

"upset" extracts games between two players having an Elo difference 
equal to or greater than the "min_Elo_difference", which by default, 
is 250. Output is in three files for wins, draws, and losses.

The user can specify another minimum Elo difference.

Output files "outU1.pgn", "outU2.pgn" and "outU3.pgn" contain games 
between players whose Elo difference is equal to or greater than the 
"min_Elo_difference".

Output file "outU1.pgn" contains games won by the player with the
lower Elo. These games are the "upsets".

Output file "outU2.pgn" contains games ending in a draw.

Output file "outU3.pgn" contains games won by the player with the 
higher Elo.

Output file "excludeU4.pgn" contains games between players whose
Elo difference is less than the "min_Elo_difference".

"upset" does not extract games missing an Elo rating or missing a
result. Use "eloCheck" to remove games with a missing Elo rating.
Use "cleanUp" to remove games without a result ("*").

Syntax: upset filename.pgn [min_Elo_difference]

Usage:  upset alpha.pgn 

        upset alpha.pgn 300

Output: outU1.pgn, outU2.pgn, outU3.pgn, excludeU4.pgn

====================================================================
====================================================================
