Insert human readable commentary about python-chess-annotator

[rpdelaney]

Using human-readable symbols rather than NAGs is proposed in #15 so we should discuss that there.

As for the other commentary added by lichess, e.g. 'Inaccuracy. Best move was Ng5.' and so on, I have mixed feelings about this. For starters, I don't intend just to mimic lichess. So there would have to be some independent, free-standing reason to do what they are doing also here. In this case I don't see what that reason is.

All the information added by this extra lichess commentary is at least implied in the annotations already produced by chess-annotator. You know your move was a mistake because it got an annotation; you know how big of a mistake it was based on the NAG and the difference in the computer's evaluation for the played move vs the best move; and you know what the best move was from the engine PV that is added as a variation.

So I don't see what this would improve, or who would be helped by this. The output format we have now is concise and information-dense. How would the user experience be improved by saying the same thing in more ways?

[rpdelaney]

This might hinge somewhat on what you expect the PGN format to achieve in a more general sense. To me, PGN is a specification for structuring data about chess games in a machine readable way. It's my expectation that users will be piping the output into a PGN reader of some kind and consuming it that way. Making the output from chess-annotator human readable in the terminal has not been a goal for this project.

With that in mind...

I find { 4. Ng5 Blunder: Best move was } (4. Ng3) to be much more meaningful than 4. Ng5 $4 (4. Ng3).

Put that way, I agree with you -- mostly because a NAG obfuscates the content of the annotation. But in a PGN reader, the difference is not so clear at all. If we do implement #15 then this problem would be fully eliminated in my eyes. (I'm not even sure it's actually a problem as it is, though.)

The move suggestions are very helpful to immediately understand why this move was a blunder or mistake

I agree. But I don't understand how it is more helpful than just looking at the engine variation. It's right there, and can be read just as easily as the human-readable comment.

I would suggest therefore an (or multiple) argument(s) which allows the user to granulate which kind of annotation they would like.

This would be an ideal solution, yes. But it would also add a non-negligible amount of complexity and maintenance overhead. I'll be thinking about this more, but right now I'm doubting that the payoff would be worth it.

[ddugovic]

Thankfully such new annotations would comply with the PGN specification and therefore robust PGN parsers should tolerate them if we choose to create them. Otherwise we'd be stuck using Numeric Annotation Glyphs:

8.2.3.8: SAN move suffix annotations

Import format PGN allows for the use of traditional suffix annotations for
moves.  There are exactly six such annotations available: "!", "?", "!!", "!?",
"?!", and "??".  At most one such suffix annotation may appear per move, and if
present, it is always the last part of the move symbol.

[Entze]

This is of course a question of preference. I find that the NAGs alone (even with the suggested additions of #15) are more for computer parsing than human interpretation.
I find { 4. Ng5 Blunder: Best move was } (4. Ng3) to be much more meaningful than 4. Ng5 $4 (4. Ng3).
The move suggestions are very helpful to immediately understand why this move was a blunder or mistake, etc..

I would suggest therefore an (or multiple) argument(s) which allows the user to granulate which kind of annotation they would like.

For example:
--commentary -c for Blunder, etc
--move-suggestions -m for move suggestions
--NAGs -n annotate NAGs
--traditional-annotation -t turns on ? ?! etc (particularly with #15 in mind)
--all-annotations -a turns on all of the above

[ddugovic]

I fully agree, PGN is meant to be machine-readable (and convenient to type by hand if necessary).

But in a PGN reader, the difference is not so clear at all.

I agree, most (all?) PGN readers lack this obvious (but costly to localize) feature. Until that changes, English (or other language) prose in PGN is of obvious benefit (and other annotations, less so).

[rpdelaney]

I agree, most (all?) PGN readers lack this obvious (but costly to localize) feature. Until that changes, English (or other language) prose in PGN is of obvious benefit (and other annotations, less so).

I'm not sure I understand - it sounds like you said you agree with me, and then you go on to say that prose comments are an obvious benefit?

[ddugovic]

I'm just saying... because ChessBase and others don't translate ! and ? symbols into prose, for amateur chess players (< 1800 FIDE) it's easier to context-switch between the text viewer and the board viewer if there's prose separating/spacing the moves/variations. Yes, the text viewer typically highlights the "last move" text, but prose helps frame "these are alternative moves" and provides English (or other) context which is more easily remembered than !? or ?! etc.

[rpdelaney]

For fun, here's the same game annotated by python-chess-annotator:

[Event "?"]
[Site "https://lichess.org/sugtc1iC"]
[Date "????.??.??"]
[Round "1"]
[White "?"]
[Black "?"]
[Result "1-0"]
[Variant "Standard"]
[TimeControl "-"]
[ECO "C61"]
[Opening "Ruy Lopez: Bird Variation"]
[Termination "Normal"]
[Annotator "Stockfish 8 64 POPCNT"]
[WhiteACPL "95"]
[BlackACPL "117"]

{ Stockfish 8 64 POPCNT } 1. e4 e5 2. Nf3 Nc6 3. Bb5 Nd4 { C61 Ruy Lopez: Bird Variation } 
4. Bc4 Nf6 5. c3 Nc6 $6 { 1.27 } ( 5... Nxf3+ 6. Qxf3 { 0.02/23 } ) 6. d3 d5 7. Bb5 $2 { -0.49 } 
( 7. exd5 Nxd5 8. Qb3 Na5 9. Qa4+ Nc6 10. Nxe5 Qe7 11. Bxd5 Qxe5+ { 1.10/26 } ) 7... dxe4 
8. Nxe5 Qd5 9. Bxc6+ bxc6 10. Bf4 Bd6 11. d4 Bg4 $2 { 0.58 } ( 11... Ba6 { -0.93/21 } ) 
12. c4 $2 { -0.99 } ( 12. Nxg4 Bxf4 13. Nxf6+ gxf6 14. Qe2 f5 15. Na3 O-O 16. Nc4 Bd6 
{ 0.58/25 } ) 12... Qa5+ $2 { 0.83 } ( 12... Bxd1 13. cxd5 Nxd5 14. Bd2 Ba4 15. Nc3 Nxc3 
16. Bxc3 f6 17. b3 { -0.96/25 } ) 13. Qd2 Qxd2+ 14. Nxd2 Nh5 $6 { 1.07 } ( 14... O-O { 0.18/23 } ) 
15. g3 $6 { -0.25 } ( 15. Be3 { 1.05/23 } ) 15... Rb8 $2 { 2.21 } ( 15... Nxf4 { -0.41/24 } ) 16. f3 $2 { 
-0.12 } ( 16. Nxg4 Nxf4 { 2.50/24 } ) 16... exf3 $2 { 2.01 } ( 16... Nxf4 17. Nxg4 { -0.02/22 } ) 17. 
Ndxf3 $4 { -1.68 } ( 17. Nxg4 Bxf4 { 2.25/23 } ) 17... Rxb2 $4 { 1.27 } ( 17... Bxf3 18. Nxf3 Nxf4 19. 
gxf4 Rxb2 20. O-O Bxf4 21. Rae1+ Kd8 22. Rf2 { -1.91/24 } ) 18. O-O $2 { -0.73 } ( 18. Nxg4 Bxf4 
{ 1.39/25 } ) 18... c5 $4 { 2.63 } ( 18... Bxf3 19. Rxf3 Nxf4 20. gxf4 f6 21. Nd3 Rd2 22. c5 Bf8 23. 
Re1+ { -0.88/26 } ) 19. Nxg4 Nxf4 20. gxf4 Bxf4 $2 { 4.14 } ( 20... O-O 21. Nge5 { 1.68/24 } ) 21. 
Rfe1+ Kd7 22. dxc5 f6 23. Red1+ Kc6 24. Rd5 $6 { 1.53 } ( 24. Nd4+ Kd7 { 2.59/22 } ) 24... h5 25. 
Nd4+ Kb7 26. c6+ Kc8 $6 { 2.57 } ( 26... Kb6 27. Nf2 { 1.38/24 } ) 27. Nf2 $6 { 1.37 } ( 27. Rf1 { 
2.87/22 } ) 27... Be3 28. Rf1 g5 $4 { 4.68 } ( 28... g6 29. Rd7 Re8 30. Nb5 Bb6 31. c5 Rxb5 32. 
cxb6 Rg5+ 33. Kh1 { 1.45/26 } ) 29. h3 $2 { 1.58 } ( 29. Nf5 Bb6 { 4.57/24 } ) 29... g4 $2 { 4.12 } ( 
29... Rd8 30. Rxd8+ Kxd8 31. Ne6+ Ke7 32. Nxc7 Kd6 33. Nd5 Bd4 34. c7 { 1.62/26 } ) 30. hxg4 
hxg4 31. Rf5 $4 { -5.14 } ( 31. Nf5 Bg5 32. Nxg4 Kb8 33. Rf2 Rb4 34. Nge3 Rb6 35. Rc5 a6 
{ 3.62/24 } ) 31... g3 32. Kg2 gxf2 $4 { -1.01 } ( 32... Bxf2 33. R5xf2 gxf2 34. a3 Rh4 35. Nf5 Rxc4 
36. Ne7+ Kd8 37. Nd5 { -5.29/26 } ) 33. Nb5 $4 { -3.81 } ( 33. Rd5 Bxd4 34. Rxd4 Rb6 35. Rxf2 
Rxc6 36. Kf3 Re6 37. Kg4 Rh6 { -0.73/26 } ) 33... Rg8+ 34. Kf3 Bd4 $4 { 4.35 } ( 34... Re8 35. 
Nc3 { -2.34/25 } ) 35. Nxd4 Rg1 $4 { 8.25 } ( 35... Rd8 36. Rd5 { 3.91/27 } ) 36. Rxf2 1-0

[rpdelaney]

Alright, at this point I'm not inclined to alter the way we present engine commentary in this app. If you are able to get the human-readable symbols added to python-chess, please re-open #15 and I'll likely add that in. Thanks for the input regardless.