YAML is half bad

YAML is a language I’m becoming more and more appreciative of, from really hating it a few years back. It has what I’m gonna call “a full structure” as opposed to Kramdown’s and Pandoc’s set of kluges and extras and “uh… We need it to distim the doshes… In HTML they would just create a <distim> and <dosh> tag or attribute, but here in ASCII art land we’ve got to… Uh… Maybe a @@@$! string can represent some doshes?”

Whereas with YAML you have key value maps and sequences. You wanna add in some dosh distimming, you can easily.

If XHTML is all good and Textile/​RST/​Pandoc is all bad, then YAML is half bad. Like Textile and its ilk, I can’t easily write YAML without tools. But the good thing is that if I am looking at a YAML document, I can more or less understand the gist of what’s there.

Here’s an example.

figure:
  img:
    src: /foo.img
    alt: An image that is great
    title: An image
    loading: lazy
  figcaption: An image that is great

I used tools to help me write that, but reading it, I can get the gist of what’s there just fine, and it’s extensible.

Which I absolutely can not from something like Kramdown’s:

![An image that is great](/foo.img "An image"){: standalone loading=lazy}

YAML is half bad but the other half is good.

Notes to the self

Even though YAML I can sorta get the gist of what a YAML document is trying to say just by looking at it, to really understand the semantics of YAML, here’s a shorthand I’m trying to use. “It’s basically JSON with extra steps.” It’s a nicer looking format and you can have comments and stuff but the core of it is sequences and key-value pairs.

If I can remember that it’s pretty much a syntactically sweetened JSON I’m looking at, that can help me get what the document is really about.

Now, y’all know I prefer sexps and SXML for my structured format and even though I’m coming around to YAML, I don’t get to use it much because in all of my own projects I usually use sexps.

Whaddayamean you “used tools”?

Talking to a friend about that particular kramdown example, which he came up with, I used xj to turn kramdown’s output into JSON then by hand I stripped off all the extra parens and curlies and then I double-checked with yasx which I don’t think I have a page for yet because it’s just a brev function that I use to check in on YAML; i.e. I write YAML but then select the region and pipe it through yasx to see the sexp equivalent.

It’s just this:

(define (yasx)
  (handle-exceptions exn "Invalid YAML" (yaml-load (current-input-port))))

It’s not great because sequences and map are both represented as conses unlike some of the JSON parsers for Scheme that uses a mix of conseses and vectors to make things roundtrip safe, so I’ve switched to using yq, and also using flycheck with yamllint in Emacs’ yaml-mode.