From 5e89bf3f6a3dc88108f8ce9f9ba1bb18d1c98459 Mon Sep 17 00:00:00 2001
From: Alessandro Mauri <alemauri001@gmail.com>
Date: Sun, 6 Sep 2020 14:40:23 +0200
Subject: [PATCH] added unifficial alsa documentation page and style change

---
 src/alsadoc.md | 114 +++++++++++++++++++++++++++++++++++++++++++++++++
 src/index.md   |   2 +
 src/styles.css |  25 ++++++++---
 3 files changed, 136 insertions(+), 5 deletions(-)
 create mode 100644 src/alsadoc.md

diff --git a/src/alsadoc.md b/src/alsadoc.md
new file mode 100644
index 0000000..1d1cb00
--- /dev/null
+++ b/src/alsadoc.md
@@ -0,0 +1,114 @@
+# Unofficial ALSA API documentation
+ALSA has to be the **worst** documented API in the whole FOSS world, so since I
+had to go trough the pain of reverse-engineering other programs I thought to save
+you form the same pain. So I present to you the most half-hassed description of
+the ALSA API on the interweb.
+
+## Functions
+
+### Interfaces
+TODO
+
+### Hints
+Hints are names, descriptions and other information about sound cards, interfaces
+and others. To get access to those hints there is a family of functions.
+
+#### `snd_device_name_hint`
+Get hints from a specified card of specified interface
+
+```c
+int snd_device_name_hint (int card, const char *iface, void ***hints);
+```
+
+ARGS:
+
+* `(int)card`: specifies the card index number, -1 means all cards
+* `(char *)iface`: interface identification (like "pcm", "rawmidi", "timer", "seq")
+
+RESULT:
+
+* `(void ***)hints`: hints will receive a NULL-terminated array of device name
+hints, which can be passed to `snd_device_name_get_hint()` to extract usable values.
+When no longer needed, hints should be passed to `snd_device_name_free_hint()` to
+release resources.
+
+RETURN: `(int)` 0 on success or negative error code
+
+#### `snd_device_name_get_hint`
+Extract selected hint form hints array
+
+```c
+char* snd_device_name_get_hint (const void *hint, const char *id);
+```
+
+ARGS:
+
+* `(const void *)hint`: a pointer to a hint which can be gotten by referencing
+`hints[i]` from `snd_device_name_hint()`, where `i` is the card index
+* `(const char *)id`: hint value to extract, valid IDs are
+	- NAME: name of device
+	- DESC: description of device
+	- IOID: input / output identification ("Input" or "Output"), NULL means both
+
+RESULT: RETURN: `(char *)` gives a pointer to a string containing the requested
+hint or NULL on error, the result should be freed when done.
+
+#### `snd_device_name_free_hint`
+Free hints array
+
+```c
+int snd_device_name_free_hint (void **hints);
+```
+
+ARGS:
+
+* `(void **)hints`: hints array gotten from `snd_device_name_hint`
+
+RETURN: `(int)` 0 on success or negative code on error
+
+#### Example
+Get hints from all pcms of all cards and print them out
+
+```c
+#define _POSIX_C_SOURCE 200809L
+#include <stdio.h>
+#include <stdlib.h>
+
+#include <alsa/asoundlib.h>
+
+int main (int argc, char *argv[])
+{
+	void **hints, **n;
+	char *name, *descr, *descr1, *io;
+
+	if (snd_device_name_hint(-1, "pcm", &hints) < 0)
+		return -1;
+	n = hints;
+	while (*n != NULL) {
+		name = snd_device_name_get_hint(*n, "NAME");
+		descr = snd_device_name_get_hint(*n, "DESC");
+		io = snd_device_name_get_hint(*n, "IOID");
+		printf("%s\n", name);
+		if ((descr1 = descr) != NULL) {
+			printf("    ");
+			while (*descr1) {
+				if (*descr1 == '\n')
+					printf("\n    ");
+				else
+					putchar(*descr1);
+				descr1++;
+			}
+			putchar('\n');
+		}
+	      	if (name != NULL)
+	      		free(name);
+		if (descr != NULL)
+			free(descr);
+		if (io != NULL)
+			free(io);
+		n++;
+	}
+	snd_device_name_free_hint(hints);
+	return 0;
+}
+```
diff --git a/src/index.md b/src/index.md
index ada93ec..5a05ec0 100644
--- a/src/index.md
+++ b/src/index.md
@@ -7,3 +7,5 @@
 [Size in loc of common software](commonsizes.html)
 
 [Programs I would like to see made/remade](makesoftware.html)
+
+[Unofficial ALSA documentation](alsadoc.html)
diff --git a/src/styles.css b/src/styles.css
index c6ebe34..93bb020 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -1,6 +1,6 @@
 /* Global options */
 * {
-	text-align: justify;
+	text-align: left;
 	font-family: monospace;
 }
 
@@ -28,6 +28,21 @@ tr:nth-child(odd) {
 	background-color: #dcdcdc;
 }
 
+/* Code style */
+pre {
+	background-color: #282828;
+	color: #ebdbb2;
+	padding: 2px;
+	font-size: 14;
+	font-family: monospace;
+	tab-size: 8;
+}
+
+:not(pre) > code {
+	background-color: #f9f4d7;
+	color: #504945;
+}
+
 /* List styles */
 li {
 	font-size: 14;
@@ -41,7 +56,7 @@ p {
 }
 
 body {
-	width: 70%;
+	width: 50%;
 	margin: 0 auto;
 	background-color: #f5fffa;
 	color: black;
@@ -49,7 +64,7 @@ body {
 }
 
 html {
-	background-color: #696969;
+/*	background-color: #696969;*/
 	scroll-behavior: smooth;
 }
 
@@ -57,11 +72,11 @@ html {
 h1 {
 	text-decoration: underline;
 }
-
+/*
 h1, h2, h3, h4, h5, h6 {
 	text-align: center;
 }
-
+*/
 footer {
 	border: 1px solid black;
 }