Angband 3.3.0 is out

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

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

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

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

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

[Magnate]

Hope i'm not repeating what is long known. i'm not even completely sure it's a bug. i read a scroll of summon undead and nothing happened. thing is i'm only 99% sure i had see invisible that moment. so i guess it might be possible that something invisible was summoned and disappeared immediately... just thought i'd mention it.
thanks for the nice game btw! i shouldn't be playing as my final university exams are coming up, but oh well... unfortunately the game didn't get worse at all with the new version... addictive as hell.

oh, and one more thing, is it intentional that with roguelike commands pressing ctrl-j (which so far has been the "action command" like dig, open, attack etc,) now brings up this strange action dialogue? can i turn this off somehow?

Hi Gockel,

I'm not sure if you realised, but your post was buried deep in a thread about help docs so might have been missed. Not to worry.

The ctrl-J thing is a known bug, which should be fixed eventually but I'm afraid there's no way to turn it off at the moment.

Summons not appearing is an old bug that we thought we'd fixed, so we are interested in seeing it reproduced. That said, there are some changes to summoning coming in the next dev version, so we'll wait until then to see if it still happens.

[Magnate]

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 think I do, but can't immediately provide compelling reasons why. A PDF help file has been a goal for several years, and it seems a shame to abandon it the version after we finally created it. But perhaps HTML will do everything we want and more.

[Timo Pietilä]

Oh. But if I am not missing anything, those are now displayed in the race/class selection screen in the new nightlies, without need to look in the help.

Not the same thing, I like to see race and class bonuses together so that I don't need to go and check every one of those individually. Those are way easier to check from "ability tables" -section in help.

[myshkin]

My suggestion at this point would be abandoning PDF as well and just living with HTML=>text.

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?

Oh, I must've missed his suggestion. I've checked it out quickly, it seems another good alternative. Only question, how is one supposed to obtain word wrap at the end of the screen? This seems like a pain to do manually when editing the help files.

Sorry, the suggestion was an out-of-band one. I'm not sure what you mean by word wrap...are you talking about editing the source rst files? I would expect that you can set your text editor to wrap at whatever column you like (I'd suggest 75).

[Gockel]

Hope i'm not repeating what is long known. i'm not even completely sure it's a bug. i read a scroll of summon undead and nothing happened. thing is i'm only 99% sure i had see invisible that moment. so i guess it might be possible that something invisible was summoned and disappeared immediately... just thought i'd mention it.
thanks for the nice game btw! i shouldn't be playing as my final university exams are coming up, but oh well... unfortunately the game didn't get worse at all with the new version... addictive as hell.

oh, and one more thing, is it intentional that with roguelike commands pressing ctrl-j (which so far has been the "action command" like dig, open, attack etc,) now brings up this strange action dialogue? can i turn this off somehow?

[fph]

What would we need to build the PDF?

Well, this would be a weak point of HTML as a source format: there is no easy way to automate HTML=>PDF with minimal requirements, up to my knowledge.
Of course every "modern" browser can do that (via printing to pdf), but automating the process within a Makefile seems to be a nontrivial task, especially on multiple platforms and if we do not want to depend on a specific web browser.

There are some tools for this job, but all have their drawbacks: http://code.google.com/p/wkhtmltopdf/ (requires QT), http://www.htmltopdf.org/ (requires Python), http://www.htmldoc.org/ (semi-commercial, the free version doesn't even have a precompiled Windows binary). Many such tools implement their own HTML parser, which doesn't seem a sound solution.

My suggestion at this point would be abandoning PDF as well and just living with HTML=>text.

d_m has proposed reStructuredText as another contender for the source documentation format. It is probably sufficiently readable not to need a converter to generate the in-game help docs, but we would need the docutils package (which requires Python) to generate HTML and LaTeX, and then LaTeX to generate a PDF.

Oh, I must've missed his suggestion. I've checked it out quickly, it seems another good alternative. Only question, how is one supposed to obtain word wrap at the end of the screen? This seems like a pain to do manually when editing the help files.

Between this and the requirements, I'd still be slightly more in favor of the HTML=>TXT path only, but I think I can hack together something with RST, too, if you feel that it is a sounder alternative and/or having a pdf help file is a must. Just my 2 cents, though, waiting for opinions from the dev team.

[myshkin]

Many, many thanks for this. I too am a big LaTeX fan and had been putting pressure on myshkin to stick with it, on the assumption that there *must* be a tex-to-text converter out there somewhere! But your research and your example of converted HTML have convinced me otherwise - and I'm pretty sure myshkin would agree with your logic too, and would share my appreciation of your offer to do the one-time conversion and the patch.

I second Magnate in thanking you for the research and analysis. d_m has proposed reStructuredText as another contender for the source documentation format. It is probably sufficiently readable not to need a converter to generate the in-game help docs, but we would need the docutils package (which requires Python) to generate HTML and LaTeX, and then LaTeX to generate a PDF. Thoughts on which seems like a better path? I am not all that fond of HTML as a source format, but it does work, and is certainly better than what we have now. Absent strong arguments, the person doing the conversion will likely get to make the choice.

I might also suggest that another round of copyediting and rewriting should precede any conversion effort, but perhaps the two operations are mostly orthogonal, and I am unlikely to find enough time to make major edits myself for at least a week and a half.

[Magnate]

I've googled around and experimented a bit with these kind of document conversions.
...
-as much as I love LaTeX, this strongly suggests ditching it and switching to html as the "source" documentation language and convert it to plain text using Elinks. Elinks would be the only external dependency required if we go this way.
...
-if you guys decide to go this way, the first step to do is converting (once and forever) the LaTeX help files to html. I can do this, and then create a patch that automates the HTML=>txt conversion. The resulting inline help files would look something like this:
...
As before, I am waiting for some feedback before wasting time to do a useless/not appreciated conversion...

Many, many thanks for this. I too am a big LaTeX fan and had been putting pressure on myshkin to stick with it, on the assumption that there *must* be a tex-to-text converter out there somewhere! But your research and your example of converted HTML have convinced me otherwise - and I'm pretty sure myshkin would agree with your logic too, and would share my appreciation of your offer to do the one-time conversion and the patch.

Thanks again - it will be great to have a single source of help for 3.4, which can provide all of html, text and PDF.

I don't have a view on whether depending on elinks is better or worse than on w3m, but if you prefer elinks we'll go with that. What would we need to build the PDF?

[fph]

I am a little worried about requiring LaTeX, actually. While I like the power of LaTeX for producing the manual, I would prefer that people not need to have LaTeX installed to build and install the game from source. It's not clear to me whether it's better to distribute the output of the LaTeX-to-text converter as part of the source distribution, or to use a lighter-weight format as source, to be converted to LaTeX, text, HTML, PDF, etc. as desired.

I've googled around and experimented a bit with these kind of document conversions. Quick summary:
-a direct tex-to-plain text converter that gives a nice human-readable output (ascii-art tables, readable headers, line-wrapping at 80 chars) doesn't seem to be around in the wild.
-(not-too-complicated) LaTeX code can be safely converted to html or rtf with a number of tools.
-OTOH, complicated LaTeX code is a mess to handle for everything that is not, well, a TeX compiler.
-html, including tables, can be converted to pure text with little effort and good results with "w3m -dump" or "elinks -dump". Maybe some CSS (supported partially by Elinks but not by w3m) can be used to force things to look different between the HTML and the generated TXT version.
-docbook is a XML-based format for documentation that can be "compiled" to html, windows help format, and ugly pdf.
-as much as I love LaTeX, this strongly suggests ditching it and switching to html as the "source" documentation language and convert it to plain text using Elinks. Elinks would be the only external dependency required if we go this way.
-we could also go (something else)=>HTML=>txt, where (something else) could be Markdown, Docbook, or Webgen, for instance, but I don't see where this would help. Well, maybe Webgen. But it's Ruby-based, and we'd need Ruby as an external dependency -- it's probably not worth it to handle 10 pages of html.
-if you guys decide to go this way, the first step to do is converting (once and forever) the LaTeX help files to html. I can do this, and then create a patch that automates the HTML=>txt conversion. The resulting inline help files would look something like this:

   Magical Devices
           Using a magical device such as a wand or staff requires experience
           and knowledge. Spell users such as mages and priests are therefore
           much better at using a magical device than say a warrior. This
           skill is modified by intelligence, and increases with the level of
           the character.
   Searching Frequency (Perception)
           Perception is the ability to notice something without actively
           seeking it out. This skill is based entirely upon race and class,
           and will never improve unless magically enhanced.
   Searching Ability (Searching)
           To search is to actively look for secret doors, floor traps, and
           traps on chests. Rogues are the best at searching, but mages,
           rangers, and priests are also good at it. This skill is based
           entirely upon race and class, and will never improve unless
           magically enhanced.

  2.7**Stat Bonus Tables

   ** Stats, hit dice, infravision and experience point modifications due to
   race and class are listed in the following table. To get the total hit
   dice and XP modifier, add the "race" and "class" numbers: for instance, a
   Dwarf Priest has a hit die of 11+2=13 (i.e. he will get 1d13 hit points
   per level, adjusted for constitution) and an XP modifier of 20+20=40%.
   **

   +----------------------------------------------------------------------+
   |            | STR | INT | WIS | DEX | CON | CHR | HD | XP/lvl | Infra |
   |------------+-----+-----+-----+-----+-----+-----+----+--------+-------|
   | Human      |  0  |  0  |  0  |  0  |  0  |  0  | 10 |  +0%   | None  |
   |------------+-----+-----+-----+-----+-----+-----+----+--------+-------|
   | Half-Elf   | -1  | +1  |  0  | +1  | -1  | +1  | 9  |  +10%  |  20'  |
   |------------+-----+-----+-----+-----+-----+-----+----+--------+-------|
   | Elf        | -1  | +2  | +1  | +1  | -2  | +1  | 8  |  +20%  |  30'  |
   |------------+-----+-----+-----+-----+-----+-----+----+--------+-------|
   | Hobbit     | -2  | +2  | +1  | +3  | +2  | +1  | 7  |  +10%  |  40'  |
   |------------+-----+-----+-----+-----+-----+-----+----+--------+-------|
   | Gnome      | -1  | +2  |  0  | +2  | +1  | -2  | 8  |  +25%  |  40'  |
   |------------+-----+-----+-----+-----+-----+-----+----+--------+-------|
   | Dwarf      | +2  | -3  | +2  | -2  | +2  | -3  | 11 |  +20%  |  50'  |
   |------------+-----+-----+-----+-----+-----+-----+----+--------+-------|
   | Half-Orc   | +2  | -1  |  0  |  0  | +1  | -4  | 10 |  +10%  |  30'  |
   |------------+-----+-----+-----+-----+-----+-----+----+--------+-------|
   | Half-Troll | +4  | -4  | -2  | -4  | +3  | -6  | 12 |  +20%  |  30'  |
   |------------+-----+-----+-----+-----+-----+-----+----+--------+-------|
   | Dúnadan    | +1  | +2  | +2  | +2  | +3  | +2  | 10 |  +80%  | None  |
   |------------+-----+-----+-----+-----+-----+-----+----+--------+-------|
   | High-Elf   | +1  | +3  | -1  | +3  | +1  | +5  | 10 | +100%  |  40'  |
   |------------+-----+-----+-----+-----+-----+-----+----+--------+-------|
   | Kobold     | -1  | -1  |  0  | +2  | +2  | -2  | 8  |  +15%  |  50'  |
   +----------------------------------------------------------------------+

As before, I am waiting for some feedback before wasting time to do a useless/not appreciated conversion...

EDIT: there's a couple of extra asterisks that show up in the wrong place in the converted txt sample here above. I don't know why, I don't see them in the original txt. Maybe the forum code inserted them automatically, or they come from some funny UTF character in the txt. Anyway nevermind about them, there are surely automated way to make them disappear. For now just look at the txt as a proof of concept.

[fph]

What exact points different race and class get for skills and /level change to them (if there is one). I never remember those (except saving throw, which I remember quite well).

I usually check those when starting new char to help choosing what to play next.

Oh. But if I am not missing anything, those are now displayed in the race/class selection screen in the new nightlies, without need to look in the help.