README.html lacks usable installation instructions

[Thundercraft]

I've installed a lot of mods over the years, for Dwarf Fortress and many other games. And while I have seen a number of mods that lacked a readme, it's not often that I see a mod with a readme that does not specify how to install it.

More important than specifying why the mod was written, more important than detailing all the features, even more important than specifying what a mod does and what it is for, is how to actually use (i.e., install) it. Your forum topic also lacks install instructions.

Exactly where does each of the files in the download go? Where do the files in the "0.43.05-r2" (or similar) folder go? Where do the files in the root folder go? What am I supposed to do with the 'realcolors.lua' file? (Is it essential, or not?) Is the 'curses_800x600.png' even necessary? (Isn't it identical to the 'curses_800x600.png' that comes with vanilla DF?)

For end users who only want to install TwbT to make their graphics set work, is there a certain install order? Should we install TwbT first, then install our graphics set? Or is that backwards?

For that matter, why didn't you organize the download into folders that are easy to install? Perhaps something like this?

.. {root}
. README.html
/data/art/
. shadows.png
. transparent1px.png
. white1px.png
/dfhack 64-bit 0.43.05-r2/
/dfhack 64-bit 0.43.05-r2/ hack/plugins/
. mousequery.plug.dll
. twbt.plug.dll
/example files/
/example files /data/art/
. curses_800x600.png
. SpacefoxNext_16x16-bg.png
. SpacefoxNext_16x16-top.png
. SpacefoxNext_16x16.png
. Spacefox_16x16_text.png
/example files /data/init/
. init.txt
. overrides.txt

Note that in my example above I made /hack/plugins/ a subfolder to make it clear where those dfhack files go. Similarly, I made /data/art/ and /data/init/ subfolders to make it clear where those files go. And I moved the extra Spacefox .png's and overrides.txt to a separate "example files" folder so as not to confuse end users who only want to install TwbT to work alongside their TwbT-based graphics sets. If users were to extract your empty overrides.txt file over a graphics set's customized overrides.txt, then the TwbT plugin will not do any overrides.

I appreciate TwbT. I have deep respect for the effort and ingenuity it took to make and maintain this. But it would have also been appreciated if this was easier to install or if we were walked through how to install it.

[mpicard]

Wow three months later and no response? I have to bump this because I want to setup my own dfhack installation as opposed to using the LNP and I would love any instructions about TWBT. @Thundercraft did you manage to get it working yourself moving the files to the folders you suggested?

[simone16]

@mpicard I also prefer to install only the features I use.
Last time I installed df (v44.02 linux-64), dfhack (v44.02-alpha1 linux-64 gcc-5.4), twbt (v6.26 linux) and Spacefox graphics set (v44.02g) by following these steps:

1. extract df as df_linux/.
2. extract dfhack in df_linux/, overwriting any duplicates.
3. extract twbt in df_linux/ following these instructions Readme File lacks install instructions #12 , overwriting any duplicates.
4. extract Spacefox in df_linux/, overwriting any duplicates.
5. change line 67 in df_linux/data/init/init.txt from [PRINT_MODE:2D] to [PRINT_MODE:TWBT].

Running df_linux/dfhack starts the game, both twbt and spacefox seem effective, however when quitting dfhack complains that the plugin twbt failed to close (I am not sure this depends on the installation procedure).
I used this procedure on older versions as well and it usually works as long as the releases of each package refer to the same version.

[lethosor]

when quitting dfhack complains that the plugin twbt failed to close (I am not sure this depends on the installation procedure).

That always happens, because of

df-twbt/plugin.hpp

Line 215 in 2bdffc8

return CR_FAILURE;

[BrunoDSL]

@mpicard I also prefer to install only the features I use.
Last time I installed df (v44.02 linux-64), dfhack (v44.02-alpha1 linux-64 gcc-5.4), twbt (v6.26 linux) and Spacefox graphics set (v44.02g) by following these steps:

1. extract df as df_linux/.

2. extract dfhack in df_linux/, overwriting any duplicates.

3. extract twbt in df_linux/ following these  instructions #12 , overwriting any duplicates.

4. extract Spacefox in df_linux/, overwriting any duplicates.

5. change line 67 in df_linux/data/init/init.txt from `[PRINT_MODE:2D]` to `[PRINT_MODE:TWBT]`.

Running df_linux/dfhack starts the game, both twbt and spacefox seem effective, however when quitting dfhack complains that the plugin twbt failed to close (I am not sure this depends on the installation procedure).
I used this procedure on older versions as well and it usually works as long as the releases of each package refer to the same version.

Why refer to another issue (which has complementary instructions as lacking as the official ones) when you could provide full instructions?

It's also interesting to note that I couldn't find anything remotely close to install instructions in the current README. The document in question seems to double as reference as well, which is not desirable and it's full of information that's not useful to someone just wanting to learn about the plugin or install it. That reference part should be its own document named like such. Also, the proper download links require you to scroll down 25% of the README and are hard to see, due to them being shoved in the middle of something that shouldn't be together with it (author and contact information). I ended up cloning the repo by mistake instead of downloading from the releases part at first.

[simone16]

I hope this will be of help to future users.
For df (v44.02 linux-64), dfhack (v44.02-alpha1 linux-64 gcc-5.4), twbt (v6.26 linux) and Spacefox graphics set (v44.02g):

1. extract df as df_linux/.
2. extract dfhack in df_linux/, overwriting any duplicates.
3. extract twbt in df_linux/ following these instructions (Readme File lacks install instructions #12) , overwriting any duplicates:

3.1. Extract DLLs to hack/plugins. If your package includes multiple sets of DLLs, make your best guess as to which is newest (betas tend to come after alphas, higher numbers imply newer versions, etc.) and use that one.
3.2. Extract PNGs to data/art.
3.3. Extract LUA to hack/lua.
3.4. Extract "overrides.txt" to data/init.

4. extract Spacefox in df_linux/, overwriting any duplicates.
5. change line 67 in df_linux/data/init/init.txt from [PRINT_MODE:2D] to [PRINT_MODE:TWBT].

@MR4Y As regards the releases, the code section of most github projects has a "releases" subsection (along with commits, branches and contributors), so the link to it is not usually included in the README at all.

[BrunoDSL]

@simone16 That presumes that whoever is browsing the page has prior knowledge of how the project repo is structured and/or knowledge of github in general. What if they don't? Since the appropriate link to whatever they need requires you to pinpoint it on a huge README full of other information that has no use for them currently, they can easily lose it, like I did.

[Archloy]

I think, an "install.md/html" into the windows release will help a lot. On my Arch Linux, I have an "aur" package with DFHack and TWBT, just look config files and play. I want to try it on my MS windows install and I got a folder with some files. I shall understand how the plugin works to do what I want. Maybe an "incomplete" install will works, I don't know, but an install section that point functionalities (to read how it will be configured), and only say "override.txt > init/override.txt plugin conf file @see §override" etc, etc.
It's a really great works on this plugin, but too complex to install :)

[draeath]

Indeed, this needs work. I knew to drop the .so in df_linux/hack/plugins and what edits to make to init.txt, but had no idea what to do with the other files. I had to catch the output in the dfhack console to know the non-spacefox png files needed to go into data/art. I had to find a reddit post to know the lua should go into hack/lua, and override.txt had a comment inside itself indicating where it should go.

This kind of thing should really be put in README.md or such.