Reading the Zig Language Reference #623

simenandre commented 2026年05月29日 09:38:48 +02:00

Hello 👋

I am currently reading through the Zig Language Reference cover to cover, and having used fragment identifiers in the URL (e.g. #Peer-Type-Resolution) as a makeshift bookmark, I realised a better way to consume it is a on my reading tablet. A few hours later, I got this working: https://codeberg.org/simenandre/ziglang-docs-epub

I always thought the language reference should be in multiple formats, like man pages, txt etc. I know we can all use pandoc or something similar to convert to a lot of formats. The result from direct conversion is likely not great, when I made the epub, the sidebar became a thing. Good user experiences pays off :)

If you want to link to the epub files somewhere, feel free <3

Hello 👋 I am currently reading through the Zig Language Reference cover to cover, and having used fragment identifiers in the URL (e.g. `#Peer-Type-Resolution`) as a makeshift bookmark, I realised a better way to consume it is a on my reading tablet. A few hours later, I got this working: https://codeberg.org/simenandre/ziglang-docs-epub I always thought the language reference should be in multiple formats, like man pages, txt etc. I know we can all use `pandoc` or something similar to convert to a lot of formats. The result from direct conversion is likely not great, when I made the epub, the sidebar became a thing. Good user experiences pays off :) If you want to link to the epub files somewhere, feel free <3

emilia commented 2026年06月20日 03:38:54 +02:00

I'd like to also bring to the attention of the team, that the language reference page is laggy on phone view, and can end up just crashing the browser.

As well, regarding the multiple output formats, EPUB is really nice, something I feel it could help is maybe using AsciiDoc, or even Typst.

• AsciiDoc it's quite stablished with its output formats, this includes HTML, PDF, MAN, and EPUB. where they can be obviously stylized and have them in a book format/type, with automatic ToC, etc.
• Typst is quite similar, except it's more specialized in PDF and HTML is experimental, and EPUB is somewhat proposed.

If possible, I'd like to showcase a very little MVP of how it could look with AsciiDoc mostly, Typst would be worth if PDF was the first target rather than HTML (being experimental).

---

Also, a bit related to the generation of this language reference, I'm wondering about the templating engine to produce, whether it could be considered to be part of the standard library, just like Go has html/template and text/template.

I'd like to also bring to the attention of the team, that the language reference page is laggy on phone view, and can end up just crashing the browser. As well, regarding the multiple output formats, EPUB is really nice, something I feel it could help is maybe using AsciiDoc, or even Typst. - AsciiDoc it's quite stablished with its output formats, this includes HTML, PDF, MAN, and EPUB. where they can be obviously stylized and have them in a _book_ format/type, with automatic ToC, etc. - Typst is quite similar, except it's more specialized in PDF and HTML is experimental, and EPUB is somewhat proposed. If possible, I'd like to showcase a very little MVP of how it could look with AsciiDoc mostly, Typst would be worth if PDF was the first target rather than HTML (being experimental). --- Also, a bit related to the generation of this language reference, I'm wondering about the templating engine to produce, whether it could be considered to be part of the standard library, just like Go has `html/template` and `text/template`.

andrewrk commented 2026年06月20日 04:26:57 +02:00

I'd like to also bring to the attention of the team, that the language reference page is laggy on phone view, and can end up just crashing the browser.

The language reference is a self-contained 941KB html file with no javascript. It is neither laggy nor fast; it is just some html. I think it's a quite reasonable quantity of html to have on one page, and I think your experience is unusual with respect to performance of this page in most browsers, including on phones.

> I'd like to also bring to the attention of the team, that the language reference page is laggy on phone view, and can end up just crashing the browser. The language reference is a self-contained 941KB html file with no javascript. It is neither laggy nor fast; it is just some html. I think it's a quite reasonable quantity of html to have on one page, and I think your experience is unusual with respect to performance of this page in most browsers, including on phones.

emilia commented 2026年06月20日 04:47:05 +02:00

Ah ok 😔 thanks

Ah ok 😔 thanks

emilia commented 2026年06月20日 04:50:37 +02:00

Hmm, so the strict requirement for the language reference is to be fully HTML?

Hmm, so the strict requirement for the language reference is to be fully HTML?