Angband 3.3.0 is out

[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.)

[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?

[Derakon]

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

[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.

[EpicMan]

What about 'bane' instead of *slay*?

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

[Magnate]

We could do what Magnate suggested, although I'm reluctant for our doc format to control how we talk about the content!

Just to say that as a general rule I agree with this 100%, but *slay* is something I've been wanting to re-name for years ....

Just sayin'.

[d_m]

Yes, I can, but the problem here is that we want two things at the same time:
-the .txt should look good, so that it can be used in the online help without further munging
-the .txt should be a valid RST document that can be converted to a good-looking HTML/PDF.
You cannot achieve the two goals at the same time for "*slay*".

Yes, fph is totally right about this.

Unfortunately all of the modern plaintext markup systems are going to have this problem I think.

If we're willing to forgo italics/bold then I could imagine a (very simple) transformation script from the plaintext into valid RST that escapes *. Maybe this is a terrible idea though?

We could do what Magnate suggested, although I'm reluctant for our doc format to control how we talk about the content!

What do you all think? fph as the person working on this now I'm especially interested in your opinion.

[fph]

Yes, I can, but the problem here is that we want two things at the same time:
-the .txt should look good, so that it can be used in the online help without further munging
-the .txt should be a valid RST document that can be converted to a good-looking HTML/PDF.
You cannot achieve the two goals at the same time for "*slay*".

[EpicMan]

Can't you just escape the asterisks in the docs ("\*")?

[CJNyfalt]

..., but I do think we could happily replace "*slay*" with "kill" or "execute" or "..'s bane" or whatever. I don't think we desperately need to stick with *slay*.

I was going to suggest to use bold instead of italics, but renaming is an even better solution.

[Magnate]

I started rewriting the docs in RST. After a hands-on experience, I see only some minor problems. I am listing them here:
-funny unexpected side-effect: when RST reads "*slay* dragons", it thinks you want to put the word "slay" in italics. I think we can work around this without making the .txt unclear by using a suitably crafted CSS that inserts back *...* before and after every <em></em> tag. Yes, that's a ugly hack.
-it's not clear to me how to link to a specific section of another document (e.g., link to a section in commands.txt from dungeon.txt)
-a couple of constructs look strange when read directly in the .txt. For instance, links with "_" at the end. People reading the .txt help files would have to get used to "some things looking strange".
-in the command descriptions, we have (``right-paren``) (where ``text`` means "typeset the text in monospace). I'd like to replace "right-paren" with the symbol, but this seems to be impossible in RST.

On a conference this week, but looking forward to finishing soon (if you don't tell me to stop, of course ).

Not at all - thanks for the effort! I'm not familiar with RST so I hope d_m will be able to answer your points better than I can, but I do think we could happily replace "*slay*" with "kill" or "execute" or "..'s bane" or whatever. I don't think we desperately need to stick with *slay*.

I don't think I understand the third point - could you give us an example of a link with _ at the end?

[fph]

I started rewriting the docs in RST. After a hands-on experience, I see only some minor problems. I am listing them here:
-funny unexpected side-effect: when RST reads "*slay* dragons", it thinks you want to put the word "slay" in italics. I think we can work around this without making the .txt unclear by using a suitably crafted CSS that inserts back *...* before and after every <em></em> tag. Yes, that's a ugly hack.
-it's not clear to me how to link to a specific section of another document (e.g., link to a section in commands.txt from dungeon.txt)
-a couple of constructs look strange when read directly in the .txt. For instance, links with "_" at the end. People reading the .txt help files would have to get used to "some things looking strange".
-in the command descriptions, we have (``right-paren``) (where ``text`` means "typeset the text in monospace). I'd like to replace "right-paren" with the symbol, but this seems to be impossible in RST.

On a conference this week, but looking forward to finishing soon (if you don't tell me to stop, of course ).

[d_m]

RST looks interesting and easy.
I have used LaTeX in the past and liked it.
I have tried Docbook and I hated it for having too verbose tags.
HTML has problems with formating and indexing, and also use the same clumsy type of tagging as Docbook.
There is also troff, texinfo and POD, but I have no experience at all about them. From what I have read the first two is not what we are looking for, unless we want to create a man-page. I know next to nothing about POD.

I've written troff and it's neat in a crufty way but not something I'd want to maintain. I used POD at a previous job writing Perl and despise it as a format.

I haven't used texinfo at all, nor docbook.

EDIT: The other formats I expected people to bring up (maybe) were Markdown and Asciidoc, which are similar to (and come after) RST.

[CJNyfalt]

RST looks interesting and easy.
I have used LaTeX in the past and liked it.
I have tried Docbook and I hated it for having too verbose tags.
HTML has problems with formating and indexing, and also use the same clumsy type of tagging as Docbook.
There is also troff, texinfo and POD, but I have no experience at all about them. From what I have read the first two is not what we are looking for, unless we want to create a man-page. I know next to nothing about POD.

[d_m]

That said, I also have a soft spot for LaTeX, so I am fine with that choice as well. I mostly just hate writing HTML.

I'd also be OK with one of the other "plaintext-esque" markup languages. I just know that RST has gotten a lot of use and is pretty flexible/powerful.