RST help files

[fph]

(well, this time I decided to open a new thread instead of keep on going OT on this old one)

There is still some minor work to be done, but I think I have an usable version of the RST online help. Apart from the converted help files, there is:
-"make manual.html" and "make manual.pdf" that create HTML and PDF version
-the online help viewer skips "RST directives" (only when they are one-liners, for now, though)
-some modifications to files.c to parse menu and link targets directly from (a very limited subset of) RST.

What still needs to be done:
1. beautify the output: a better CSS and LaTeX preamble, maybe a couple of images.
2. instruct the online help viewer to render a couple of RST constructs in a more readable version (namely, |something| and "\ ", "\\").
3. skip RST directives as whole paragraphs.
4. there's a couple of warnings, that I think are due to outdated information in the docs (do we still have view_special_light and view_granite_light?). I could easily remove them, but I'd like someone to confirm me that they can go.
5. how can I get "make clean" to work properly, without mkmk complaining? The previous help files managed, but I can't understand what did the trick in the Makefile.
6. pressing ? at the right moment during character creation should lead directly to the classes and races description, but this doesn't work in the master branch either -- can you confirm that?
7. at some point, a weird bug in my editor removed some lower-case "s" letters at word start (e.g.: similar -> imilar). I think I have now fixed all the damage, but if you're skimming through the help files please keep your eyes open for words (not) beginning with "s".

The help file branch is online at https://github.com/fph/angband. After we fix items 4 and 5 (I need a quick consult for that), probably I can issue a pull request. Items 1, 2, 3 and 6 can be a later goal (there is no obvious regression).

[fph]

Oh, and about the *slay* problem: I think I have solved it using RST substitution directives: currently, the string "*slay*" is displayed as "|*slay*|", with an extra pair of |...|, in the help files, and correctly in HTML/PDF. If I/we implement item 2 in my list (which doesn't sound complicated), we can get rid of the |...| as well. Probably the cleanest way is converting them to spaces in the online help viewer.

[d_m]

Originally Posted by fph

(well, this time I decided to open a new thread instead of keep on going OT on this old one)

There is still some minor work to be done, but I think I have an usable version of the RST online help.

Awesome! Later tonight I will take a look at this.

I can confirm that in-game help during character creation is borked. I'm not sure if there's a ticket open yet, but there should be. Definitely worth fixing (and probably backporting to 3.3.1 if it's broken in 3.3.0 too).

Thanks for your hard work!

[Magnate]

Originally Posted by d_m

Awesome! Later tonight I will take a look at this.

I can confirm that in-game help during character creation is borked. I'm not sure if there's a ticket open yet, but there should be. Definitely worth fixing (and probably backporting to 3.3.1 if it's broken in 3.3.0 too).

Thanks for your hard work!

+1 that's fantastic work - many thanks.

[Nomad]

Originally Posted by d_m

I can confirm that in-game help during character creation is borked. I'm not sure if there's a ticket open yet, but there should be. Definitely worth fixing (and probably backporting to 3.3.1 if it's broken in 3.3.0 too).

It's been borked for a long time. I'm pretty sure it stopped working somewhere between 3.0.9 and 3.1.2v2.

[fph]

Originally Posted by Magnate

+1 that's fantastic work - many thanks.

No need at all -- it's nothing compared to the work you guys do regularly to maintain Angband and develop new features.

Going on to fix the last rough spots...

[fph]

I've fixed in my list 3, 4, 5 and part of 2 (handling backslashes is kinda tricky). I think this can now safely be pulled into the main development branch (of course after you review the code -- there's some C involved, and it could be buggy or not following your code style).

How is the protocol for that?

[d_m]

Originally Posted by fph

I've fixed in my list 3, 4, 5 and part of 2 (handling backslashes is kinda tricky). I think this can now safely be pulled into the main development branch (of course after you review the code -- there's some C involved, and it could be buggy or not following your code style).

How is the protocol for that?

The best way to do it is to open a pull request on Github. You should be able to find instructions on how to do it, but the basic gist is:

1. make your changes in a branch
2. commit your changes
3. push your branch up to your github account
4. open a pull request against the staging branch of angband/angband

That's it! We get notifications whenever someone does this, so then we can go review things, comment on the pull request and/or merge it.

[Magnate]

fph - thanks again for your work on this.

...

You don't by any chance fancy converting the spoilers do you? They haven't been updated in 3.0.8, and would appreciate some love ... ;-)

[fph]

I'll try - but is the information they contain up-to-date?