Make example config files more accessible

[myk002]

trafficstars

People don't use things unless it's zero effort. If we want the example config files to be useful and used, they should be more accessible.

1. Orders files can be moved from hack/examples/orders to dfhack-config/defaults/orders. This will allow them to be used immediately by the orders plugin without having to be manually copied, and if the user has files of the same names in dfhack-config/orders, they won't be overwritten by upgrades. Users will have to delete the files in dfhack-config/orders if they want to get updated orders that were installed in defaults, but they'd have to do that today anyway. Alternately, we could put the example orders in hack/data/orders and read them in addition to files in the dfhack-config/orders directory. Name conflicts would prefer files in dfhack-config.

2. Professions files are a little trickier since they aren't integrated with the dfhack-config directory. If we install the example professions directly to the professions/ directory, they could overwrite user files. I propose migrating the professions folder into dfhack-config. Manipulator could check for the old directory and either prefer name-conflicting files there or automatically move files to the new location when the manipulator UI is invoked, showing a pop-up to say what it had done. Again, alternately we could add the files to hack/data/professions and read them in addition to user-written files.

3. onMapLoad_dreamfort.init could be moved to the top level directory, but renamed to onMapLoad_dreamfort.init.example. I don't think we should enable it by default, though it is possible we could move some of its contents to a default onMapLoad.init file if we want to be a little more opinionated about the default DFHack experience.

The documentation wouldn't change, except to remove the copying instructions. Dreamfort instructions would have to be likewise updated.

[myk002]

It is inevitable that some users will not like these defaults. We should provide a way for the defaults to be hidden or removed so they don't get in those users' way.

For the orders, extra defaults don't really get in the way. They show up in the orders list output, but there aren't many items in that list, so the risk of annoying users is low. Moreover, the default orders don't dictate any particular playstyle, and are unlikely to be controversial. I don't think we need to invest any time in making them easy to remove/hide. If a user really wants them gone, they can delete the JSON files in dfhack-config/defaults/orders (as well as the files in dfhack-config/orders).

The default professions are a different story. Not only are they opinionated (i.e. dictating specific labor groupings and profession names), but they also are very visible. The user will have to scroll through them every time they select a profession to apply to a dwarf. If the user doesn't want to use those default professions, there will just be an annoyance.

[myk002]

Idea to make defaults not annoying for manipulator:

allow hiding professions from the UI. In the professions selection dialog, you can toggle whether hidden professions are shown and you can hide/unhide individual professions

[lethosor]

For orders, I kind of like the idea of having the defaults in hack/ and searching both places. If we put them in dfhack-config/default/, then people would have to delete them from two places to make them go away. I think that folder works better for standalone config files, and not quite so well for groups of files where new things are added in new files.

Then there is the question of whether we expect users to muck around in hack/ to disable built-in orders. I like quickfort's approach of a toggle to hide/show "library" blueprints.

[myk002]

I remember I considered that layout for quickfort as well - user blueprints in the top level blueprints/ directory and library blueprints in hack/. I eventually decided to put the library directly in blueprints/library for two reasons:

1. so uses could discover the library when they view their own files
2. so there would not be confusion if the user created their own library/ subdirectory

I think it's the same situation here. We can use this approach for professions since the directory layout is similar. Orders being in dfhack-config makes it more difficult.

Could we consider moving the orders out of dfhack-config? As you said, it doesn't really belong there. However, how many subdirectories in the main DF folder are we willing to create?

[lethosor]

As you said, it doesn't really belong there.

This?

I think that folder works better for standalone config files, and not quite so well for groups of files where new things are added in new files.

I was referring to just the dfhack-config/default/ folder there, actually. Somewhere else in dfhack-config/ doesn't run into the problem of deleted files being recreated.

I do want to limit the spread of subdirectories in the DF folder somehow. Ideally user-created files would be isolated to dfhack-config or somewhere similar. I'd like to consider hack "safe to delete" in case someone needs to do a clean install. ("safe" to a certain extent - you'd lose custom scripts, but those can live elsewhere.)

[myk002]

How's this for a policy:

• if the user data is created externally to DFHack or the user is expected to edit the file directly (and it's not a lower-level config like quickfort.txt), the file/directory for the user data should be in the main DF folder
• if the user data is created, read, and written only by DFHack commands, it should go in the dfhack-config/ folder
• library files should go in a library/ subdirectory within the user data folder. Library files should be installed once with DFHack but not reinstated if they are deleted after installation (i.e. if the user data folder is in dfhack-config then the library folder must not appear in dfhack-config/defaults)

With this policy, the folder structure would look like this:

blueprints/
  library/
dfhack-config/
  orders/
    library/
  professions/
    library/
dfhack.init
onLoad.init
onMapLoad.init
hack/
  init/
    DFHack-owned default init files

That is, blueprints are unchanged, professions moves into dfhack-config, and orders and professions gain library subdirectories.

I added the proposed init file layout from #2120 as well so we can visualize how all this might fit together.

The only downside I see is that users now have to type orders import library/basic instead of just orders import basic, but it does make it much more explicit that a library config is being used.

Orders and professions would gain "hide library" functionality, and orders would restrict orders export from writing to the library subdir. blueprint should restrict writing to the blueprints/library as well.

[cppcooper]

People don't use things unless it's zero effort. If we want the example config files to be useful and used, they should be more accessible.

Didn't even realize there were json config files until very recently. I see you linked to an example rst, it might only be in develop.. but I don't see it on dfhack readthedocs, I'd expect a link to it here Or perhaps something related to plugin development.

No opinion on the policy stuff.

More generally, if this isn't already a thing. We should provide a quick serve json to plugins. eg. auto json = DFHack::GetConfig(plugin_self) (personally I prefer nlohman, but I think we've already got one integrated. Then we'd want to example this in the skeleton plugin and ideally document it.. but the documentation I think is in need of large wide sweeping improvements particularly for development.

[myk002]

The last item here (onMapLoad_dreamfort.init) could be integrated as a preset for the upcoming configuration management tool. Then we can finally remove the examples directory entirely.