Document syntax trees

[wooorm]

When working with trees, there are several tasks that occur a lot. And there’s jargon for those tasks. Explaining jargon in of course needed. Having those explanations in one place makes it easier to update, an gives a good introduction to syntax trees/unist for newcomers.
Using jargon is nice for utilities and others tools so they don’t have to explain everything all the time.

Current efforts

One effort to do that is the Glossary and Tree traversal appendices of unist.
As raised in syntax-tree/unist#25, the appendices are growing and it may be time to move them somewhere else.

Design

The form this takes could be either more technical, or more beginner friendly. In the latter case, it could be a bit like the introduction of the babel handbook.

It could be a readme file. Or it could be a guide on unified.js.org. Or it could be a GitBook / Docusaurus project.

Additional resources

• https://dom.spec.whatwg.org/#trees
• https://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-035-computer-language-engineering-spring-2010/
• https://github.com/skylake59/awesome-compilers#introductory
• https://en.wikipedia.org/wiki/Abstract_syntax_tree

[wooorm]

/CC @ChristianMurphy

[Murderlon]

I would definitely like to see a more introductory guide to syntax trees that isn't a technical specification or glossary. In terms of it's form/design, I'm not sure a book like Babel is the right choice here. It scares me that it takes a book to understand babel while not all parts are may be relevant to what brought me there. On one hand it's nice to have a continuously evolving single-source of truth that encapsulates not just syntax trees, but also their context in the ecosystem. On the other hand interlinked single-purpose guides might be easier to consume.

Personally, I've always preferred highly specific (and therefor short) articles and the like. The question for me though it whether syntax trees is still too big for a single guide/readme? Can it be split up? Introduction vs. working with them?

[ChristianMurphy]

I would definitely like to see a more introductory guide to syntax trees that isn't a technical specification or glossary. In terms of it's form/design

I completely agree.

I'm not sure a book like Babel is the right choice here. It scares me that it takes a book to understand babel

There are a lot of resources on syntax trees, the subject area is pretty large.
Having a book makes sense, people don't need to read all of it to get started.
Yet people who want to do a deep dive can leverage it as an exhaustive reference.
My caution is that we could end up writing yet another book on syntax trees, that largely duplicates existing resources.

The Can it be split up? Introduction vs. working with them?

I think we may be able to
We may be able to link out to external references for tree traveral and syntax trees, and primarily offer recipes on how those concepts translate into Unifed.js examples.

Personally, I've always preferred highly specific (and therefor short) articles and the like.

This sounds like a blog.
@Murderlon would you be interested in creating some blog posts on some specific use-cases for Unified?

[Murderlon]

My caution is that we could end up writing yet another book on syntax trees, that largely duplicates existing resources.

Valid concern, I'd say some of the jargon and precise technicalities are beyond the scope here.

We may be able to link out to external references for tree traveral and syntax trees, and primarily offer recipes on how those concepts translate into Unifed.js examples.

Exactly.

@Murderlon would you be interested in creating some blog posts on some specific use-cases for Unified?

Coincidentally, this is what @wooorm and I have been talking about on what I should focus on. I'm currently thinking most about centralizing docs and guides on https://unified.js.org V2, which includes writing about syntax trees. As this is beyond the scope of just documenting syntax trees, I've created a new issue (does relate to #7): unifiedjs/unifiedjs.github.io#7

[ChristianMurphy]

Thanks for starting the discussion @wooorm !
We're in the process unifying ideas in with discussions unifiedjs/collective#44
If you'd like to continue this thread, or start a new one https://github.com/syntax-tree/unist/discussions/categories/ideas will be the home for ideas going forward.