Human-Oriented Markup Language

[captn3m0]

Some context, this was launched at IndiaFOSS[0] yesterday

25 minute talk at https://www.youtube.com/live/AUrPdOZNsX8?feature=shared&t=13... (starts 3h:52)

The talk proposal is at https://fossunited.org/c/indiafoss/2025/cfp/arsnhack6n

And it primarily tries to avoid YAML horrors : https://noyaml.com/ and https://ruudvanasseldonk.com/2023/01/11/the-yaml-document-fr....

[0]: https://fossunited.org/indiafoss/2025

[xg15]

JSON5 allows comments.

Can someone explain to me what is so horrible about curly braces that we need a whole host of "human-friendly" configuration languages with nontrivial parsing just to get around them?

[tracker1]

    s/JSON/YAML/g
    s/curly braces/whitespace/g

[ivan_gammel]

We are stuck in the old paradigm of characters taking space on the screen and the idea that a markup language must support classic dumb TUI. If, just imagine it, we used some Unicode range for control characters for the semantic markup and standardized UX for it, we wouldn’t need using normal characters as delimiters and escaping them in strings.

The following would have parseable structure, but would be free of visual noise.

  Title: Markup languages: decades of going in the wrong direction 
  Keywords: hypertext,
      delimiters, 
            ˋ, ", \

[wpm]

Don't ask me, I don't even know what was so bad about XML tags.

[Silphendio]

JSON 5 is pretty good. It just needs to make the top-level brace and all commas optional, and add proper support for multi-line strings (writing '/n/' at the end of every line doesn't count).

Allowing only valid JavaScript identifiers to be unescaped keys is also a bit quirky (You have to quote reserved keywords).

But they will never change any of that because it would break JavaScript compatibility.

[nielsbot]

I can see someone wanting the Markdown of markup languages: more convenient for people to read and write. Sure, without markdown you could write HTML, say. But editing Markdown is a nicer experience.

[sigmonsays]

I prefer curly braces. My editor has all sorts of comments to jump between opening and closing curly braces. This is not possible with whitespace.

[groby_b]

Honestly, nothing. Except the endless debate on where the braces go, and how long they're allowed to stay on a single line.

It seems trivial, but replacing scope delimiters with a per-line signifier (i.e. indent) makes the scope of each line self-contained and sidesteps that discussion.

Is that worth YAYAML (Yet another YAML)? I don't know. But I certainly get the desire to skip the discussion :)

[jameskilton]

I couldn't help but notice almost immediately one feature that is not human oriented, but most likely exists because it's easier for a machine to parse: single (":") vs double colon ("::"). This is not human-friendly. A human wants to write "key" "is" "value", and YAML has for a very long time supported a single ":" for "is" regardless of the actual type of the value.

I shouldn't have to care about what the type of the value is when writing out effectively YAML. This double-colon feature will do nothing but lead to bug reports from people confused as to why their document is invalid.

[xpe]

The comment above gives explanations defending subjective preferences about what "human oriented" means. That's fine as long as you remember that is what is happening: justification of subjective preferences. Other people can reasonably (or unreasonably) have different subjective preferences.

Also notice what the commenter above haven't done (yet, maybe they will?): done a full "forest level" comparison of all the trade-offs between the current HUML specification and ... what is your alternative proposal, exactly?

Based on my experience, I would guess that most people who design a language (and written a parser for it) for the first time will: (1) be surprised at how quickly design decisions snowball and lead to unexpected places; (ii) discover just how entangled design choices really are; (iii) will give up on trying to please everyone.

In my view, a language designer does really well to describe one's motivations, goals, tradeoffs, decisions, and then live with what you make, because... (a) making something real and useful is rad and (b) any language you make will probably have some weird stank you can't seem to get rid of.

[jampekka]

I find this very human-friendly: "[double colon] permits vectors to be defined inline without additional syntax such as [ ... ] or { ... }."

(One could question how human friendly it is to call lists and dicts "vectors" though...)

https://huml.io/specifications/v0-1-0/#why

[debo_]

I think we should have a name for the often undue examination and analysis of colon/semicolon usage in machine languages. I volunteer the name "colonoscopy."

[Sohcahtoa82]

The double-colon is probably a necessity to disambiguate a scalar from an inline list that only has one scalar.

For example `x: 3` would be equivalent to `"x": 3` in JSON, but `x:: 3` is equivalent to `"x": [3]`

[JoBrad]

I found that example to be humerous, but specifically compared to the goals:

> Provide as few ways as possible—preferably one—of representing something.

Very Pythonic. Especially since representing a dict already has 2 ways, on the first page!

[CrimsonCape]

In my theory of "human-readability", odd double tokens like :: can exist successfully so long as there is sufficient utility and logic in the single token :

Tokens are inseparable from human instincts of single = less, double = more and the corresponding emotions: single=less=easier=quicker, double=more=complicated=longer=difficult

If you are not emphasizing the single token as them most common, it's going to cause confusion.

[inerte]

Maybe the plural of "is" is "are" :)

But why double the character instead of picking another one... plenty of other non-alphanumeric characters to chose from.

[xpe]

Language design often involves subjective tradeoffs. The author gives their rationale here: https://huml.io/specifications/v0-1-0/#why

[xg15]

There would at least be some ambiguity with single-value lists otherwise:

If

  numbers: 1, 2, 3

was a list, what would

  numbers: 1

be?

[vczf]

The clear distinction between scalars and vectors appears to be the main advancement HUML offers.

I think it’s a neat improvement.

[kazinator]

The buttstock of a rifle, trigger and other operating details are "human oriented" and the muzzle end is also frequently "human oriented".

Not sure which one we have here.

[R_D_Olivaw]

Thanks for the chuckle.

[troupo]

"Human readability and editability above all else" would not chose significant whitespace for a markup language. IMO.

Or restrictions like "only one space allowed after : before a value"

[ssivark]

On the contrary, such strictness makes it easy to lint / auto-format HUML.

[xpe]

> Provide as few ways as possible—preferably one—of representing something.

TRUTH!

Or, expressed in YAML 1.1 [1]

    y
    Y
    yes
    Yes
    YES
    true
    True
    TRUE
    on
    On
    ON

As expressed in YAML 1.2 [2]:

    true

[zahlman]

If the goal is to look similar to YAML and fix its problems and assert itself as something that's needed in a world with YAML, the introduction should probably explicitly call out some clear differences.

[braebo]

LSP is the only thing that matters to me, regardless of the language I’m evaluating.

Weeks of my life have been reclaimed thanks to TypeScripts LSP.

All configuration languages suck in Monaco, so much so that I would rather use C# or TS to generate a config with docs in the tooltips, red squiggles under my typos, and location-aware autocomplete.

[burnt-resistor]

Oh lord. We already have TOML, which is an improvement on limited JSON when a human-readable, easily-diffable, more flexible format is needed.

We don't even need HCL (offers little value), YAML (has too many features making it inherently less secure), XML (is a mess with too many features and too much verbosity), or INI (insufficient features) except for existing and historical reasons.

In cases where a single file is attempted to be managed by multiple, competing interests, it's probably better to split the file into multiple, modular/include files like *.d/* so there would be less chances for merge conflicts.

And then there's /{proc,sys}-like configuration with one "value" per file where the path forms the heirarchy.

Please. Just. Stop reinventing wheels that were already round enough.

[lucketone]

Off topic: Hard part of the wheel was not the round shape, but the axle. (That part actually was improved great many times)

[LordDragonfang]

I was googling for the repo, and it looks like this project has a name collision with an 11-year-old, 3-star repo: https://github.com/shelling/huml

[bvrmn]

`::` is quite strange. 1) It only allows to resolve nesting conflicts for a single level. 2) Could be hard to read and could lead to reasoning mistakes. 3) Looks like an attempt to differentiate HUML from YAML somehow.

[insane_dreamer]

I like the idea of using `::` to denote a vector value.

[kardianos]

My only pet peeve: can we define decimals as dec128 rather then float64 in configuration files?

[beckford]

For something like this I would love to see a formal spec to go along with the examples.

[Jolter]

I do appreciate that they lead with the examples. They convey 90% of the important information. TBH, having worked with yaml just enough to get by with k8s deployments, I could immediately spot how this would be an improvement.

[bmn__]

ctrl+f grammar

Term not found.

[xpe]

Me like teh grammarz 2. Plays 4 author someday could put at https://github.com/huml-lang then it slay

[skerit]

Strictly 2 spaces for indentation? What's human about that.

[SpaceNoodled]

Oh good, another even more confusing YAML alternative that still offers less functionality, flexibility and readability than JSON.

[AlienRobot]

You could say the same thing about JSON compared to XML.

[sigzero]

Data only for JSON, it lacks just like everything else as a configuration language. Arguments against I have seen are too verbose, too strict, and no comments. I am sure there are more.

[romperstomper]

yeah, the 15th standard.. https://xkcd.com/927/ :)

[sigzero]

XKCD predicting the future so well! :)

[mrbluecoat]

It's like YAML and MD had a baby

[kelvinjps]

Wasn't this solved by yaml 1.2?

[romaniv]

Reminder: you can use indentation to encode s-expressions. The result is very easy to parse and easy to read provided the underlying data structures are not insane.

https://srfi.schemers.org/srfi-49/srfi-49.html

[sgarland]

I don’t hate this nearly as much as I hate YAML. Now get everyone else to adopt it - good luck.

[NoSalt]

This is the main reason why YAML and Python are bad. Give us CLEAR beginnings and ends to code statements and blocks, not these dubious beginnings and ends. Ignore white space and use clear EOL delineation. Clearly, XML and JSON are superior to YAML and even this weird-looking HUML. Not to mention almost any other language syntax being superior to Python.

[lenkite]

I have actually practically tried out a test where I give a huge config file in XML and then JSON and ask folks question on its structure.

The ones who read the XML file understood immediately. Why ? Because XML is self-documenting and the repetition via clear de-limitation extensively aids human memory.

The one who read the JSON file just glazed over it and needed to refer back to the document and re-read several times.

I urge all the XML naysayers and XML haters to please carry out this practical test with their colleagues. Please choose a good level of complexity and nesting and please make use of XML attributes for scalar values.

XML is SO FAR ahead in readability and grokking that it is not funny.

[kelvinjps]

I think it's a preference? I find both Python and YAML to give clear beginnings and ends using whitespace, and you can also see it visually.

[AlienRobot]

That has never been a problem with Python, ever.

[slowmovintarget]

Posting a link to the XKCD comic would be a cliche at this point, yes?

[didip]

Why not just use YAML?

[vedmakk]

Because of the reasons presented in the actual article that was posted by op...