script: New document, describing HorizonScript

5 files changed, 64 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
index e83c994..a8b5439 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
 devel/requirements/html
+devel/script/html
 devel/vision/html
diff --git a/devel/script/1_introduction.xml b/devel/script/1_introduction.xml
new file mode 100644
index 0000000..e746619
--- /dev/null
+++ b/devel/script/1_introduction.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter label="1" id="introduction">
+    <title>Introduction</title>
+    <section id="purpose">
+        <title>Purpose</title>
+        <para>This document describes the file format, including logical and on-disk formats, for HorizonScript.  HorizonScript is the file read in by the Project Horizon system to configure Adélie Linux on a target computer.</para>
+    </section>
+    <section id="conventions">
+        <title>Document Conventions</title>
+        <para>Text formatted like <literal>this text</literal> is meant to represent a literal value, or a value that will appear verbatim in the HorizonScript.</para>
+        <para>Text formatted like <replaceable>this text</replaceable> is replacaeable, or a value that will vary based on User or Administrator decisions.</para>
+    </section>
+    <section id="audience">
+        <title>Intended Audience</title>
+        <para>This document is intended to be used by developers and researchers, to implement Project Horizon 1.0 and study how Project Horizon accomplishes its goals of installing and configuring Adélie Linux.  This document may also be used by Administrators intended to hand-write their own HorizonScript, though this activity is only recommended for advanced users.  This document is additionally intended to be used by the wider Adélie Linux community to determine how Project Horizon is designed, its intended purposes, and for development of future releases of Project Horizon.</para>
+    </section>
+</chapter>
diff --git a/devel/script/2_keys.xml b/devel/script/2_keys.xml
new file mode 100644
index 0000000..29a8eb3
--- /dev/null
+++ b/devel/script/2_keys.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter label="2" id="keys">
+    <title>HorizonScript Keys</title>
+    <section id="key_intro">
+        <title>Introduction</title>
+        <para>A HorizonScript file is, at its core, a collection of values that determine the actions and configuration values used to transform a computer from an indeterminate state to a well-known state running Adélie Linux.  These values are categorised into <firstterm>key</firstterm>s, which is a logical unit of a value.</para>
+        <para>This chapter defines and specifies for every valid key for a HorizonScript file: its name, its purpose, its format, and one or more example values with explanations.</para>
+    </section>
+</chapter>
diff --git a/devel/script/3_ondisk.xml b/devel/script/3_ondisk.xml
new file mode 100644
index 0000000..951989e
--- /dev/null
+++ b/devel/script/3_ondisk.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter label="3" id="ondisk">
+    <title>On-Disk Format</title>
+    <section id="TBD">
+        <title>TBD</title>
+        <para>TODO: you really thought we figured this out? :(</para>
+    </section>
+</chapter>
diff --git a/devel/script/script.xml b/devel/script/script.xml
new file mode 100644
index 0000000..56eba3a
--- /dev/null
+++ b/devel/script/script.xml
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+               <!ENTITY chap1 SYSTEM "1_introduction.xml">
+               <!ENTITY chap2 SYSTEM "2_keys.xml">
+               <!ENTITY chap3 SYSTEM "3_ondisk.xml">
+]>
+<book>
+    <bookinfo>
+        <title>HorizonScript Specification</title>
+        <authorgroup>
+            <author><firstname>A.</firstname><surname>Wilcox</surname><affiliation><orgname>Adélie Linux</orgname></affiliation></author>
+        </authorgroup>
+        <edition>Specification for HorizonScript (Horizon release 1.0): Draft</edition>
+        <pubdate>2019</pubdate>
+        <copyright>
+            <year>2019</year>
+            <holder>Adélie Linux</holder>
+        </copyright>
+        <legalnotice>
+            <para>Development documentation for Project Horizon is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.</para>
+            <para>You should have received a copy of the license along with this work. If not, see <ulink url="https://creativecommons.org/licenses/by-nc-sa/4.0/"><citetitle>the Creative Commons Web site</citetitle></ulink>.</para>
+        </legalnotice>
+        <abstract><para>This document describes the file format of HorizonScript.  HorizonScript is the input file used for Project Horizon, the installation system for Adélie Linux.</para></abstract>
+    </bookinfo>
+    &chap1;
+    &chap2;
+    &chap3;
+</book>