[DOCUMENTATION] Shout options have unclear behavior

Hello, while checking the source code because of my recent feature request, I’ve explored a bit and found the source code for the shout/tell command (t). I then remembered that in some of my games I was surprised by how my allies behaved, and that’s because there’s no user-facing documentation for what each of the options (attack/guard/retreat/etc.) does. Reading the source code helped a lot, it’s surprisingly clear what behavior it sets (e.g. patrol an area vs. patrol the player, alert against monsters vs. alert only to attacks on the player, etc.), but I think there should be documentation of that (or printing help when the player types ?). In addition, I think the stop attacking/stop fighting option would be more appropriately named “stand by”, considering it basically tells the allies to be alert to whatever attacks the player. (Perhaps the options could be reworked altogether?) Thanks.

I think it would be reasonable to open a documentation bug report on this; this is a known longstanding issue but I don’t think there is an open bug about it: Issues · crawl/crawl · GitHub