Dependency on libyaml not documented

[TnS-Loup-Vaillant]

Hi,

When I first tried to build libcyaml, I got a compile error about yaml.h being missing. Digging to the source code I noticed that the error was normal, because I did not have libyaml installed on my system.

The dependency itself is okay, but the README makes no mention of libyaml, and I don't see an INSTALL file either. Perhaps you should mention that you're building on top of libyaml? From the look of it libcyaml is an overley of top of libyaml that adds schema capabilities. You may also have other advantages over libyaml (I don't know, I just got in), that may be worth mentioning explicitly.

Explicitly documenting the dependence and the additional features of libcyaml over libyaml would help newcomers decide which is best for them. Me for instance just have one small configuration file, so I probably won't ever need the schemas. But I could consider sticking with libcyaml if its API is clearly easier to use.

[tlsa]

Hello!

The README file says it here: https://github.com/tlsa/libcyaml/blob/main/README.md?plain=1#L40

Maybe I can make it clearer.

[danielealbano]

Maybe it's worth to add a small section before or under Building with the commands for the most known distros to install the required dependencies.

If it works for you, I can reuse the list of deps from my project ( https://github.com/danielealbano/cachegrand/blob/main/docs/build-from-source.md ), clean it up and add it to the section

[TnS-Loup-Vaillant]

@tlsa, it would seem I can't read. Oops.

Now I do think you can make it clearer. Listing the libyaml dependency as a "feature" probably contributed to my missing it: I'm currently taking over a project that uses LibCYAML, and until the thing build I had no interest in your features. We could also argue that dependencies aren't features.

If libyaml is your only significant dependency (besides a C compiler), you could perhaps lead with something like "LibCYAML is a C library for reading and writing structured YAML documents. It is written in ISO C11, based on libyaml, and licensed under the ISC licence." Or something similar under the "overview" section.

@danielealbano, a clear list of dependencies under a dedicated section (if we have many dependencies) or under the Building section (if we have few dependencies) would work wonders.

[tlsa]

When I was writing that, the reason I considered it a feature is that it gives people the assurance that under the hood it's the canonical implementation of the YAML spec.

When you get to the edge cases there are about as many different behaviors as there are implementations. See this overview of the situation with JSON parsers, and YAML is a far more complex standard.

[TnS-Loup-Vaillant]

Sounds like a pretty core selling point, then. It definitely belongs to your elevator pitch. If not in the very first sentence like I've shown, at least in the overview. That way people know right away you're building on a strong foundation. (And grumpy users like me will stop bitching about not finding dependencies. :smile:)