Setup docs infra

16 files changed, 195 insertions, 28 deletions

diff --git a/.gitmodules b/.gitmodules
new file mode 100644
index 0000000..144e9f5
--- /dev/null
+++ b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "doc/style"]
+	path = doc/style
+	url = ../etc/style.git
diff --git a/README b/README
index eac7786..c6c213f 100644
--- a/README
+++ b/README
@@ -1,35 +1,20 @@
-buildos is a Debian-based in-memory, net-booted operating system specialized
-for building software with the build2 toolchain.
+This package contains the build2 operating system bootstrap scripts.
 
-Configuration
--------------
+build2 is an open source, cross-platform toolchain for building and packaging
+C++ code. Its aim is a modern build system and package manager for the C++
+language that provide a consistent, out of the box interface across multiple
+platforms and compilers. For more information see:
 
-- Network is configured via DHCP. All Ethernet intrface that have carrier are
-  tried in (some) order and the first interface that is successfully configure
-  via DHCP is used.
+https://build2.org/
 
-- Hostname is configure from the DHCP information. Failed that, a name is
-  generated based on the MAC address. @@ Maybe also kernel cmdline.
+See the NEWS file for the user-visible changes from the previous release.
 
-PXE
----
+See the LICENSE file for the distribution conditions.
 
-- Copy the kernel image and initrd to TFTP
+See the INSTALL file for the prerequisites and installation instructions.
 
-# mkdir -p /var/lib/tftpboot/buildos
-# cp buildos-image buildos-initrd /var/lib/tftpboot/buildos/
+See the doc/ directory for documentation.
 
-- Assuming the host has MAC address de-ad-be-ef-b8-da, create host-specific
-  configuration (or use 'default' for the last path component to apply to
-  all the hosts):
-
-# cat <<EOF >/var/lib/tftpboot/pxelinux.cfg/01-de-ad-be-ef-b8-da
-default buildos
-prompt 1
-timeout 50
-
-label buildos
-  menu label buildos
-  kernel /buildos/buildos-image
-  append initrd=/buildos/buildos-initrd
-EOF
+Send questions, bug reports, or any other feedback to the users@build2.org
+mailing list. You can post without subscribing. See https://lists.build2.org
+for searchable archives, posting guidelines, etc.
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 0000000..5dddec7
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,3 @@
+build2-*-manual.xhtml
+*.ps
+*.pdf
diff --git a/doc/a4.html2ps b/doc/a4.html2ps
new file mode 120000
index 0000000..4b31c06
--- /dev/null
+++ b/doc/a4.html2ps
@@ -0,0 +1 @@
+style/a4.html2ps
\ No newline at end of file
diff --git a/doc/cli.sh b/doc/cli.sh
new file mode 100755
index 0000000..a658c3b
--- /dev/null
+++ b/doc/cli.sh
@@ -0,0 +1,49 @@
+#! /usr/bin/env bash
+
+version="0.5.0"
+date="January 2017"
+
+trap 'exit 1' ERR
+set -o errtrace # Trap in functions.
+
+function info () { echo "$*" 1>&2; }
+function error () { info "$*"; exit 1; }
+
+while [ $# -gt 0 ]; do
+  case $1 in
+    --clean)
+      rm -f build2-buildos-manual.xhtml
+      rm -f *.ps *.pdf
+      exit 0
+      ;;
+    *)
+      error "unexpected $1"
+      ;;
+  esac
+done
+
+# Manuals.
+#
+
+function compile_doc () # <file> <prefix> <suffix>
+{
+  cli -I .. \
+-v version="$(echo "$version" | sed -e 's/^\([^.]*\.[^.]*\).*/\1/')" \
+-v date="$date" \
+--generate-html --html-suffix .xhtml \
+--html-prologue-file doc-prologue.xhtml \
+--html-epilogue-file doc-epilogue.xhtml \
+--output-prefix "$2" \
+--output-suffix "$3" \
+"$1"
+
+  local n="$2$(basename -s .cli $1)$3"
+
+  html2ps -f doc.html2ps:a4.html2ps -o "$n-a4.ps" "$n.xhtml"
+  ps2pdf14 -sPAPERSIZE=a4 -dOptimize=true -dEmbedAllFonts=true "$n-a4.ps" "$n-a4.pdf"
+
+  html2ps -f doc.html2ps:letter.html2ps -o "$n-letter.ps" "$n.xhtml"
+  ps2pdf14 -sPAPERSIZE=letter -dOptimize=true -dEmbedAllFonts=true "$n-letter.ps" "$n-letter.pdf"
+}
+
+compile_doc manual.cli 'build2-buildos-'
diff --git a/doc/code-box.css b/doc/code-box.css
new file mode 120000
index 0000000..e442993
--- /dev/null
+++ b/doc/code-box.css
@@ -0,0 +1 @@
+style/code-box.css
\ No newline at end of file
diff --git a/doc/common.css b/doc/common.css
new file mode 120000
index 0000000..3ddf6fc
--- /dev/null
+++ b/doc/common.css
@@ -0,0 +1 @@
+style/common.css
\ No newline at end of file
diff --git a/doc/doc-epilogue.xhtml b/doc/doc-epilogue.xhtml
new file mode 120000
index 0000000..5111ca2
--- /dev/null
+++ b/doc/doc-epilogue.xhtml
@@ -0,0 +1 @@
+style/doc-epilogue.xhtml
\ No newline at end of file
diff --git a/doc/doc-prologue.xhtml b/doc/doc-prologue.xhtml
new file mode 120000
index 0000000..e1fd108
--- /dev/null
+++ b/doc/doc-prologue.xhtml
@@ -0,0 +1 @@
+style/doc-prologue.xhtml
\ No newline at end of file
diff --git a/doc/doc.css b/doc/doc.css
new file mode 120000
index 0000000..6cb3fd5
--- /dev/null
+++ b/doc/doc.css
@@ -0,0 +1 @@
+style/doc.css
\ No newline at end of file
diff --git a/doc/doc.html2ps b/doc/doc.html2ps
new file mode 120000
index 0000000..dc19855
--- /dev/null
+++ b/doc/doc.html2ps
@@ -0,0 +1 @@
+style/doc.html2ps
\ No newline at end of file
diff --git a/doc/letter.html2ps b/doc/letter.html2ps
new file mode 120000
index 0000000..607ca58
--- /dev/null
+++ b/doc/letter.html2ps
@@ -0,0 +1 @@
+style/letter.html2ps
\ No newline at end of file
diff --git a/doc/manual.cli b/doc/manual.cli
new file mode 100644
index 0000000..22cbd13
--- /dev/null
+++ b/doc/manual.cli
@@ -0,0 +1,117 @@
+// file      : doc/manual.cli
+// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd
+// license   : MIT; see accompanying LICENSE file
+
+"\name=build2-buildos-manual"
+"\subject=buildos"
+"\title=Operating System"
+
+// NOTES
+//
+// - Maximum <pre> line is 70 characters.
+//
+
+"
+\h0#preface|Preface|
+
+This document describes \c{buildos}, the \c{build2} operating system.
+
+\h1#intro|Introduction|
+
+\c{buildos} is a GNU/Linux(Debian)-based in-memory network-booted operating
+system specialized for autonomous building of software using the \c{build2}
+toolchain. It's primary purpose is to run the \c{build2} build bot (\c{bbot}),
+build slave (\c{bslave}), or both.
+
+A machine that run an instance of \c{buildos} is called a \i{build host}. A
+build host runs the \c{bbot} and/or \c{bslave} in the \i{agent mode}. The
+actual building is performed in the virtual machines and/or containers. For
+\c{bbot} it is normally one-shot virtual machines and for \c{bslave} it is
+normally containers but can also be long-running virtual machines. Inside
+virtual machines/containers, \c{bbot} and \c{bslave} run in the \i{worker
+mode} and receive \i{build tasks} from their respective agents.
+
+\h1#boot|Booting|
+
+\c{buildos} is normally booted from the network using PXE but can also be
+booted locally from initrd directly.
+
+\h2#boot-net|Network|
+
+Here we assume that you have already established your PXE setup using
+PXELINUX. That is, you have configured a TFTP server that hosts the
+\c{pxelinux} initial bootstrap program (NBP) and configured a DHCP
+server to direct PXE client to this server/NBP.
+
+To setup PXE boot of \c{buildos}, perform the following steps:
+
+\ol|
+
+\li|Copy the kernel image and initrd to the TFTP server. For example:
+
+\
+# mkdir -p /var/lib/tftpboot/buildos
+# cp buildos-image buildos-initrd /var/lib/tftpboot/buildos/
+\
+
+|
+
+\li|Assuming the host has MAC address \c{de:ad:be:ef:b8:da}, create a
+    host-specific configuration file (or use \c{default} as the last path
+    component for a configuration that applies to all the hosts):
+
+\
+# cat <<EOF >/var/lib/tftpboot/pxelinux.cfg/01-de-ad-be-ef-b8-da
+default buildos
+prompt 1
+timeout 50
+
+label buildos
+  menu label buildos
+  kernel /buildos/buildos-image
+  append initrd=/buildos/buildos-initrd
+EOF
+\
+
+|
+
+\li|You can test the setup using QEMU/KVM, for example:
+
+\
+$ sudo kvm \
+  -m 8G \
+  -netdev tap,id=net0,script=./qemu-ifup \
+  -device e1000,netdev=net0,mac=de:ad:be:ef:b8:da \
+  -boot n
+\
+
+||
+
+\h2#boot-local|Local|
+
+During testing it is often useful to boot \c{buildos} directly from the
+kernel image and initrd files. As an example, here is how this can be done
+using QEMU/KVM:
+
+\
+sudo kvm \
+  -m 8G \
+  -netdev tap,id=net0,script=./qemu-ifup \
+  -device e1000,netdev=net0,mac=de:ad:be:ef:b8:da \
+  -kernel buildos-image -initrd buildos-initrd
+\
+
+\h1#config|Configuration|
+
+\h2#config-net|Network|
+
+Network is configured via DHCP. All Ethernet intrface that have carrier are
+tried in (some) order and the first interface that is successfully configured
+via DHCP is used.
+
+Hostname is configured from the DHCP information. Failed that, a name is
+generated based on the MAC address, in the form \c{build-xxxxxxxxxx}.
+
+@@ Maybe also kernel cmdline.
+
+"
diff --git a/doc/pre-box.css b/doc/pre-box.css
new file mode 120000
index 0000000..b9ec76c
--- /dev/null
+++ b/doc/pre-box.css
@@ -0,0 +1 @@
+style/pre-box.css
\ No newline at end of file
diff --git a/doc/style b/doc/style
new file mode 160000
+Subproject 6afac719afc627d4c74dfbaa282b049f6f96e90
diff --git a/doc/toc.css b/doc/toc.css
new file mode 120000
index 0000000..477b331
--- /dev/null
+++ b/doc/toc.css
@@ -0,0 +1 @@
+style/toc.css
\ No newline at end of file