Scripts: valid options for the assign-* scripts

Many of the assign-* scripts accept various tokens that can be found on the df wiki. Their help docs provide article/anchor urls to allow users to read more about what they're presumably trying to assign. This does however require the player to stop playing and open their browser so they can browse to the page(s) and read.

With a bit of digging I was able to find these lists (on the wiki pages) in the df table with devel/query. We should put commands in the docs for users to use to list the valid options so they have a more immediate way of accessing basic option listings.

beliefs: devel/query --table df.value_type facets: devel/query --table df.personality_facet_type goals: devel/query --table df.goal_type skills: devel/query --table df.job_skill attributes: devel/query --table df --maxdepth 1 --search [ physical_attribute_type mental_attribute_type ]

As was discussed [but separate from this issue] having these commands in the docs would pair nicely with a click-and-run mechanism for gui/launcher. More ideal, perhaps, would be to integrate the commands (above) into the scripts under a --list option for each command that has such lists to consider.

copied from shared feedback doc:

Gui/launcher While tab/shift+tab do navigate through the list of commands, perhaps dedicated controls could be offered and indicated to the player. When I went to read add-thought it looked like the help text was cutting off (by happenstance of it being exactly the same size as the window), I don’t know but maybe in the right corner we could put something like to avoid first use confusion. I don’t care for the “command/options” syntax, I think we achieve the same needs by using indentation for the descriptions; so I think the quotations are redundant. I think we should print a message to the console about text potentially displaying incorrectly with certain custom tilesets. (mine for example doesn’t display a lot of punctuation correctly [,.#]

Example sections Several docs appear to be using different formatting schemes for the examples. eg. Example

assign-goals --reset --goals [ MASTER_A_SKILL false ]

Clears all the selected unit goals. …

Example

“likes alabaster and willow wood”: assign-preferences -reset -likematerial [ INORGANIC:ALABASTER PLANT:WILLOW:WOOD ]

Example

Loads and applies the profile called “DOCTOR” in the … assign-profiel --profile DOCTOR --reset PROFILE

3dveins 3D Perlin noise, while totally searchable could be broken down to be more explanatory. What is Perlin noise, noise with localized features to appear more natural to the human eye than say TV static noise.

The information about undoing by restoring from backup should maybe standout more. For the GUI it should probably be seen in red or yellow to catch the eye, and a NOTE: or WARNING: to prepend to it.

Adaptation Not really about the docs if it’s truly all the script supports, but I noticed the option for selecting the highlighted dwarf is him. At some point, this is probably going to trigger someone into some sort of tirade. Perhaps we could change this to this or some other gender neutral term. Or I suppose support all the pronouns and all the newly made up ones kids are using these days. Neutral examples: this, that, one, highlighted, selected, it(maybe)

add-recipe native usage feels a bit disjointed in its explanation. I think it is saying that it ensures your civ gets all the recipes it should have, and then additionally picks extras from a pool.

doesn’t specify how to find the possible tokens add-spatter It is nice to know this works without need of intervention, but I’d kinda like to know more about what these “contaminants” are doing. add-thought the second usage command description, and this isn’t even remotely a problem, should be written to not say “add the specified thought/emotion” because it doesn’t show specifying a thought or emotion. It just has [] so I don’t think it makes sense to use this language. I’d probably copy the form the first usage command provides ie. Allows you to specify … for … Or Allows you to select or specify … and add ... Reading the options, it seems like add-thought always adds a thought, so the description at the top saying `thought or emotion` is not accurate. --strength has a typo: cooresponding The options I think could be worded a bit better, I think it would be preferable for them each to talk in terms of how they are used and not in terms of what they represent. To explain what I mean: “The emotion that the unit associates with the thought” → “Specifies an emotion for the unit to associate with the specified thought” gui/advfort “changes are only persisted” I am not a linguistic expert, but I think this use of persisted smells. It doesn’t sound right and I can’t find a similar example of it being used this way. I think because as persisted it is a verb..? or adverb?? but what I think the sentence calls for is an adjective (ie. persistent) The -e option I think should deal with the optional [name] at the top of the description instead of the bottom animal-control I might add something in the script description to elaborate on how it’s useful for deciding which animals to geld/butcher. (ie. mentioning stats; but it might not be important) armoks-blessing classes: it might be nice to say in the option that it is classes of skills, I had to read this info from `armoks-blessing ` to understand what it was autohauler This may be taking place in other docs, but I noticed it here. Take a look at this exercept: Autohauler allows a skill to be used as a flag to exempt a dwarf from “autohauler”’s effects. It is kind of weird to quote the command when it’s being used as a pronoun, especially when it’s possessive, yet the first use isn’t quoted.. presumably because it’s capitalized. The second should also not be quoted imho. Autolabor Under usage, the final paragraph is a bit terse. I find the “biased against masters of other trades” to be particularly ambiguous. I think I understand it after thinking about it, but it might be nice if it could be understood just be reading it autonestbox Having never used this, it is unclear to me whether it is oddly above (1 z layer above) or above (same z level, over top of the thing)

While tab/shift+tab do navigate through the list of commands, perhaps dedicated controls could be offered and indicated to the player.

Would a scrollbar like what was added to the help text be sufficient? That would allow you to quickly page through them.

When I went to read add-thought it looked like the help text was cutting off (by happenstance of it being exactly the same size as the window), I don’t know but maybe in the right corner we could put something like to avoid first use confusion.

Does the new scrollbar address this? It should show when you are at the bottom of the document. I also added some space above, below, and to the right of the text in order to make it look less like it is getting cut off.

I don’t care for the “command/options” syntax, I think we achieve the same needs by using indentation for the descriptions; so I think the quotations are redundant.

I'm sure you know this, but for others reading, the quotes are not there in the .rst markup. The text rendering transforms code literal text (e.g. The ``clear`` keyword clears the list ) into text like the "clear" keyword clears the list. I offer an alternate format in the documentation standards doc that avoids this, but it's not always appropriate for every context. For example, the "quote"-less format is only really applicable when multiple usage forms can be described with a single followup paragraph. I'm not really sure we can do much about this.

I think we should print a message to the console about text potentially displaying incorrectly with certain custom tilesets. (mine for example doesn’t display a lot of punctuation correctly [,.#]

This really isn't specific to gui/launcher. I'm sure people with those tilesets have noticed that the entire UI is rendered like this. Why do you think this warning should go in gui/launcher's help specifically?

Several docs appear to be using different formatting schemes for the examples.

Most of the time I tried to use what I recommended in the documentation standards, but there were some cases (like when the example involved several commands run in succession) that other formats worked better. The examples you pointed out do not fall under that category and probably should have followed the standard. PRs welcome for those.

The information about undoing by restoring from backup should maybe standout more. For the GUI it should probably be seen in red or yellow to catch the eye, and a NOTE: or WARNING: to prepend to it.

We can put this in an admonition:: block. I'm not sure it needs a WARNING, though, since the impact of running the command inadvertently is relatively low.

Adaptation Not really about the docs if it’s truly all the script supports, but I noticed the option for selecting the highlighted dwarf is him.

For O\other scripts that supported a plethora of synonyms for "the selected unit" I generally only documented a neutral one, but this one really only supports "him". Agree that this should be fixed in the code.

add-recipe native usage feels a bit disjointed in its explanation. I think it is saying that it ensures your civ gets all the recipes it should have, and then additionally picks extras from a pool.

It's saying that by default the civ picks from a pool, and add-recipe native gives you the entire pool. How would you rephrase this?

doesn’t specify how to find the possible tokens

Can you come up with a command to show the possible tokens?

add-spatter It is nice to know this works without need of intervention, but I’d kinda like to know more about what these “contaminants” are doing.

I'll add a note that vanilla raws do not include any SPATTER_ADD_ tokens. This plugin is only useful for mods that add this kind of behavior, and the added behavior is up to the mod.

While tab/shift+tab do navigate through the list of commands, perhaps dedicated controls could be offered and indicated to the player.

Would a scrollbar like what was added to the help text be sufficient? That would allow you to quickly page through them.

I did not update the doc to reflect changes that were merged after I wrote things in the doc. I think you could just ignore the stuff that seems redundant; I think things are moving in the right direction without making a point of specifically addressing those lines.

Does the new scrollbar address this? It should show when you are at the bottom of the document. I also added some space above, below, and to the right of the text in order to make it look less like it is getting cut off.

Unfortunately that's a first experience thing, and I've already had mine. So however I answer it'll be biased. I'd ask a first time user of the launcher. I do think the scroll bar is visible enough though.

really applicable when multiple usage forms can be described with a single followup paragraph

To be clear what I meant was that the use of indentation makes it clear what is a command and what is description, already. The quotations are redundant in my opinion.

Why do you think this warning should go in gui/launcher's help specifically?

Well I don't think it needs to be, but it is a nice visible location to briefly point out custom tilesets can cause text to render less readable than it could otherwise. Probably a bit pointless to bother for the reasons you said, and the graphics updates coming.

The examples you pointed out do not fall under that category and probably should have followed the standard. PRs welcome for those.

Won't be from me I expect. These are just my thoughts on the docs, I won't really be putting aside much time for dfhack docs in the coming months. And the build docs have my priority. The main blocker is windows activation in my VM windows can't tell it's the same PC since all the hardware is virtualized.

It's saying that by default the civ picks from a pool, and add-recipe native gives you the entire pool. How would you rephrase this?

First of all, I just looked at the docs online and noticed there is a typo.

Add crafting recipies to a civ.

So upon re-reading it, granted after reading your explanation, it makes perfect sense as is. Perhaps it just needs to be clearer on what the game's default behaviour is. Perhaps something like:

By default the game has civilizations pick randomly...

But actually, thinking about it a bit more. This should be explained in the summary, not the usage. I think by explaining it in the usage you're setting player's up to misunderstand what the command does. So on that subject, for any scripts that are modifying the game's default behaviour(s) [or rely on the player understanding what some game behaviour] the behaviour should be explained in the script summary and not at all in the usage section which should be specifically for what the script's behaviours are.

I'll add a note that vanilla raws do not include any SPATTERADD tokens. This plugin is only useful for mods that add this kind of behavior, and the added behavior is up to the mod.

Perhaps it could be reworded then, as some mechanics do appear to be directly from the plugin. So then explain what the plugin provides vs what the mod can provide. Surely there are limitations to what the mechanics can be? Or could I make literally anything.. like say.. a special blood that turns dwarves into gods [with other dwarves worshiping them] for exactly 73 hours after which they turn into werewolves kill 7 people [not followers/worshipers], then die.. in an explosion to ensure more dwarves do the same.

Done. Thank you for the suggestions!

DFHack / dfhack