update zine to v0.10.2 and adjust github pages

Author: matu3ba

.github/workflows/gh-pages.yml

@@ -1,28 +1,71 @@
+# adjusted from https://zine-ssg.io/docs/deploying/github-pages/
 name: github pages
 
 on:
   push:
     branches:
       - master
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
 jobs:
   deploy:
     timeout-minutes: 20
     runs-on: "ubuntu-latest"
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # steps:
+    #   - name: Checkout
+    #     uses: actions/checkout@v4
+    #     with:
+    #       fetch-depth: 0  # Change if you need git info
+
+    #   - name: Setup Zig
+    #     uses: mlugg/setup-zig@v1
+    #     with:
+    #       version: 0.14.0
+
+    #   - name: Build
+    #     run: zig build --summary new
+
+    #   - name: Deploy
+    #     uses: JamesIves/github-pages-deploy-action@v4
+    #     with:
+    #       folder: ./zig-out
+
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0  # Change if you need git info
 
-      - name: Setup Zig
-        uses: mlugg/setup-zig@v1
+      - name: Setup Zine
+        uses: kristoff-it/setup-zine@v1
         with:
-          version: 0.14.0
+          version: v0.10.2
 
-      - name: Build
-        run: zig build --summary new
+      - name: Release
+        run: zine release
 
-      - name: Deploy
-        uses: JamesIves/github-pages-deploy-action@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
         with:
-          folder: ./zig-out
+          path: 'public'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -1,6 +1,13 @@
 ### Usage
 
+```
 ../zig-linux-x86_64-0.14.0/zig build serve
+zig build serve
+zine
+
+zine release
+git diff --word-diff=color --no-index zig-out public
+```
 
 ### Markdown languages
 
@@ -24,3 +31,26 @@ So one has to workaround this via
 </pre>
 ```
 or including sections into the item.
+
+Work around unchecked references
+```
+content/articles/shennanigans_in_c.smd:16:5: error: unknown ref
+|    - 1.[Pointer semantics](#pointer_semantics)
+|        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+```
+via
+```
+- 1.[Pointer semantics]($link.unsafeRef('pointer_semantics'))
+```
+
+### Comments
+
+- shtml
+```
+<!--<div :html="$page.content()"></div>-->
+```
+- smd
+```
+(empty line)
+[This is a comment]::
+```

build.zig

@@ -2,11 +2,16 @@ const std = @import("std");
 const zine = @import("zine");
 
 pub fn build(b: *std.Build) !void {
-    zine.website(b, .{
-        .assets_dir_path = "assets",
-        .content_dir_path = "content",
-        .host_url = "https://matu3ba.github.io/",
-        .layouts_dir_path = "layouts",
-        .title = "Jans Website",
-    });
+    // zine.website(b, .{
+    //     .assets_dir_path = "assets",
+    //     .content_dir_path = "content",
+    //     .host_url = "https://matu3ba.github.io/",
+    //     .layouts_dir_path = "layouts",
+    //     .title = "Jans Website",
+    // });
+    b.getInstallStep().dependOn(&zine.website(b, .{}).step);
+
+    const serve = b.step("serve", "Start the Zine dev server");
+    const run_zine = zine.serve(b, .{});
+    serve.dependOn(&run_zine.step);
 }

build.zig.zon

@@ -6,8 +6,8 @@
 
     .dependencies = .{
         .zine = .{
-            .url = "git+https://github.com/kristoff-it/zine?ref=v0.9.0#e918b49937c071187a26b19132f707a5b53e381e",
-            .hash = "1220066f645b5ef9f9080e48073942fd3434ad789ad9548496d48d60fab5467cde15",
+            .url = "git+https://github.com/kristoff-it/zine?ref=v0.10.2#122be41ecc4f2f3a56ad3568dd5a8a0ad93de050",
+            .hash = "1220e93519a9ac531a02b5f79bf69a11ab2bfffd28ff90e95fb486cd5a1c4ae54e62",
         },
     },
     .paths = .{"."},

content/articles/shennanigans_in_c.smd

@@ -12,7 +12,7 @@ This article focuses on some of the non-obvious and easy to make mistakes
 non-experienced C programmers are likely to make and are/can not completely
 be covered by tooling without going into edge cases relevant to performance
 and covering the most simple and conservative approach:
-- 1.[Pointer semantics](#pointer_semantics)
+- 1.[Pointer semantics]($link.unsafeRef('pointer_semantics'))
 - 2.[Sequence points](#seq_pts)
 - 3.[Bit-fields](#bitfields)
 
@@ -57,17 +57,17 @@ abbreviated via macro `NULL`.
 []($section.id("pointer_access_practice"))
 **Pointer access** in **practice**.
 - Provenance as regions pointer is allowed to point to for access.
-[provenance.c]($code.asset('./provenance.c').language('c'))
+[provenance.c]($code.asset('provenance.c').language('c'))
 - Copy around some bytes from not overlapping regions (otherwise use memmove).
-[copy_bytes.c]($code.asset('./copy_bytes.c').language('c'))
+[copy_bytes.c]($code.asset('copy_bytes.c').language('c'))
 - Correct alignment of pointers with temporary, when necessary.
-[correct_alignment.c]($code.asset('./correct_alignment.c').language('c'))
+[correct_alignment.c]($code.asset('correct_alignment.c').language('c'))
 - Ensure correct storage and padding size for pointers via sizeof.
-[storage_padding.c]($code.asset('./storage_padding.c').language('c'))
+[storage_padding.c]($code.asset('storage_padding.c').language('c'))
 - Allowed aliasing of pointers (type-based aliasing analysis)
-[allowed_aliasing.c]($code.asset('./allowed_aliasing.c').language('c'))
+[allowed_aliasing.c]($code.asset('allowed_aliasing.c').language('c'))
 - Non-allowed aliasing of pointers (type-based aliasing analysis)
-[non_allowed_aliasing.c]($code.asset('./non_allowed_aliasing.c').language('c'))
+[non_allowed_aliasing.c]($code.asset('non_allowed_aliasing.c').language('c'))
 
 []($section.id("pointer_exceptions"))
 **The Exceptions**
@@ -81,7 +81,7 @@ abbreviated via macro `NULL`.
   back. This also means that `sizeof (function pointer) == sizeof (void *)` must be uphold, which is not true for
   microcontrollers with separate address space for code and data or CHERI in mixed capability mode/hybrid compilation mode.
   Address space annotations are mandatory for this to work and it is unfortunate that standards do not reflect this as of 2024-04-28.
-[aliasing_exceptions_uniform_address_space.c]($code.asset('./aliasing_exceptions_uniform_address_space.c').language('c'))
+[aliasing_exceptions_uniform_address_space.c]($code.asset('aliasing_exceptions_uniform_address_space.c').language('c'))
 
 []($section.id("pointer_construction_requirements"))
 **Pointer construction requirements** are unspecified in all C standards with potentially some hints and nothing
@@ -154,12 +154,12 @@ Other more elaborative examples can be seen in the github gist "What is the Stri
 
 []($section.id("opaque"))
 Opaque type idiom.
-[opaque.h]($code.asset('./opaque.h').language('c'))
-[opaque.c]($code.asset('./opaque.c').language('c'))
+[opaque.h]($code.asset('opaque.h').language('c'))
+[opaque.c]($code.asset('opaque.c').language('c'))
 
 []($section.id("ptrintconv"))
 Pointer to integer and integer to pointer conversion.
-[ptrtoint_inttoptr.c]($code.asset('./ptrtoint_inttoptr.c').language('c'))
+[ptrtoint_inttoptr.c]($code.asset('ptrtoint_inttoptr.c').language('c'))
 
 []($section.id("lto"))
 Link time optimization (LTO) usage and problems. One can use `ptrtoint_inttoptr.c` with flags for strong LTO
@@ -172,24 +172,24 @@ compiler automatically do runtime selection of the best SIMD routine instead of
 is vectorized and one has to check for example via `clang -O3 -Rpass=loop-vectorize -Rpass-missed=loop-vectorize -Rpass-analysis=loop-vectorize`
 or `gcc -O3 -ftree-vectorizer-verbose=3` and use [clang extensions](https://clang.llvm.org/docs/LanguageExtensions.html)
 and [gcc extensions](https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html) like `__builtin_assume_aligned`.
-[extern_avx.h]($code.asset('./extern_avx.h').language('c'))
-[extern_avx.c]($code.asset('./extern_avx.c').language('c'))
-[memcpy_avx.c]($code.asset('./memcpy_avx.c').language('c'))
+[extern_avx.h]($code.asset('extern_avx.h').language('c'))
+[extern_avx.c]($code.asset('extern_avx.c').language('c'))
+[memcpy_avx.c]($code.asset('memcpy_avx.c').language('c'))
 
 []($section.id("cerberus"))
 Checking C code validity with Cerberus does not imply absence of compiler miscompilations.
-[cerberus_install.sh]($code.asset('./cerberus_install.sh').language('bash'))
-[extern_miscompilation.h]($code.asset('./extern_miscompilation.h').language('c'))
-[extern_miscompilation.c]($code.asset('./extern_miscompilation.c').language('c'))
-[ptr_provenance_miscompilation.c]($code.asset('./ptr_provenance_miscompilation.c').language('c'))
+[cerberus_install.sh]($code.asset('cerberus_install.sh').language('bash'))
+[extern_miscompilation.h]($code.asset('extern_miscompilation.h').language('c'))
+[extern_miscompilation.c]($code.asset('extern_miscompilation.c').language('c'))
+[ptr_provenance_miscompilation.c]($code.asset('ptr_provenance_miscompilation.c').language('c'))
 
 []($section.id("cheri"))
 CHERI usage is left as task for the reader. Useful links are `https://github.com/CTSRD-CHERI/cheribuild`,
 `https://github.com/CTSRD-CHERI/cheri-c-programming` and `https://github.com/capablevms/cheri-examples`.
 
 []($section.id("seq_pts"))
 **Sequence Points** in simple case and with storage lifetime extension.
-[sequence_points.c]($code.asset('./sequence_points.c').language('c'))
+[sequence_points.c]($code.asset('sequence_points.c').language('c'))
 
 []($section.id("bitfields"))
 **Bit-fields** should not be used unless for non-portable code regarding

content/articles/shennanigans_in_cpp.smd

@@ -48,7 +48,7 @@ has no static analysis to reduce transition efforts from C++.
   via iterator or use emplace, because there is no check for the elements
   existence or (typically raw C) values of members can remain undefined after
   object creation due to implicit default constructor.
-[hashmap_simple_ub.cpp]($code.asset('./hashmap_simple_ub.cpp').language('cpp'))
+[hashmap_simple_ub.cpp]($code.asset('hashmap_simple_ub.cpp').language('cpp'))
 - Providing const char * to a function with reference will use the stack-local
   memory instead of using a copy. If further, `c_str()` is used to emplace into a
   `std::map`, this leads to UB due to usage of invalid memory once the stack
@@ -61,18 +61,18 @@ has no static analysis to reduce transition efforts from C++.
 - There is no type safety in `reinterpret_cast` usage, which is worse than
   memcpy. However, the prevention of another temporary for portable code may be
   worth it.
-[reinterpret_cast_ts.cpp]($code.asset('./reinterpret_cast_ts.cpp').language('cpp'))
+[reinterpret_cast_ts.cpp]($code.asset('reinterpret_cast_ts.cpp').language('cpp'))
 - C++ conversion string to int is worse without boost, so use C's strtol.
 - Checking, if typename is a string is complex (even with C++17 extension).
-[is_typname_string.hpp]($code.asset('./is_typname_string.hpp').language('cpp'))
+[is_typname_string.hpp]($code.asset('is_typname_string.hpp').language('cpp'))
 - auto does verbatim replacement of the return type, which can hide a
   stack-local copy or move. Only use `auto` for well-known iterators, status
   tuples, shared pointers etc, but never for objects and object references.
 - Interoperating type safe with c strings is cumbersome.
-[cstr_interop.cpp]($code.asset('./cstr_interop.cpp').language('cpp'))
+[cstr_interop.cpp]($code.asset('cstr_interop.cpp').language('cpp'))
 - MSVC has no reliable relative paths as macro yet (see
   experimental:deterministic mode). Workaround to get filename by Andry.
-[msvc_rel_path.cpp]($code.asset('./msvc_rel_path.cpp').language('cpp'))
+[msvc_rel_path.cpp]($code.asset('msvc_rel_path.cpp').language('cpp'))
 - Destructors of virtual classes should have lifetime annotation, unless final
   class. Otherwise, debugging problems will be painful, because the intended
   object lifetimes become ambiguous on reading the code. Consider using clang
@@ -85,14 +85,14 @@ has no static analysis to reduce transition efforts from C++.
 - Streams do not enforce C abi and are overly complex for printing memory.
   Further (no example here), they need to extensions to offer non-blocking
   reads, writes and introspection.
-[streams_no_cabi.cpp]($code.asset('./streams_no_cabi.cpp').language('cpp'))
+[streams_no_cabi.cpp]($code.asset('streams_no_cabi.cpp').language('cpp'))
 - Incomplete type can not be instantiated in template:
   1. pull in all headers deps of headers
   2. class forward declares may create circular dependencies
   3. build each file individually
   4. might be a circular dependency during template usage
 - Missing virtual destructor for non-final methods in classes is technically UB.
-[missing_virt_destructor.cpp]($code.asset('./missing_virt_destructor.cpp').language('cpp'))
+[missing_virt_destructor.cpp]($code.asset('missing_virt_destructor.cpp').language('cpp'))
 - Why exceptions do not scale.
-[exceptions_dont_scale.cpp]($code.asset('./exceptions_dont_scale.cpp').language('cpp'))
+[exceptions_dont_scale.cpp]($code.asset('exceptions_dont_scale.cpp').language('cpp'))
 - `__STDC_VERSION__` is not necessary defined by C++ compilers.

content/articles/shennanigans_in_python.smd

@@ -37,22 +37,22 @@ Aside of these more fundamental limitations, here the [list of shennanigans](#li
 - `.strip()` is necessary after file read, because Python automatically adds
   `\n` and there is no way to read without newlines into a list.
 - Testing for subdictionaries with `dict` is unreadable, so such a method is missing
-[missing_dict_methods1.py]($code.asset('./missing_dict_methods1.py').language('python'))
+[missing_dict_methods1.py]($code.asset('missing_dict_methods1.py').language('python'))
 - `dict` has no method to check, if the fields of a dictionary are in another dictionary
-[missing_dict_methods2.py]($code.asset('./missing_dict_methods2.py').language('python'))
+[missing_dict_methods2.py]($code.asset('missing_dict_methods2.py').language('python'))
 - `dict` has no method to check, if all fields and values of a dictionary are in another dictionary
-[missing_dict_methods3.py]($code.asset('./missing_dict_methods3.py').language('python'))
+[missing_dict_methods3.py]($code.asset('missing_dict_methods3.py').language('python'))
 - Tuples and dicts are annoying to differentiate
-[tup_and_dicts.py]($code.asset('./tup_and_dicts.py').language('python'))
+[tup_and_dicts.py]($code.asset('tup_and_dicts.py').language('python'))
 - Stack trace formatting is inefficient and one can not use <code>gf</code> or <code>gF</code> vim shortcuts to jump to location
   function to write status + trace to variable.
-[stacktrace_fmt.py]($code.asset('./stacktrace_fmt.py').language('python'))
+[stacktrace_fmt.py]($code.asset('stacktrace_fmt.py').language('python'))
 - Mixed double quote (`"`) and single quote (`'`) strings are invalid json
-[invalid_json.py]($code.asset('./invalid_json.py').language('python'))
+[invalid_json.py]($code.asset('invalid_json.py').language('python'))
 - `os.kill()` does not call registered cleanup function
   `atexit.register(exit_cleanup)` by daemonized threads. Must store pids of
   child processes and clean them explicitly or signal main thread via
-[signal_main_thread.py]($code.asset('./signal_main_thread.py').language('python'))
+[signal_main_thread.py]($code.asset('signal_main_thread.py').language('python'))
 - [Socket timeout can cause file-like readline() method to lose data](https://github.com/python/cpython/issues/51571), workaround
   1. Read from Kernel structure and append chunk-wise to buffer from socket until stop event (via select).
   2. After each read, try to line a line from the buffer and remove the line on success (being utf-8 etc).
@@ -61,7 +61,7 @@ Aside of these more fundamental limitations, here the [list of shennanigans](#li
 - Generic module annotation is not allowed and mypy has no explicit docs for
   this. The following does not work and `module: object` is the closest we can
   get as simple annotation.
-[module_annotation.py]($code.asset('./module_annotation.py').language('python'))
+[module_annotation.py]($code.asset('module_annotation.py').language('python'))
 - There are no scheduling and watchdog methods, which makes Python thread
   scheduling very unreliable. Unlucky schedules may cause fatal delay for
   shuffling data between daemon thread and main thread. As example, an

content/articles/shennanigans_in_zig.smd

@@ -20,7 +20,7 @@ As of ~~2024-04-04 (zig version 0.12.0-dev.3562+96bc8f17c)~~ 2024-07-01 (zig ver
 The rest of the language feels very smooth to me in contrast to the potential
 very flexible and cryptic syntax of C (see [preprocessor iceberg](https://github.com/JadLevesque/PPMP-Iceberg)).
 - Bottlenecks of array assignments not obvious via <code>@memcpy</code>:
-[perf_array_assignment.zig]($code.asset('./perf_array_assignment.zig').language('zig'))
+[perf_array_assignment.zig]($code.asset('perf_array_assignment.zig').language('zig'))
 - Signaling: Test runner allows no signaling to <code>qemu -g
   4242</code> (debugger mode). Qemu uses gdb server signaling,
   which means sending SIGKILL is necessary to kill