path: root/devel/script/2_keys.xml

<?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>
    <section id="reqd_keys">
        <title>Required Keys</title>
        <para>Each key specified in this section is required to be present in a HorizonScript.  If any key from this section is missing, the HorizonScript will be considered invalid and Horizon Runner will not execute it.</para>
        <section id="network">
            <title><literal>network</literal></title>
            <formalpara id="network.name">
                <title>Name</title>
                <para><literal>network</literal></para>
            </formalpara>
            <formalpara id="network.purpose">
                <title>Purpose</title>
                <para>The <literal>network</literal> key determines if the target computer will support networking or not.  If the value is <literal>true</literal>, the computer will support networking, and at least one <literal>netaddress</literal> key will then be required.</para>
            </formalpara>
            <formalpara id="network.format">
                <title>Format</title>
                <para>The <literal>network</literal> key is a Boolean value &mdash; valid values are <literal>true</literal> and <literal>false</literal>.  <literal>network</literal> must appear exactly once in a HorizonScript.</para>
            </formalpara>
            <formalpara id="network.example">
                <title>Example</title>
                <para>
                    <example>
                        <title>The <literal>network</literal> Key</title>
                        <programlisting>
network true
                        </programlisting>
                        <para>This enables networking for the target computer.</para>
                    </example>
                </para>
            </formalpara>
        </section>
        <section id="hostname">
            <title><literal>hostname</literal></title>
            <formalpara id="hostname.name">
                <title>Name</title>
                <para><literal>hostname</literal></para>
            </formalpara>
            <formalpara id="hostname.purpose">
                <title>Purpose</title>
                <para>The <literal>hostname</literal> key determines the hostname of the target computer.  This key is always required, even when the target computer will not participate in a network.  The computer's hostname is used on shell prompts, most window manager launchers, and in log files.</para>
            </formalpara>
            <formalpara id="hostname.format">
                <title>Format</title>
                <para>The <literal>hostname</literal> key is a string value that must contain only alphanumeric characters and optionally one or more '.' characters.  If hostname contains one or more '.' characters, all content before the first '.' is considered the hostname, and all content after the first '.' is considered the domain name.  <literal>hostname</literal> must appear exactly once in a HorizonScript.</para>
            </formalpara>
            <formalpara id="hostname.examples">
                <title>Examples</title>
                <para>
                    <example>
                        <title>The <literal>hostname</literal> Key &mdash; Setting a Host Name</title>
                        <programlisting>
hostname gwyn
                        </programlisting>
                        <para>This sets the hostname of the target computer to <literal>gwyn</literal>.</para>
                    </example>
                    <example>
                        <title>The <literal>hostname</literal> Key &mdash; Setting a Host Name and Domain Name</title>
                        <programlisting>
hostname gwyn.foxkit.internal
                        </programlisting>
                        <para>This sets the hostname of the target computer to <literal>gwyn.foxkit.internal</literal>.</para>
                    </example>
                </para>
            </formalpara>
        </section>
    </section>
    <section id="opt_keys">
        <title>Optional Keys</title>
        <para>Each key specified in this section may be present in a HorizonScript.  This section additionally defines the default value or action taken if the specified key is not present.</para>
        <section id="language">
            <title><literal>language</literal></title>
            <formalpara id="language.name">
                <title>Name</title>
                <para><literal>language</literal></para>
            </formalpara>
            <formalpara id="language.purpose">
                <title>Purpose</title>
                <para>The <literal>language</literal> key determines the default natural language for the target computer.  The value of this key will be used to configure the <envar>LANG</envar> and <envar>LC_ALL</envar> environment variables, in addition to installing language packs for certain software.</para>
            </formalpara>
            <formalpara id="language.format">
                <title>Format</title>
                <para>The <literal>language</literal> key is a string value that specifies a valid locale code.  A locale code must match one of the following formats: <replaceable>xx</replaceable>, or <replaceable>xx</replaceable><literal>_</literal><replaceable>YY</replaceable>, or <replaceable>xx</replaceable><literal>_</literal><replaceable>YY</replaceable><literal>.UTF-8</literal>, where <replaceable>xx</replaceable> is a valid ISO 639-1 language code, and <replaceable>YY</replaceable> is a valid ISO 3166-1 country code.  <literal>language</literal> may appear at most once in a HorizonScript.</para>
            </formalpara>
            <formalpara id="language.default">
                <title>Default</title>
                <para>If the <literal>language</literal> key is not present, no setting will be defined for the <envar>LANG</envar> or <envar>LC_ALL</envar> environment variables.  Most software treats this as either "C.UTF-8" or "en_US.UTF-8".  No language packs will be installed for software that supports multiple language; due to English being the <emphasis role="italics">de facto</emphasis> language of software engineering, this implies all software will run in English.</para>
            </formalpara>
            <formalpara id="language.examples">
                <title>Examples</title>
                <para>
                    <example>
                        <title>The <literal>language</literal> Key &mdash; Simple Language</title>
                        <programlisting>
language cy
                        </programlisting>
                        <para>This sets the language of the target computer to Welsh.</para>
                    </example>
                    <example>
                        <title>The <literal>language</literal> Key &mdash; Language with Country Localisation</title>
                        <programlisting>
language fr_CA
                        </programlisting>
                        <para>This sets the language of the target computer to Canadian French.</para>
                    </example>
                </para>
            </formalpara>
        </section>
        <section id="keymap">
            <title><literal>keymap</literal></title>
            <formalpara id="keymap.name">
                <title>Name</title>
                <para><literal>keymap</literal></para>
            </formalpara>
            <formalpara id="keymap.purpose">
                <title>Purpose</title>
                <para>The <literal>keymap</literal> key determines the keyboard layout used for input on the target computer.</para>
            </formalpara>
            <formalpara id="keymap.format">
                <title>Format</title>
                <para>The <literal>keymap</literal> key is a string value that specifies the name of a keyboard layout.  Valid keyboard layouts are listed in <filename class="file">/etc/console-setup/ckb/rules/xorg.lst</filename> under the <literal>! layout</literal> heading.  <literal>keymap</literal> may appear at most once in a HorizonScript.</para>
            </formalpara>
            <formalpara id="keymap.default">
                <title>Default</title>
                <para>If the <literal>keymap</literal> key is not present, the target computer will use the default keyboard settings from Linux.  These settings are architecture-dependent, but almost universally use a US QWERTY-style layout.</para>
            </formalpara>
            <formalpara id="keymap.example">
                <title>Example</title>
                <para>
                    <example>
                        <title>The <literal>keymap</literal> Key</title>
                        <programlisting>
keymap fr
                        </programlisting>
                        <para>This sets the keyboard layout of the target computer to French AZERTY.</para>
                    </example>
                </para>
            </formalpara>
        </section>
        <section id="firmware">
            <title><literal>firmware</literal></title>
            <formalpara id="firmware.name">
                <title>Name</title>
                <para><literal>firmware</literal></para>
            </formalpara>
            <formalpara id="firmware.purpose">
                <title>Purpose</title>
                <para>The <literal>firmware</literal> key determines if the target computer will load potentially insecure, proprietary firmware.</para>
            </formalpara>
            <formalpara id="firmware.format">
                <title>Format</title>
                <para>The <literal>firmware</literal> key is a Boolean value &mdash; valid values are <literal>true</literal> and <literal>false</literal>.  <literal>firmware</literal> may appear at most once in a HorizonScript.</para>
            </formalpara>
            <formalpara id="firmware.default">
                <title>Default</title>
                <para>If the <literal>firmware</literal> key is not present, the target computer will not load proprietary firmware.  This is to ensure the integrity, security, and reliability of the target computer.</para>
            </formalpara>
            <formalpara id="firmware.example">
                <title>Example</title>
                <para>
                    <example>
                        <title>The <literal>firmware</literal> Key</title>
                        <programlisting>
firmware false
                        </programlisting>
                        <para>This explicitly disables loading of firmware on the target computer.</para>
                    </example>
                </para>
            </formalpara>
        </section>
    </section>
</chapter>