Document that YAML::Tiny is not YAML

[perlpunk]

While YAML::Tiny is great and fast for really simple data, I think the documentation should be clearer that it is actually not YAML.

It says it's a subset, but that makes people think that files that can be read by YAML::Tiny can also be read by other YAML libs.
But that's not the case. It can lead to syntax that is not valid YAML.
That creates the problem that people using it cannot switch to a different module easily. If all YAML files are controlled by the same person, that might work, but otherwise it will break things.

[karenetheridge]

Isn't it the other way around, that YAML::Tiny only reads and produces a limited subset of the YAML dialect, so if you use some of the more advanced features, YAML::Tiny cannot read it?

I don't think it's intentional that YAML::Tiny produces non-compliant output. We should fix that!

(I am definitely in favour of updating the documentation to make clear what YAML::Tiny is good for, and not good for.)

[haarg]

I believe the issue is that it's not truly a subset of YAML. It mostly is, but there are things that it just parses differently from how a real YAML parser would.

[perlpunk]

Yeah, sorry =)
It's not about producing invalid YAML. I think I haven't found cases where it does that.

It's that it accepts things that are not valid.
See #35, #56

The problem is that if people are using YAML::Tiny in their software, they are likely to write invalid YAML at some point.
And then moving to a different module or simply sharing the YAML with other apps can lead to problems.

The question is, could we fix all these cases? Maybe we can, but it would break things.

We recently had the case at work.
There was a team inventing their own include syntax like so:

key: val
!include: file.yaml

And then the include happened via post processing.
The problem is that this is invalid YAML. There needs to be a space after the tag/before the colon.
Of course then YAML::Tiny would have complained that it doesn't support tags.

In our case it was easy to fix because this feature was so far only used locally, so we were able to fix all YAML files, and we used $include instead. We are now using YAML::PP.

I can try to look into the issues and see if those are easily fixable, but like I said, it might then break things.