angband strategy guide

[Tibarius]

Dear Folks,
i am in to write / make an Angband strategy guide. I wanted to do that for years already ... now is the time

I started this thread to collect Input from other fellow Players. What should be included, what not, suggestions for layout, Content - everything is welcomed.

First question:
PDF Format or .txt file for ordinary text Editor?
pro PDF: i could add Pictures and screenshots, quite easily
pro txt: everyone can use it, regardless of the operating System

Cheers,
Tibarius

[Nick]

IIRC someone did something like this a couple of years ago - anyone recall? That might be a good starting point.

[Derakon]

Well, I wrote TANG over a decade ago (!), but it's woefully out of date and should not be relied on for anything.

I wouldn't worry too much about the specifics of the format; just write in whatever is easiest for you to work with. As for what to include, a starting guide for each of the classes would be good -- what to buy, what to watch out for, general playstyle guidelines. Some warning that mages are hard would be a good idea too.

[Nick]

I think this was what I was thinking of. We probably should advertise that better.

[fph]

Originally Posted by Nick

IIRC someone did something like this a couple of years ago - anyone recall? That might be a good starting point.

Not sure if this is what you remembered, but three years ago I took care of converting the Angband in-game guide to a different format. We discussed which one, and then we decided for ReStructured Text (RST, the standard format for Python documentation). It is a markup language that is meant to be readable when opened as plain-text, but easy to convert to other formats (html/pdf). It is similar in spirit to Markdown, which is more common today due to support in several popular sites.

One of these two formats would be my suggestion for this guide, too.
The in-game guide required a few ugly hacks, since we did not want to implement a full RST-to-screen parser inside Angband or depend on an external library, but this is not a concern here.

Thanks for the effort to help the Angband community, Tibarius!

[Tibarius]

Nick: Yes, a very good starting Point indeed - to know what resources already are available is indeed valuable. I DID read that guide some years back, but had forgotten about it.

So, i guess i first have to gather the requirements and define the Goals this product should meet. Well i wanted to produce an "advanced" guide for Players like myself - who seek Information beyond those, which are available for example in this player's guide on the help-site of the angband Webpage (which Nick reffered to).

Nevertheless - a complete guide would cover this Topic too i guess.

fph: I am using windows7 on a home pc. As writing application i am using open-Office for all my personal texts. It offers a cool PDF conversion function, which i had in mind using for this guide. So it would be either a plain text file i am able to produce or a nice looking PDF document. Which is what i would go for at this Point. A single document you can download and print easily if you like to. Most Windows users i know of have a browser and are easily able to download and install the acrobate PDF Reader. I must admit tho, that a document readable with a browser alone would even be more simple to open and distribute.

[mrrstark]

Originally Posted by Tibarius

So it would be either a plain text file i am able to produce or a nice looking PDF document.

If you go with a "plain" text file, but follow a syntax like Markdown or others, you can with a single click in many editors turn that plain text into an HTML or PDF file, or just leave it as a nice and consistently formatted text file.
I guess my point is just that, IF you go with plain text, don't make your own format up since you can follow an existing format and voila, get a bunch of insta-pretty-conversion benefits.

A Markdown Cheatsheet: http://assemble.io/docs/Cheatsheet-Markdown.html
An example of an online Markdown -> HTML converter: http://dillinger.io/
(Many exist, and many are integrated into text editors, like Github's Atom, or Sublime Text 3)

[the Invisible Stalker]

I played for years very badly. Then by chance I discovered Eddie Grove's Tales of the Bold and changed my play style completely. It's not suitable for absolute beginners, and the game has changed in various ways since it was written, but I think it remains the best guide for an intermediate player.

[Magnate]

Originally Posted by Nick

I think this was what I was thinking of. We probably should advertise that better.

Didn't somebody add that to the shipped docs a release or two ago? I thought I saw it in a changelog somewhere.

[Tibarius]

Ok, it is almost midnight now ... basically i worked the whole day on my guide and finished 1 and 1/2 sections of 5. I am writing in the open document file format used by open Office and am able to convert it into PDF finaly to have a nice looking document / file for Distribution amoung the Angband Folks.

This has the following advantages for me as writer:
- i see how the finished guide looks like (i guess i can expect the guide to look very similar and readable on every device which supports PDF files)

After studying fph's and mrrstark's posts i must admit i understood only half of what their statement's and links said, but i am realy impressed by the online dillinger example of how markdown is converted into HTML text.

So i try to explain in my own words what i understood and what questions i got, maybe i will write the first version of the guide in PDF but convert it into another text format afterwards if i am convinced this work would pay off in additional benefits like easier availability for users not being able to use PDF files.

If i speak from plain text, i refer to a text containing only letters and the two control characters #13, #10 Carriage-Return and Line-Feed. Even the most basic text editors i know of are able to show a file that uses this syntax. You cannot use bold, italics, underlined or similar features in the document.

I did not understand what Assemble docs! actually is. It somehow has to do with using HTML Tags (or similar things) to produce a nice looking final document.

I found the online dillinger example very impressive tho, and i guess i have understood what we are talking about there. The left side using "Markdown" syntax or text formatting is basically "plain text" as described earlier from me.
Just that there are a couple of syntax agreements used which can be used by - what program/editor exactly? - to produce an very nice looking HTML output (dispolayed on the right side).

If you open a markdown file with a simple text editor you get the "simple" text file as shown on the left side. Does the right (nice looking side) automatically open if you open a markdown file with a HTML capable web-browser (or is there something to do from the user)?