Making pdf of help files

[qwerty]

From:

http://angband.oook.cz/forum/showthread.php?t=4494

Turn the help files into HTML and PDF - ok so this does require knowledge of HTML, but not C.

I decided to give this a go using tex and have made all the files into a pdf. I have made a github repository for all the files located here: https://github.com/qwerty16/Angband-Help----PDF

The pdf file is named angbmanual.pdf, all the rest of the files are used to create the pdf using latex. There are instructions on how to make the pdf from the other files in the README.

Any comments, suggestions or spotted errors are most welcome.

[jens]

This is great :-) Now if someone can update the content as well :-)

[Nolendil]

It looks good, nice job.

[Magnate]

This is great :-) Now if someone can update the content as well :-)

@qwerty: many thanks for your work - this has kick-started four years of stalled progress!

For more up-to-date content, please see http://rephial.org/wiki/UserManual. I'm not sure how much of this would be useful in a PDF - but I'm sure the current content could be enhanced a little. (Apologies for not putting this link into the initial tasks thread.)

[fph]

For more up-to-date content, please see http://rephial.org/wiki/UserManual. I'm not sure how much of this would be useful in a PDF - but I'm sure the current content could be enhanced a little. (Apologies for not putting this link into the initial tasks thread.)

I think I could contribute to this project, too, especially on the LaTeX formatting enhancement side. However, I feel that we should before:
(1) decide which documentation is going to be ported to PDF
(2) decide, after the conversion, that the LaTeX/PDF version is the "final one" and that all subsequent changes should be made to that one and then converted back to raw text or HTML if needed.

Otherwise I fear we will end up with two separate diverging versions of the documentation. Dealing with diff's and patches in the documentation isn't very practical, since LaTeX conversion involves some regexp substitution in the process (e.g., escaping all lower-than and greather-than symbols).

[d_m]

I think I would be fine with having LaTex be the primary documentation, providing that the conversions to HTML and TXT are good. I've worked with LaTex and like it pretty well.

While Takkaria and the devteam probably need to communicate our intentions about what we want updated/added/changed in the documentation, whoever takes this on will get substantial leeway (and responsibility) to decide these things themselves.

EDIT: Sorry I obliquely answered your question about which documentation to update. Honestly, I don't have a good perspective on which is the best place to start.

[Derakon]

The LaTeX version, exported to PDF, would certainly be more convenient than the in-game help -- you can search it more readily, and you can easily switch back and forth between your game and a specific point in the help. I vote for it being the primary help docs. In fact we could simply refer the user to the PDF when they hit '?' and do away with the in-game help altogether. Online HTML help should probably still be made though.

[takkaria]

The LaTeX version, exported to PDF, would certainly be more convenient than the in-game help -- you can search it more readily, and you can easily switch back and forth between your game and a specific point in the help. I vote for it being the primary help docs. Online HTML help should probably still be made though.

The thing that gets the most hits past the front few pages on rephial.org is the manual, so I'd consider it essential to have good-quality HTML help too. And if we just shipped as PDF, I'd feel sorry for all the people who are going to be using Acrobat Reader on Windows.

My original plan, as outlined on the ticket, was to make HTML documentation primary and use Prince to convert it to PDF, but that seems to be even more of a specialist thing than LaTeX.

In fact we could simply refer the user to the PDF when they hit '?' and do away with the in-game help altogether.

I agree. The help tickets are all about getting rid of in-game help – I've been wanting to kill that code for so many years now...

[takkaria]

@qwerty: many thanks for your work - this has kick-started four years of stalled progress!

For more up-to-date content, please see http://rephial.org/wiki/UserManual. I'm not sure how much of this would be useful in a PDF - but I'm sure the current content could be enhanced a little. (Apologies for not putting this link into the initial tasks thread.)

I think there needs to be some discussion around what should be in documentation and what shouldn't. I think it should aim to explain how the game works while still leaving surprises. The online docs have a few too many lists of game content by this measure and they should definitely be left out, IMO.

[Magnate]

The thing that gets the most hits past the front few pages on rephial.org is the manual, so I'd consider it essential to have good-quality HTML help too. And if we just shipped as PDF, I'd feel sorry for all the people who are going to be using Acrobat Reader on Windows.

http://www.foxitsoftware.com/products/reader/

I agree. The help tickets are all about getting rid of in-game help – I've been wanting to kill that code for so many years now...

I thought you wanted the HTML help to be available in-game? Isn't that what the desire for context-sensitive help is about? Did you mean you just wanted to get rid of the help menu?

[takkaria]

http://www.foxitsoftware.com/products/reader/I thought you wanted the HTML help to be available in-game? Isn't that what the desire for context-sensitive help is about? Did you mean you just wanted to get rid of the help menu?

What I mean by context-sensitive help is smaller snippets of information available when they would be useful - either using '?' or in a term window. Maybe the player can hit '?' in-game and the game will pull up relevant help for the last 5 things that happened, something like that. Either way, the current help reader would be junked, since we wouldn't be browsing massive help files anymore.

I'd like context-sensitive help but not displayed using the current (kind of icky) help reader. I think it's pretty unreadable and it's more useful to provide shorter help and leave long help to PDF/HTML.

[qwerty]

To be honest I find the in game help occasionally useful, more so when I hadn't played as much, to find out commands etc. So if the in game help is scraped perhaps a list of commands and descriptions should be avaliable in game to avoid the hassle of having to open a large pdf in another window.

@Magnate: Thanks for the link, I'll see what I can add.

@fph: any suggestions, patches, comments etc are welcome thanks.

[takkaria]

To be honest I find the in game help occasionally useful, more so when I hadn't played as much, to find out commands etc. So if the in game help is scraped perhaps a list of commands and descriptions should be avaliable in game to avoid the hassle of having to open a large pdf in another window.

Aye, we should definitely keep an in-game list of commands.

[Timo Pietilä]

Aye, we should definitely keep an in-game list of commands.

I would prefer keeping in-game help as well. PDF is good format for manuals, but for help I think you need lighter version, all pdf-readers are bloatware compared to angband (even that mentioned foxit reader). They also have absolutely nothing to offer over over good in-game help.

[qwerty]

Okay so I've been putting the online docs into their own pdf and slowly adding bits into the help and cross-referencing/indexing as I go. The original link is still good to reach the files though(I have rearranged a little and the readme's are NOT up to date but I think it is pretty intuitive).
Either way there isn't much more done on the help but the manual is about half done (ignoring indexing/crossrefing obviously).

I'm not entirely sure what wants to be added all the time so any hints or suggestions are appreciated.