docs(book): initialize mdBook structure for The Xilem Book

[richarddalves]

Related to #1480

After many hours of work, I've set up the mdBook infrastructure and written the initial chapters to get The Xilem Book started. The structure follows the outline suggested by @PoignardAzur in the issue.

What's done:

• Complete mdBook setup with organized chapter structure
• Introduction chapter
• "What is Xilem?" chapter with architecture diagram
• Installation and Setup chapter
• "Your First Xilem App" tutorial chapter
• README and contributors page for the book

Preview:

Edit.: I put it up at richarddalves.github.io/xilem (or xilem.enriched-rust.org).

Introduction	Architecture Diagram	First App Tutorial

What's next:
The remaining chapters exist as placeholders ready to be filled in. As the Xilem team continues developing the framework, the book structure is there to document new concepts and patterns. Community contributions are also welcome for anyone wanting to help expand the guide.

[PoignardAzur]

Thanks for the initiative!

There hasn't been any official discussion about this, but I'm not sure we want a mdbook, actually.

In the case of Masonry, we embedded the tutorial directly within rustdoc. This has a few advantages: it's lightweight, and it makes intra-doc linking easy.

Also, on a subjective level, while I associate large mdbooks with professional projects, small mdbooks (or, like here, mdbooks with a lot of stub chapters) have the opposite connotation to me: they suggest an incomplete and poorly-documented project.

[PoignardAzur]

I do have to ask, this is a lot of text to write in under three hours, especially as someone with no Xilem experience. Did you write this with LLM assistance?

[richarddalves]

Thanks for taking the time to review this!

About your question on LLM usage: yes, I did use an LLM to help me structure and review the content. However, the actual content came from my own learning over the past three weeks since opening the issue. Since then I've been learning the framework, and everything I wrote comes from that learning. That's precisely why I left the other chapters as stubs, I don't have enough knowledge yet to write about those topics with confidence. I wanted to get feedback on what I wrote before continuing, and I also thought having the structure there might make it easier for others to contribute if they wanted to.

I really like the idea of having a book for Xilem. If you don't want to integrate it into the project though, would it be okay if I kept working on this independently as an unofficial resource to help people getting started? I'd make it clear it's not official documentation. Otherwise, I'm happy to close this PR and adapt whatever I wrote to whatever format works better for you.

If you want to check what I wrote without cloning, I put it up at richarddalves.github.io/xilem (or xilem.enriched-rust.org).

[PoignardAzur]

I really like the idea of having a book for Xilem. If you don't want to integrate it into the project though, would it be okay if I kept working on this independently as an unofficial resource to help people getting started?

Maybe others can chime in, but I think this is fine, as long as you clearly label it as non-official. We could even link it from this repo's README (while still presenting it as non-official material).

[eliheuer]

I like the mdbook format much more than just rustdoc personally. An official blessed mdbook would be much better for designers and semi-technical people.

[PoignardAzur]

I like the mdbook format much more than just rustdoc personally.

What do you prefer? I think they're both equally fine (either way, it's markdown with a gutter on the left and a search bar).

[StefanSalewski]

Just had a short look. Do we think that

you write functions that describe what your interface should look like for any given state.

Well, I created only the tiny chess and sudoku games, but that was not really my feeling -- I have never cared much about state.

Other points: Have you discussed the differences between immediate mode GUIs like EGUI and the other type like GTK? Can currently not remember the correct term. And compared declarative GUIs with ... I think QML was called a declarative GUI? And perhaps we should compare Xilem a bit with one of the latest GUIs, GPUI from the popular Zed editor, perhaps also to the GUI of the Lapce editor. Compared to Xilem, Zed and Lapce have proved that large apps can be created with it.

[richarddalves]

Well, I created only the tiny chess and sudoku games, but that was not really my feeling -- I have never cared much about state.

You're right, that's exactly what I meant by that phrase, but it clearly wasn't coming across well. I've rewritten that part based on your feedback, and I've reorganized the chapter to explain the GUI paradigms first with code examples, then added the framework comparisons you suggested. Should be much clearer now.

Updated version at xilem.enriched-rust.org.