Angband 3.3.0 is out

[Gockel]

ok, thanks for the answer! and sorry for misposting, i guess i shouldn't post at four in the morning being half-asleep anyway.

[bio_hazard]

Thanks for posting the OSX Version- seems to be working fine although I've only gotten to about 400'. Haven't played much since 3.1.2 so there's a lot of new stuff in here even at low levels.

Myshkin- I sent you a PM about this but unfortunately I don't have xcode on my old machine after all and couldn't compile on my old ppc mac.

[CJNyfalt]

I don't have a big problem with this, but it does sound as if a number of people are quite fond of the PDF manual. Does anyone have a really strong objection to shipping HTML in lieu of PDF?

I would prefer a format that is both easy to convert to PDF and to HTML. Also HTML documentation is probably the format that I like least to use.

[takkaria]

I would prefer a format that is both easy to convert to PDF and to HTML. Also HTML documentation is probably the format that I like least to use.

What might be useful to move on from this point of discussion is someone to make a list of pros and cons of various formats?

Personally I'd be pretty happy with HTML as the base format - it's easy to put online, there are converters for PDFs (probably good enough ones), and it's approaching a universal language.

[d_m]

I like reStructuredText.

http://docutils.sourceforge.net/rst.html

The basic gist is that it's a plaintext format (which is readable as text) which can be converted to HTML, PDF, whatever. I have used it before and found it to be pretty easy to create and maintain.

Here are the goals that were set when designing RST:

1. Readable. The marked-up text must be easy to read without any prior knowledge of the markup language. It should be as easily read in raw form as in processed form.
   
2. Unobtrusive. The markup that is used should be as simple and unobtrusive as possible. The simplicity of markup constructs should be roughly proportional to their frequency of use. The most common constructs, with natural and obvious markup, should be the simplest and most unobtrusive. Less common constructs, for which there is no natural or obvious markup, should be distinctive.
   
3. Unambiguous. The rules for markup must not be open for interpretation. For any given input, there should be one and only one possible output (including error output).
   
4. Unsurprising. Markup constructs should not cause unexpected output upon processing. As a fallback, there must be a way to prevent unwanted markup processing when a markup construct is used in a non-markup context (for example, when documenting the markup syntax itself).
   
5. Intuitive. Markup should be as obvious and easily remembered as possible, for the author as well as for the reader. Constructs should take their cues from such naturally occurring sources as plaintext email messages, newsgroup postings, and text documentation such as README.txt files.
   
6. Easy. It should be easy to mark up text using any ordinary text editor.
   
7. Scalable. The markup should be applicable regardless of the length of the text.
   
8. Powerful. The markup should provide enough constructs to produce a reasonably rich structured document.
   
9. Language-neutral. The markup should apply to multiple natural (as well as artificial) languages, not only English.
   
10. Extensible. The markup should provide a simple syntax and interface for adding more complex general markup, and custom markup.
    
11. Output-format-neutral. The markup will be appropriate for processing to multiple output formats, and will not be biased toward any particular format.

I can't say I'm at all excited about maintaining HTML, and I doubt most other people are as well. In my opinion, RST is good because it means people can edit documents without even thinking about markup/formatting/layout/etc and have it mostly work well.

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

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

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.

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

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

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

[EpicMan]

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

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

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

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