Book update and stuff

I'm updating the book, since previous update is already two months old, even though there aren't that many changes, but then again, there are no reasons to hold them back.

Changes from the previous update include:

• divided, moved piece actions tables
• fixed action tables for Pawn, Shaman, Wave
• described mometum restrictions of actions
• fixed notation, grammar for double side-effect (promotion + capture)
• added examples, Pawns (not) blocked by Wave
• described singe-step pieces and transparency
• clarified diverging from opponent's Starchild

The book was compiled on July 21, 2024, version is 20240721.112914.

In a bit surprising, unexpected move (pun intended!), last month I decided to convert all of DoxyGen documentation into Sphinx, and also ditch my editor of choice (MS Visual Code, at the time) for something else. This was done mostly on some sort of an intuition, feeling; which is strange, since I'd usually try to do some (strategic) thinking, e.g. "syntax hilight is broken again, for xyz times", "folding comments is borked, again", "editor is getting too slow", ...

Each documentation system has its own strengths and weaknesses, just like everything else in life. I'm already missing DoxyGen warnings when e.g. functions parameters do not match content of a C file. Also, with DoxyGen, it's immediately clear what is documented, and what is not. On the other hand, for DoxyGen one better have editor capable of folding (unusual) comments.

Sphinx is much more crude, you have to specify everything by hand, write everything down explicitly, and even then stumble upon random bricks on the (yellow) road. For instance, files can be organized hierarchically; labels generated automatically from section titles are flat by default (!?), there is only option to prefix them with a filename (!?). As a result, all your sections has to be prefixed with context (by file name, by parent title, etc.); so you now have titles:

• Piece
• Piece data
• Piece functions
• Tags 
• Tags data
• Tags functions

instead of what should be default:

• Piece
• Data
• Functions
• Tags
• Data
• Functions

Sure, second option can be done, but then files might have to be split, sometimes into very small ones. It's no good.

On the other hand, Sphinx does not bloat source code files. It's free-form, and lets you easily organize any way you want, and document key concepts, designs, informal agreements, and so on. Currently, I plan to document libcrochess in parallel to its development; later I might add documentation for various build scripts (gfx.sh, pdf.sh, build.py, py/), and docs for off-screen-shot generator.

Converting documentation proved to be a bit grindy, but relaxing experience, although there were way more text to convert than I'd ever imagine I has written. Anyway, it's done now.

Changing the editor was a bit more pain. Unlike some (most?) developers, I'm not attached to editor I use. Still, I do like the ones that tend to disappear when I'm working, and have all the essentials: 

• proper dark-mode
• simple project management, as in a collection of files
• find in (project) files, and with regex
• search and replace in (project) files, also with regex
• visual editor, e.g. commands are on clickable menu, or at keypress, not on a command line (i.e. vi is not for me)
• split text panes, preferably both panes are proper editors

I tried Kate, but only very briefly, I wasn't able to set it into proper dark mode, since some GUI, window elements have either hard-coded colors, or under non-KDE desktop it defaults to some light colors. Tried to install some KDE control panel app, tried to  fiddle with some settings, only to fail, time and again. It seems I'd have to install full-blown KDE desktop just to set Kate right. Thanks, but no thanks.

So, I returned back to Geany, which is reasonably good, fast, small, and with selection of useful plugins. It only fails at the last item, and in a strange ways; you can split editor into two panes, but only one (left, in my case) is a proper editor with working key shortcuts, the other one can be edited, but most shortcuts don't work.

I asked devs, quite some time ago, it seems it's quite a challenging issue, since Geany was designed from the very beginning around assumption that one file will be ever edited by only one editor widget. There is a 2.0 version out there, but it does not come in Mint repository, since default gcc version does not support C++17; so I can't test if new version solved the issue. For what it is, old version is still quite usable. Shame it's not more popular, and made better.

Which left me wanting more. So, I tried Pulsar editor, and it's great. So far, I only find that it does not have "save all" option. Other than that, I have to say I'm not fond of Electron apps (and 750+ MB for an editor!), but here we are. I think I'll stick with it, for now.