Angband 3.3.0 is out

[EpicMan]

What about 'bane' instead of *slay*?

So "Foo of *slay* orc" becomes "Foo (Orcbane)", "*slay* demon" becomes "(Demonbane)", etc.

[fph]

We could in fact take the occasion to rename
*slay* X -> X's bane
*healing* -> greater healing
*remove curse* -> remove heavy curse (seems more noob-friendly: that's what it does, isn't it?)
*enlightenment* -> greater enlightenment, or greater knowledge

Just sayin', too. Ok, but that's cheating --- I agree with d_m, we shouldn't let the doc format force decisions on game content.

I'd say let me ponder for some other days on RST's documentation, maybe there is a better way out that has eluded me. Of course anyone else, with or without previous RST experience, is free to suggest solutions. Maybe there's a clever use of "interpreted text" or "substitution directives" that I am now missing.

There's another problem that I forgot in my previous message, and that we could in fact turn into a feature to our advantage: there is already some "markup" in the lib/help files, namely, the lines starting with asterisks in text such as

***** <pickup_always>
***** <pickup_inven>
Always pickup items [pickup_always]
Always pickup items matching inventory [pickup_inven]
If pickup_always is on, all items are always picked up, providing it is
safe to do so. If pickup_inven is on, then items matching those in your
inventory are always picked up.

If I am not mistaken, they are used to provide context-sensitive help. It would be nice to convert them to some RST-approved construct.

So in fact we're not talking really "readable TXT" + "valid RST", but rather "readable TXT-with-some-extra-interpreted-markup" + "valid RST": maybe if we design this additional markup language well we can have it interact well with RST.

[Derakon]

I'd say Enlightenment => Wizard Sight; *Enlightenment* => Enlightenment. But that's just me.

[Magnate]

We could in fact take the occasion to rename
*slay* X -> X's bane
*healing* -> greater healing
*remove curse* -> remove heavy curse (seems more noob-friendly: that's what it does, isn't it?)
*enlightenment* -> greater enlightenment, or greater knowledge

Just sayin', too. Ok, but that's cheating --- I agree with d_m, we shouldn't let the doc format force decisions on game content.

... but in all these cases, getting rid of the asterisks would be a good move for all sorts of reasons.

There's another problem that I forgot in my previous message, and that we could in fact turn into a feature to our advantage: there is already some "markup" in the lib/help files, namely, the lines starting with asterisks in text such as

If I am not mistaken, they are used to provide context-sensitive help. It would be nice to convert them to some RST-approved construct.

So in fact we're not talking really "readable TXT" + "valid RST", but rather "readable TXT-with-some-extra-interpreted-markup" + "valid RST": maybe if we design this additional markup language well we can have it interact well with RST.

Yes, absolutely. The goal is to have more context-sensitive help available in the game (at the moment it's only the options), so we definitely need a way to do this. Maybe we could get the game to read the RST directly, and dispense with the txt-with-markup altogether?

[myshkin]

There's another problem that I forgot in my previous message, and that we could in fact turn into a feature to our advantage: there is already some "markup" in the lib/help files, namely, the lines starting with asterisks in text such as

If I am not mistaken, they are used to provide context-sensitive help. It would be nice to convert them to some RST-approved construct.

So in fact we're not talking really "readable TXT" + "valid RST", but rather "readable TXT-with-some-extra-interpreted-markup" + "valid RST": maybe if we design this additional markup language well we can have it interact well with RST.

The current markup language recognizes menu items and tags, both denoted by five asterisks at the beginning of the line. Menus behave as one might expect, where pressing 'a' selects menu item a, and so forth. Tags are essentially the same as HTML anchors; one can call show_file("options.txt#use_sound", NULL, 0, 0), and the file browser will pop up options.txt starting from the use_sound tag.

An rST reference can replace menu items, and an rST internal hyperlink target should suffice to replace tags. The show_file() routine could be modified to read the subset of rST we decide to use in the help files. (I hope that subset is very small.)