Add: outline for a vmdb2 manual

5 files changed, 174 insertions, 0 deletions

diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..b7304f5
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,10 @@
+formats: vmdb2.en.html vmdb2.en.pdf
+en_srcs = $(wildcard en/*)
+
+all: $(formats)
+
+vmdb2.en.html: $(en_srcs) vmdb2.css
+	./format-html "$@" ${en_srcs}
+
+vmdb2.en.pdf: $(srcs)
+	./format-pdf "$@" ${en_srcs}
diff --git a/doc/en/000.mdwn b/doc/en/000.mdwn
new file mode 100644
index 0000000..e4bc243
--- /dev/null
+++ b/doc/en/000.mdwn
@@ -0,0 +1,51 @@
+---
+title: Building system images with vmdb2
+author: Lars Wirzenius
+date: work-in-progress
+...
+
+# Introduction
+
+- what is vmdb2 for?
+- how does it differ from other image building tools?
+- especially vmdebootstrap
+
+# Installation
+
+- .deb
+- git clone and run from source tree
+
+# Quick start
+
+- sample .vmdb2
+- command to run vmdb2 and produce an image
+- command to run vm using image
+
+# Configuration
+
+- command line options, list them and give summary of use
+- cliapp config files, ini and yaml, and the fact that a long
+  option is always an acceptable variable in a config file
+
+# A .vmdb2 image specification file
+
+- yaml, jinja2 syntax
+- steps to list what needs to be done to build an image
+- setting jinja2 variables from the command line
+
+# List of available steps and their configuration
+
+- list each step
+- what is the step for? examples of how it could be used
+- what mandatory and optional key/value pairs does it
+  understand? examples of their use
+- the tag concept
+
+# Examples
+
+- various spec files, explained in detail
+- simple image to run under kvm, qemu, or similar, boots with
+  normal grub (bios)
+- same but with uefi boot
+- same but software installed with ansible
+- an LVM enabled image with encrypted / but cleartext /boot
diff --git a/doc/format-html b/doc/format-html
new file mode 100755
index 0000000..88147e8
--- /dev/null
+++ b/doc/format-html
@@ -0,0 +1,15 @@
+#!/bin/sh
+
+set -eu
+
+output="$1"
+shift
+
+pandoc  -H vmdb2.css\
+        --smart \
+        --toc \
+        --chapters \
+        --number-sections \
+	--standalone \
+        --self-contained \
+        -o "$output" "$@"
diff --git a/doc/format-pdf b/doc/format-pdf
new file mode 100755
index 0000000..6915245
--- /dev/null
+++ b/doc/format-pdf
@@ -0,0 +1,19 @@
+#!/bin/sh
+
+set -eu
+
+output="$1"
+shift
+
+pandoc --smart \
+       --toc \
+       --chapters \
+       --number-sections \
+       -Vdocumentclass:report \
+       -Vgeometry:a4paper \
+       -Vfontsize:12pt \
+       -Vmainfont:FreeSans \
+       -Vsansfont:FreeSans \
+       -Vmonofont:FreeMonoBold \
+       --latex-engine=xelatex \
+       -o "$output" "$@"
diff --git a/doc/vmdb2.css b/doc/vmdb2.css
new file mode 100644
index 0000000..78cd374
--- /dev/null
+++ b/doc/vmdb2.css
@@ -0,0 +1,79 @@
+<style>
+html {
+    background: white;
+    font-family: serif;
+    margin-left: 3em;
+    margin-right: 2em;
+    margin-top: 2em;
+}
+
+form#searchform {
+    font-family: monospace;
+    text-align: right;
+}
+
+div.actions {
+    font-family: monospace;
+    text-align: right;
+}
+
+div.actions ul, div.actions li {
+    display: inline;
+}
+
+div.pageheader {
+    font-family: monospace;
+    margin-bottom: 2em;
+}
+
+div.pageheader span.title {
+    display: block;
+    font-size: 200%;
+    font-weight: bold;
+    font-family: sans-serif;
+    margin-top: 0.5em;
+}
+
+div#pagebody {
+}
+
+div.pagefooter {
+    font-family: monospace;
+    margin-top: 3em;
+}
+
+div#pagebody {
+}
+
+div#TOC ul {
+    list-style: none;
+}
+
+h1, h2, h3, h4, h5, h6 {
+    font-family: sans-serif;
+    font-weight: bold;
+    margin-top: 2em;
+}
+
+h1 {
+    font-size: 150%;
+}
+
+h2 {
+    font-size: 120%;
+}
+
+h3 {
+    font-size: 100%;
+}
+
+ul li, ol li {
+    margin-top: 0.5em;
+    margin-bottom: 0.5em;
+}
+
+pre {
+    margin-left: 4em;
+}
+
+</style>