Initial commit. In a broken state, do not use.

build/doc/i18n/shell/workflow.md

@@ -0,0 +1,197 @@
+
+# Shell Internationalization Workflow
+
+To provide translations for shell scripts we use the gettext package.
+
+## Preparing a Shell Script for Translation
+
+Shell scripts contain `echo` commands to provide user feedback.
+
+We need for the strings displayed by an `echo` command to be displayed in the language the user of 
+the machine is using.
+
+In the top of the script we put these lines:
+
+	export TEXTDOMAIN=myscript
+	export TEXTDOMAINDIR=/usr/share/locale
+
+	. gettext.sh
+
+In the above example `myscript` is an example script name.
+
+The `TEXTDOMAINDIR` above contains the usual path to localization for a typical Linux installation. 
+It may be raplaced with:
+
+	export TEXTDOMAINDIR=$PWD/locale
+
+For testing a script's translation.
+
+The script author changes typical `cho` of this syntax:
+
+	echo 'Press any key to continue'
+
+With:
+
+	echo $(gettext "Press any key to continue") ; echo
+
+We place an extra `echo` with no arguments at the end because the `gettext` function does not add a line-feed.
+
+The `gettext` function is contained in the `gettext.sh` script included at the top of the script.
+
+If an echoed string contains any shell variables they must be replaced.
+
+For example:
+
+	echo "Program name: $0"
+
+Becomes:
+
+	PROGNAME=$0
+	echo $(eval_gettext "Prog name: \$PROGNAME") ; echo
+
+The `eval_gettext` function is used instead of `gettext` and the dolla-sign is `escaped` with a 
+back-slash.
+
+Again an extra `echo` is put in after the command to echo a translated string.
+
+## Extracting Strings into a Portable Object Template (.pot)
+
+Now we run `xgettext` against our script to create a file of strings to translate.
+
+We do this in this fashion:
+
+   xgettext -L Shell -o myscript.pot myscript
+
+This reads all the `echo` commands which contain references to the `gettext` and `eval_gettext` functions and writes them to a `.pot` (portable object template) file.
+
+Here is a simple example of the contents of a `.pot` file for a script which contains only one `echo` command:
+
+
+
+	# SOME DESCRIPTIVE TITLE.
+	# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
+	# This file is distributed under the same license as the PACKAGE package.
+	# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+	#
+	#, fuzzy
+	msgid ""
+	msgstr ""
+	"Project-Id-Version: PACKAGE VERSION\n"
+	"Report-Msgid-Bugs-To: \n"
+	"POT-Creation-Date: 2017-04-19 22:52+0100\n"
+	"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+	"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+	"Language-Team: LANGUAGE <LL@li.org>\n"
+	"Language: \n"
+	"MIME-Version: 1.0\n"
+	"Content-Type: text/plain; charset=UTF-8\n"
+	"Content-Transfer-Encoding: 8bit\n"
+	#
+	#: myscript:10
+	#, sh-format
+	msgid "Hello world: $PROGNAME"
+	msgstr ""
+
+
+In the above example there are values in upper-case at the top in the comments which should be filled out with the details of the package-name, and the author details etc.
+
+And this line:
+
+    "Content-Type: text/plain; charset=CHARSET\n"
+
+Should be changed to read:
+
+    "Content-Type: text/plain; charset=UTF-8\n"
+
+Or whichever character-set we are using.
+
+## The Translation Process
+
+The first-cut `.pot` file should be passed to a translator with the name changed to drop the ending `t`:
+
+    cp myscript.pot myscript.po
+
+Now give the `.po` (portable object) file to a translator.
+
+After the line which reads:
+
+      "Content-Transfer-Encoding: 8bit\n"
+
+There will be entries of the form:
+
+      msgid "Some string in the original language"
+      msgstr ""
+
+A translator places the translation of the string in the `msgid` entry in the `msgstr` entry between the	quotes.
+
+The translator _MUST_ preserve any shell variable reference that is in the original string. For example:
+
+    msgid "Attention! $ERRORCODE"
+    	  msgstr "Achtung! $ERRORCODE"
+
+In this way a translator goes right through the file and translates the strings, leaving the `msgid` entries as-is, and placing their translations in the corresponding `msgstr` entries.
+
+## Creating `Machine Object` Files
+
+The files which will actually be used when a script runs, to provide translated strings is a `.mo` file.
+
+We create this from a `.po` file like this:
+
+   msgfmt -o myscript.mo myscript.po
+
+Which will create `myscript.mo` from `myscript.po`.
+
+## Merging New Strings
+
+Of course the development of a complex script is never static and it may be necessary to add new strings, or to remove old ones. We can use another utility to `merge` strings from a new `.pot` file into our `.po` file and re-create our `.mo` file.
+
+For this we use `msgmerge`, like this:
+
+    msgmerge -U myscript.po myscript.pot
+
+This will search the `.pot` file for new or deleted strings and merge them into the `.po` file. In this way previous translation work is not lost when things change.
+
+And again we then create a new `.mo` file from the update `.po` file.
+
+## Installing a Translation
+
+Using our `myscript` example from above, the `.mo` file is installed in:
+
+      /usr/share/locale/<LANG>/LC_MESSAGES/myscript.mo
+
+Where <ALANG> is the language into which the script has been translated.
+
+For example, for Brazilian Portuguese:
+
+    /usr/share/locale/pt_BR/LC_MESSAGES/myscript.mo
+
+## The Worklow in Short
+
+1. Script is written and tested, including gettext support.
+2. Run `xgettext` to extract all `echo` strings into a `.pot` file.
+3. Rename the `.pot` file to `.po` and pass to translator.
+4. When step 3 is done, run `msgfmt` to create the `.mo` file.
+5. Install the `.mo` file (after testing).
+6. If something new is written in the script, go to step 2 and repeat to step 5.
+
+## Notes/Suggestions
+
+The `.po` files to be translated should probably either be contained in a directory structure which clearly defines the language, or should contain the language in the file-name, although the completed `.mo` file cannot.
+
+So, for `myscript`, perhaps:
+
+    myscript/
+		en/myscript.en.po (English)
+				fr/myscript.fr.po (French)
+							pt_BR/myscript.pt_BR.po (Brazilian Portuguese)
+
+
+## License
+
+This document is licensed under the creativecommons.org, 'Attribution-NonCommercial-ShareAlike 4.0 
+International' license:
+
+https://creativecommons.org/licenses/by-nc-sa/4.0/ 
+
+2017 Mike Ray, <mike.ray@btinternet.com>
+

build/doc/image/Build in Stages.md

@@ -0,0 +1,112 @@
+# Building an Image in Stages #
+This document describes how to use the build stage scripts to perform a more manual build.
+# Introduction #
+Normally, in order to build an F123Light image for a Raspberry Pi computer, the script at build/build.sh is used, along with the configuration file that has the desired options configured. *See README.md at the top level of this repository for full documentation of the automated build process.* This document describes a more manual build that offers better control of the build process by using the stage scripts in build/scripts individually, using command line options rather than a configuration file. It is assumed that each script will be called from the build/scripts directory in this repository. Each script must be run as root, either as the logged in user or via sudo. Script calls in this document are written for sudo users; if not using sudo, just remove sudo from the beginning of the command line. It is also recommended that these scripts be called in the order listed below, but the build system is tolerant of some deviations from this order, as well as multiple calls in some cases. For example, it is possible to run gsettings either before or after aur-install, but the non-root user is required in order to build AUR packages or set gsettings keys, so config-base must run before either aur-install or gsettings. On the other hand, pacstrap may run any number of times using the same mount point, at any point in the build process, as long as its first run comes before config-base, as config-base requires at least a minimal system to be installed.
+# rpi-image-tool #
+This script creates, mounts, unmounts and manipulates two-partition Raspberry Pi image files.
+## usage ##
+  ./rpi-image-tool -h
+  sudo ./rpi-image-tool <operation> <argument> [options]
+## Operations, arguments and options ##
+**-N <imagefile> -w <workdirectory> -c <blockcount> [-z blocksize] [-s <split>] [-b <bootlabel>] [-r <rootlabel>]**  
+Create a new image with the given filename and parameters, then mount it.  
+*-w <workdirectory>*  
+The work directory where the image is mounted. Package caches are also stored under this directory.  
+*-z <blocksize>*  
+The block size used when writing the empty image file. May be a number of bytes or a number with a K, M or G suffix, representing kilobytes, megabytes or gigabytes. Default is 1MB.  
+*-c <count>*  
+The number of blocks to be written to the empty image file.  
+*-s <split>*  
+Determines the size of the boot partition. May be a number of bytes or a number of kilobytes, megabytes or gigabytes, suffixed by K, M or G. Default is 64MB.  
+*-b <bootlabel>*  
+Specify the volume label of the boot partition. Default is rpi-boot.  
+*-r <rootlabel>*  
+Specify the volume label of the root partition. Default is rpi-root.
+
+**-M <imagefile> -w <workdirectory>**  
+Mount the specified image file under the specified work directory.
+
+**-D <device> -w <workdirectory>**  
+Mount the specified device under the specified work directory. Device must be a two-partition Raspberry Pi image.
+
+**-C <workdirectory>**  
+Unmount a mounted image and cleanup the specified work directory, with the exception of package caches, which are always preserved.
+
+**-h**  
+Currently not fully implemented: display usage message.
+# pacstrap #
+This script installs packages to a mounted image or to the directory of your choice.
+## Usage ##
+  ./pacstrap -h
+  sudo ./pacstrap [-d] [-c <cachedirectory>] -l <packagelist> <systemroot>
+## Options and Arguments ##
+*-d*  
+Install packages to a directory rather than a mount point.
+
+*-c <cachedirectory>*  
+Use <cachedirectory> to store the persistent package cache.
+
+*-l <packagelist>*  
+Install all packages listed in <packagelist.
+
+*<systemroot>*  
+The top level root of the installed system. Must be a mount point, unless *-d* is specified.
+
+*-h*  
+Currently not fully implemented: display usage message.
+# config-base #
+Configures the base system, including  the hostname, root password, non-root username/password and system services.
+## Usage ##
+./config-base -h  
+sudo ./config-base [-o <hostname] [-r <rootpassword>] [-l <locale>] [-u <username>] [-p <userpassword>] <systemroot>
+## Options and Arguments ##
+*-o <hostname>*  
+The hostname of the installed system. Default is alarmpi.
+
+*-r <rootpassword>*  
+The password of the root user. Default is root.
+
+*-l <locale>*
+The system locale (must exist in /etc/locale.gen)
+
+*-u <username>*  
+The username of the non-root user. Default is alarm.
+
+*-p <userpassword>*  
+The password of the non-root user. Default is alarm.
+
+*systemroot>*  
+The top level root of the installed system.
+
+*-h*  
+Currently not fully implemented: display usage message.
+# aur-install #
+Builds and installs packages from the Arch User Repository (AUR), using the specified package list.
+## Usage ##
+./aur-install -h  
+sudo ./aur-install -l <packagelist> <systemroot>
+## Options and arguments ##
+*-l <packagelist>*  
+The file containing the list of packages to be built and installed.
+
+*<systemroot>*  
+The top level root directory of the installed system.
+*-h*  
+Currently not fully implemented: display usage message.
+# services-enable #
+Enables the specified systemd services in the specified system root.
+## Usage ##
+sudo ./services-enable <systemroot> <service> [service ...]
+## Arguments ##
+*<systemroot>*
+The top level root directory of the installed system.
+
+*<service> [service ...]*
+One or more services to be enabled at boot time. All services must exist on the system image, as systemd is used to enable each service inside of a chroot.
+# gsettings #
+Sets various gsettings keys. This script must only be run if a gsettings compatible desktop has been installed.
+## usage ##
+sudo ./gsettings <systemroot>
+## Options and Arguments ##
+*<systemroot>*  
+The top level root directory of the installed system.