Asciidoc (#71)

use asciidoc for the automatic toc

README.adoc

@@ -1,48 +1,43 @@
-![microzig logo](design/logo-text-auto.svg)
+:imagesdir: design
+:toc: macro
 
-[![discord](https://img.shields.io/discord/824493524413710336.svg?logo=discord)](https://discord.gg/ShUWykk38X)
+image::logo-text-auto.svg[]
 
-## NOTE: in development
+image::https://img.shields.io/discord/824493524413710336.svg?logo=discord[link=https://discord.gg/ShUWykk38X]
 
-APIs will likely break in the future
+[NOTE]
+This is in development, breaks in the API are bound to happen
 
-# Table of Contents
+toc::[]
 
-- [Contributing](#contributing)
+== Contributing
-- [Introduction](#introduction)
-- [How to](#how-to)
-  - [Embedded project with "supported" chip/board](#embedded-project-with-supported-chipboard)
-  - [Embedded project with "unsupported" chip](#embedded-project-with-unsupported-chip)
-  - [Interrupts](#interrupts)
 
-<!-- Created by https://github.com/ekalinin/github-markdown-toc -->
+Please see the https://github.com/orgs/ZigEmbeddedGroup/projects/1/views/1[project page], its used as a place to brainstorm and organize work in ZEG.
-
-## Contributing
-
-Please see the [project page](https://github.com/orgs/ZigEmbeddedGroup/projects/1/views/1), its used as a place to brainstorm and organize work in ZEG.
 There will be issues marked as `good first issue`, or drafts for larger ideas that need scoping/breaking ground on.
 
-## Introduction
+== Introduction
 
-This repo contains the infrastructure for getting started in an embedded Zig project, as well as some code to interact with some chips/boards. Specifically it offers:
+This repo contains the infrastructure for getting started in an embedded Zig project, as well as some code to interact with some chips/boards.
+Specifically it offers:
 
-- a single easy-to-use builder function that:
+* a single easy-to-use builder function that:
-  - generates your linker script
+** generates your linker script
-  - sets up packages and start code
+** sets up packages and start code
-- generalized interfaces for common devices, such as UART.
+* generalized interfaces for common devices, such as UART.
-- device drivers for interacting with external hardware
+* device drivers for interacting with external hardware
-- an uncomplicated method to define [interrupts](#interrupts)
+* an uncomplicated method to define xref:interrupts[interrupts]
 
-## How to
+== How to
 
 Here's a number of things you might be interested in doing, and how to achieve them with microzig and other ZEG tools.
 
-### Embedded project with "supported" chip/board
+=== Embedded project with "supported" chip/board
 
 Start with an empty Zig project by running `zig init-exe`, and add microzig as a git submodule (or your choice of package manager).
 Then in your `build.zig`:
 
-```zig
+[source,zig]
+----
 const std = @import("std");
 const microzig = @import("path/to/microzig/src/main.zig");
 
@@ -68,12 +63,13 @@ pub fn build(b: *std.build.Builder) !void {
     exe.setBuildMode(.ReleaseSmall);
     exe.install();
 }
-```
+----
 
 `zig build` and now you have an executable for an Arduino Nano.
 In your application you can import `microzig` in order to interact with the hardware:
 
-```zig
+[source,zig]
+----
 const microzig = @import("microzig");
 
 // `microzig.chip.registers`: access to register definitions
@@ -81,20 +77,21 @@ const microzig = @import("microzig");
 pub fn main() !void {
     // your program here
 }
-```
+----
 
-### Embedded project with "unsupported" chip
+=== Embedded project with "unsupported" chip
 
 If you have a board/chip that isn't defined in microzig, you can set it up yourself!
 You need to have:
 
-- SVD or ATDF file defining registers
+* SVD or ATDF file defining registers
-- flash and ram address and sizes
+* flash and ram address and sizes
 
-First use [regz](https://github.com/ZigEmbeddedGroup/regz) to generate the register definitions for your chip and save them to a file.
+First use https://github.com/ZigEmbeddedGroup/regz[regz] to generate the register definitions for your chip and save them to a file.
 Then your `build.zig` is going to be the same, but you'll define the chip yourself:
 
-```zig
+[source,zig]
+----
 const nrf52832 = Chip{
     .name = "nRF52832",
     .path = "path/to/generated/file.zig",
@@ -108,18 +105,19 @@ const nrf52832 = Chip{
 const backing = .{
     .chip = nrf52832,
 };
-```
+----
 
-NOTE: `regz` is also still in development, and while it tends to generate code well, it's possible that there will be errors in the generated code!
+[NOTE]
+`regz` is also still in development, and while it tends to generate code well, it's possible that there will be errors in the generated code!
 Please create an issue if you run into anything fishy.
 
-### Interrupts
+=== Interrupts
 
 The current supported architectures for interrupt vector generation are ARM and AVR.
 To define the Interrupt Service Routine (ISR) for a given interrupt, you create a function with the same name in an `interrupts` namespace:
 
-```zig
+[source,zig]
-
+----
 pub const interrupts = struct {
     pub fn PCINT0() void {
       // interrupt handling code
@@ -129,7 +127,7 @@ pub const interrupts = struct {
 pub fn main() !void {
     // my application
 }
-```
+----
 
 We're using compile-time checks along with the generated code to determine the list of interrupts.
 If a function is defined whose name is not in this list, you'll get a compiler error with the list of interrupts/valid names.