Describe variant configuration inheritance in INI

diff --git a/src/variants.ini b/src/variants.ini
index 8947091..a483ef8 100644 (file)
--- a/src/variants.ini
+++ b/src/variants.ini
@@ -24,11 +24,20 @@
 ################################################
 ### Variant configuration:
 # The variant name needs to be specified as a section in square brackets,
-# followed by its rule configurations as key-value pairs.
-# See variants.h for the available options and their default values.
+# followed by its rule configurations as key-value pairs as described below.
 # If you encounter problems configuring variants, please report them at:
 # https://github.com/ianfab/Fairy-Stockfish/issues
 
+### Inheritance
+# If a variant is similar to a previously defined variant,
+# inheritance can be used to simplify the definition. To inherit from the
+# configuration of an existing variant, specify the parent variant after the child
+# variant name separated by a colon, e.g., [gothic:capablanca].
+# When inheritance is used, only the differences to the parent variant need to be defined,
+# see the examples in this file, e.g., 3check-crazyhouse.
+# When no inheritance is used, the default template applies,
+# which is basically standard chess but without any predefined pieces.
+
 ### Piece types
 # Firstly, the piece types for a variant need to be defined.
 # For that, specify the letter used for each piece type, e.g.:
@@ -83,13 +92,13 @@
 # chess960: allow chess960 castling [bool] (default: false)
 # startFen: FEN of starting position (default: rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1)
 # promotionRank: relative rank required to reach for promotion [Rank] (default: 8)
-# promotionPieceTypes: letters of promotion piece options (default: nbrq)
+# promotionPieceTypes: pawn promotion options using their one-letter representations (default: nbrq)
 # sittuyinPromotion: enable Sittuyin-style pawn promotion [bool] (default: false)
 # promotionLimit: maximum number of pieces of a type, e.g., q:1 r:2 (default: <none>)
-# promotedPieceType: mapping between unpromoted and promoted piece types, e.g., p:g s:g (default: <none>)
+# promotedPieceType: mapping between unpromoted and promoted non-pawn piece types, e.g., p:g s:g (default: <none>)
 # piecePromotionOnCapture: piece promotion only allowed on captures (e.g., micro shogi) [bool] (default: false)
 # mandatoryPawnPromotion: pawn promotion is mandatory [bool] (default: true)
-# mandatoryPiecePromotion: piece promotion is mandatory [bool] (default: false)
+# mandatoryPiecePromotion: piece promotion (and demotion if enabled) is mandatory [bool] (default: false)
 # pieceDemotion: enable demotion of pieces (e.g., Kyoto shogi) [bool] (default: false)
 # endgameEval: enable special endgame evaluation (for very chess-like variants only) [bool] (default: false)
 # doubleStep: enable pawn double step [bool] (default: true)
@@ -101,15 +110,15 @@
 # castlingQueensideFile: destination file of king after queenside castling [File] (default: c)
 # castlingRank: relative rank of castling [Rank] (default: 1)
 # checking: allow checks [bool] (default: true)
-# mustCapture: captures are mandatory [bool] (default: false)
+# mustCapture: captures are mandatory (check evasion still takes precedence) [bool] (default: false)
 # mustDrop: drops are mandatory (e.g., for Sittuyin setup phase) [bool] (default: false)
 # pieceDrops: enable piece drops [bool] (default: false)
 # dropLoop: captures promoted pieces are not demoted [bool] (default: false)
 # capturesToHand: captured pieces are go to opponent's hand [bool] (default: false)
 # firstRankDrops: allow pawn drops to first rank [bool] (default: false)
 # dropOnTop: piece drops need to be on top of pieces on board (e.g., for connect4) [bool] (default: false)
-# whiteDropRegion: restrict region for white piece drops [Bitboard]
-# blackDropRegion: restrict region for black piece drops [Bitboard]
+# whiteDropRegion: restrict region for piece drops of all white pieces [Bitboard]
+# blackDropRegion: restrict region for piece drops of all black pieces [Bitboard]
 # sittuyinRookDrop: restrict region of rook drops to first rank [bool] (default: false)
 # dropOppositeColoredBishop: dropped bishops have to be on opposite-colored squares [bool] (default: false)
 # dropPromoted: pieces may be dropped in promoted state [bool] (default: false)