Finished documenting batch process.

Batch.md

@@ -4,6 +4,94 @@ Batch building is used to provide a set of AppImages for a specific version of
  LibreOffice (and it is the mechanism used to provide AppImage releases on the
 [official website](https://www.libreoffice.org/download/appimage/)).
 
+Instructions on how to build the set of AppImages are written in a simple YAML
+file, which is the only required argument of the `batch` ve; pplease provide a
+valid path to the YAML file (remember that if only the name of the YAML file,
+complete with .yml extension, is provided, is considered local to the current
+folder).
+
+Plenty of examples of those YAML files can be found inside the source
+repository, although some fields/variables of the file might need an
+explanation.
+
+## Fields of the YAML file ##
+
+Here's the definition and explanation of all the variables that can be
+indicated in the YAML file.
+
+### Basic structure ###
+
+The file requires exactly **two** sections, one called `data` and the other one called `builds`.
+
+### `data` section ###
+
+Contains the general information valid for any one of the AppImage to be
+built. `loaih` will honor the following key-value pairs:
+
+* `download`: This is the name of the folder where all the needed archives
+  would be downloaded to. Contrary to the `build` verb, using batch building
+will **conserve** all the downloads (except for daily and preleases). Defaults
+to `/var/tmp/downloads`;
+* `force`: disables the check for existing builds, thus forcing `loaih` to
+  rebuild the entire set of AppImages described in the file. Defaults to
+`False` (so: check previous existence of the build and skip it if found);
+* `repo`: this is the "public available" storage where final builds would be
+  published. It can be a local folder (and in this case it is referred as a
+"local" repo) or it can be an HTTP/HTTPS address (in which case this is
+considered as "remote" repo). See below under *Remote repositories* for more
+explanations. Defaults to `/srv/http/appimage`;
+* `remote_host`: the name of the remote host that can be reached via
+  rsync/ssh (see below under *Remote repositories* for more information).
+Defaults to '';
+* `remote_path`: the base path under which the builds would be shared.
+  Defaults to `/srv/http/appimage`;
+* `sign`: if set to true, signs every AppImages built with the default GPG
+  key. Defaults to False (do not sign builds).
+
+## `builds` section ##
+
+This section is a list of objects, each of which have the following key-pair
+values that `loaih` would honor; each object would represent a single
+AppImage:
+
+* `query`: the query to use when determining the version of the build (see
+  [Usage - versions](Version.md) for a more complete explanation). This is a
+required parameter;
+* `language`: the set of locales to support, comma separated (e.g. 'en,it,de'), or one of the predefined set: *basic*, *standard* and *full*. Defaults to 'basic' if not specified;
+* `offline_help`: whether the AppImage should contain the help pages, defined
+  as boolean value (true/false). Defaults to 'false' if not specified;
+* `portable`: whether the AppImage should be portable or not, defined as a
+  boolean value (true/false). Defaults to 'false' if not specified.
+
+## Expected behaviour ##
+
+For each of the items in the `builds` list, `loaih` does the following
+operations, in this order:
+* checks if the AppImage is already available in `repo` (`data` section). If
+  it is, the build is skipped (unless `force` has been defined in the `data`
+section);
+* checks if the binary deb archives have already been downloaded. If not,
+  downloads the required archives;
+* based on the options of each object, it unpacks the needed archives, fixes
+  the sources and builds the AppImage in a temporary folder;
+* proceeds to calculate md5 checksums of each produced file;
+* the build files are then moved to the publishing folder;
+* If needed, "generic" links to the last versions are produced and published,
+  also (e.g. when the script has just built the just released 'fresh' version of LibreOffice, it would create the necessary `LibreOffice-fresh.*.AppImage*` links;
+* if the query regarded daily builds or prereleases, removes the related
+  source packages from the download location.
+
+
+## Remote repositories ##
+
+If the parameter `repo` in the `data` section refers to a remote location,
+`loaih` can upload the new builds automatically using `rsync` and `ssh`, by
+honoring the `remote_host` and `remote_path` key-pairs.
+
+For this mechanism to work, please configure an `ssh_config` stanza for the
+host you will indicate in `remote_host` for the user you plan to use to build
+the AppImages with; also, ensure passwordless login can be performed (using
+SSH private/public key pairs).
 
 
 ---