📓 documentation should mention that colon is an invalid character in string values

[DrakeDWhite]

What are we changing or adding?

• [ ] Repository
• [ ] Publish Documentation

Location

The main readme for the github repository, explaning how to use Fantasy stablocks.

The issue is...

See title. Lots of troubleshooting may be wasted trying to figure out why the homebrew statblocks are not working or saving progress: many D&D descriptions use colons in their text.

Suggestions?

Should list out any invalid characters and potential workarounds.

Anything else?

Nope! Thank you :)

[JamesYeoman]

TL;DR: Read the documentation. It already explains the statblocks are written in YAML and that you should wrap anything containing colons in quote marks.

---

You should be able to wrap descriptions in speech marks (e.g. "some content: here"). YAML is a configuration language. : is used to denote key-value pairs (e.g. size: Large meaning the key is size and the value is Large).

YAML is lenient enough that you don't need speech marks to denote that a value is a string. But when you use characters that are recognised by the language as having very specific meaning, then it can't be intelligent enough. For example, it's valid in YAML to have nested key-value pairs.

# An example of nested key-value pairs
saves:
  strength: 15

# { [ key="saves", value={ [ key="strength", value=15 ] } ] }

Here's an example for the Weretiger in Pathfinder 2E, where a lack of quotes could mean a different datatype (a list of key-value pairs instead of a key-value pair)

saves:
  "Recall Knowledge - Beast": 19

And here's an example of YAML being used to configure Docker

version: "3"

services:
  myContainer:
    image: "ubuntu:22.04"
# ...

The value for image in the above example needs to be a string, and without the quote marks, it would be interpreted as a key-value map instead, which would break the configuration.

Also, the Readme for this repository already mentions your problem, and has been there at least 5 months (the last commit that modified the readme was 5 months ago).

Common errors include: not putting quotes around parameters with : or * (such as Melee Weapon Attack:) and not indenting properly.

You might have missed it while skimming through (even I do that sometimes too to be fair, and I'm a software developer), but it's always a good practice to make sure to double-check (or even triple-check) any documentation before raising issues regarding it.

[DrakeDWhite]

I am also a developer, and am used to poking through documentation like this and still missing some minor stuff. Thanks for pointing out where that information is.

My underlying point here is that not everybody using this service is technical, a talented problem solver, a developer, etc. They may not know github well enough to poke around beyond the readme and read these initial things, and instead just take from your examples on the initial readme what they can do. They may also not be aware of implicit YAML rules, as this might be their first time using it. Someone may not have the first thought to look at the common errors section: they may instead follow your directions as written in the initial formatting section, have it error out, and give up on using it altogether rather than knowing to dig for it.

My main suggestion is to just add a note to this section of the documentation that notes the arguments should have quotes. I don't think this adds too much content to the readme, and can help potentially catch folks who may fall into that pitfall (whether or not we feel like it's a natural pitfall for us to fall into, as more technical folks).

Let me know if you have any thoughts!