Updated documentation with core concepts of the script. Updated all the pages to link the core concepts.

Batch.md

@@ -23,7 +23,8 @@ indicated in the YAML file.
 
 ### Basic structure ###
 
-The file requires exactly **two** sections, one called `data` and the other one called `builds`.
+The file requires exactly **two** sections, one called `data` and the other
+one called `builds`.
 
 ### `data` section ###
 
@@ -92,7 +93,6 @@ The script would build all the AppImages silently by default (and likely,
 seemingly stuck); if you need to follow the building process, use the `-v` (or
 `--verbose`) flag, which is the only option available for the `batch` verb.
 
-
 ## Remote repositories ##
 
 If the parameter `repo` in the `data` section refers to a remote location,
@@ -104,6 +104,7 @@ 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).
 
-
 ---
-[Home](Home.md) — [Prerequisites](Prerequisites.md) — [Installation](Install.md) — [Usage - versions](Version.md) — [Usage - manual build](Build.md)
+[Home](Home.md) — [Prerequisites](Prerequisites.md) —
+[Installation](Install.md) — [Core concepts](Concepts.md) —
+[Usage - versions](Version.md) — [Usage - manual build](Build.md)

Build.md

@@ -73,4 +73,6 @@ quite explicit at this point; use it if you would like to build the same
 version but with different options consecutively).
 
 ---
-[Home](Home.md) — [Prerequisites](Prerequisites.md) — [Installation](Install.md) — [Usage - versions](Version.md) — [Usage - batch build](Batch.md)
+[Home](Home.md) — [Prerequisites](Prerequisites.md) —
+[Installation](Install.md) — [Core concepts](Concepts.md) —
+[Usage - versions](Version.md) — [Usage - batch build](Batch.md)

Concepts.md

@@ -0,0 +1,171 @@
+# Core concepts of the script #
+
+This page describes some core concepts behind the options of `loaih`.
+
+## Manual builds versus bulk/batch builds ##
+
+The `loaih` script can be used to produce a single, personal release of
+LibreOffice packaged as AppImage (that will hardly be shared with everyone
+else), as well as a full set of AppImages that can be shared with other people
+for ease of consumption.
+
+The single manual build is implemented with the `build` verb, while the
+batch/bulk builds is supported with the `batch` verb of the `loaih`
+command.
+Since the two use cases are largely different, when developing `loaih` we
+chose to distinguish the default behaviour of the options of the command based
+on the verb.
+
+The concepts behind the options available to both `build` and `batch` verbs
+are explained in the rest of this page; the actual use of the two verbs is
+explained in the relative pages: [Usage - manual build](Build.md) and [Usage -
+batch build](Batch.md).
+
+## Language support ##
+
+The `loaih` script can include in your AppImage the language support you
+prefer, by the use of the `--languages` option, or in short `-l`.
+
+You can specify a single translation of LibreOffice, in addition to the
+standard English, to be included in your build like:
+
+    loaih build daily -l 'zh-CN'
+
+Or, you can provide a set of languages to include in a similar way:
+
+    loaih build daily -l 'pt,pt-BR'
+
+The command recognises, also, three different sets of languages:
+
+* `basic`, which includes just English and British English;
+* `standard`, which includes English, Arabic, German, British English,
+  Spanish, French, Japanese, Korean, Portuguese, Brasilian Portuguese,
+Russian, Standard Chinese and Taiwanese Chinese;
+* `full`, which includes all the languages supported by LibreOffice at the
+  time of the specific release.
+
+They can be used like:
+
+    loaih build daily -l standard
+
+The default value, both for `build` and `batch` verbs, for the `--languages`
+option is `basic`.
+
+## Offline help ##
+
+The `loaih` script will **not** include, by default, the offline help pages
+for the chosen release, for both the `build` and `batch` verbs.
+
+However, you can change the behaviour of the `build` verb using the
+`--offline-help` option, or in short `-o`: when used, this option will honor
+the value of the `--languages` option and include the help pages for all the
+languages that have been selected by the user.
+
+## Updatability ##
+
+Updatability for an AppImage means to provide support to use the
+[zsync2](https://github.com/AppImageCommunity/zsync2) utility to update a
+previously downloaded AppImage. This tool permits to avoid re-downloading the
+entire AppImage file, but to leverage the webserver to send only the different
+chunks of the AppImage file from the local version.
+
+Since the size of the AppImages are different based on language support,
+offline help pages inclusion and so on, using `zsync2` to download a newly
+built image is not always beneficial.
+
+For an AppImage to be updatable means that the newly built AppImage has to be
+publicly available on a web server that supports downlads in chunks, the
+presence in the same folder of the AppImage file of a specific `.zsync` file
+and the usage, by the final user, of the `zsync2` tool.
+
+By default, the `loaih` script **does not** build an updatable AppImage when
+using the `build` verb (manual build), however it does when using
+the `batch` verb instead.
+
+To revert the default behaviour of the `build` verb, you can use the
+`--updatable` option (in short, `-u`), which forces `loaih` to build also the
+`.zsync` file required to update a previous AppImage.
+
+## Portability ##
+
+The `loaih` command can produce AppImages that uses a different profile path
+than the default LibreOffice one --- this is jergally known as "portable"
+AppImage.
+
+Portable versions greatly help when debugging an issue in a specific version
+of LibreOffice and the debugger wants to be sure to exclude his own personal
+settings of LibreOffice when doing so.
+
+The `loaih` command builds, for both the `build` and `batch` verbs, an
+AppImage that is **not** considered "portable": which means it uses the
+default profile folder (which, for documentation purposes, is
+`~/.config/libreoffice/4/user`).
+
+If you want to build a "portable" version of an AppImage, be sure to include
+with the `build` verb the option `--portable` (in short, `-p`): this will
+change the profile path of the user settings of the LibreOffice AppImage to
+`~/.config/libreoffice/<major-version>/user` folder.
+
+## Signing ##
+
+When releasing an AppImage, the developer can choose to sign the AppImage with
+his own GPG signature.
+
+`loaih` can obviously sign your AppImage using your default GPG key, however
+it **does not** do it by default with the `build` verb (we assume not everyone
+would have the necessity to sign the AppImage, nor everyone possesses a valid
+GPG key). With the `batch` verb it does by default, instead.
+
+If you want to sign your AppImage with your default GPG key, be sure to add
+the option `--sign` (or in short `-s`).
+
+## Checksums ##
+
+When releasing a large file (like the LibreOffice AppImages are), developers
+usually choose to provide a checksum of the file produced by commonly known
+hashing algorithms. Of course, this is not needed when you are building an
+AppImage on your own machine for your own use.
+
+As such, the `batch` verb produces checksums for each of the file produced by
+the build process; instead, the `build` verb **does not** by default.
+
+If you want your AppImage to be accompanied with its own checksums, you can
+provide the command with the `--checksums` option (in short, `-e`): `loaih`
+will build your AppImage and produce an `.md5` file of each of the output
+file, which contains the checksum for the file with MD5 algorithms.
+
+You can then check your built AppImage for example with:
+
+    md5sum -c LibreOffice-24.2.0.3.basic-x86_64.AppImage.md5
+
+## Keeping downloads ##
+
+When releasing a great number of similar AppImages, all starting from the same
+sources, as in the case of `batch` builds, keeping the downloads between
+single builds will allow a great deal of bandwith saving and, in general,
+optimize the release process.
+
+This is however a very different approach than when building a single version
+for your own purposes: you just need the built AppImage, and you don't care
+about the sources once the build process is finished.
+
+This is reflected in the behaviour of the two verbs of `loaih`, where:
+
+* the `batch` verb will retain all the downloaded files;
+* the `build` verb instead will remove the download folder as soon as it is
+  finished building your version.
+
+If you want to keep your downloads when manually building your AppImage, you
+can pass the option `--keep-downloads` (or `-k` in short) to preserve the
+sources once your AppImage has been built: this is especially useful if you
+want two slightly different versions of the same LibreOffice version as
+AppImage (for example, if you want a version with the help pages and one
+without).
+
+If you want to customise the position inside your filesystem of the download
+folder, you can also use the option `--download-path` (in short `-d`). This is
+honored in any case, even if you don't want to keep your downloads after the
+build.
+
+---
+[Home](Home.md) &mdash; [Prerequisites](Prerequisites.md) &mdash; [Installation](Installation.md) &mdash; [Usage - versions](Version.md) &mdash; [Usage - manual build](Build.md) &mdash; [Usage - batch build](Batch.md)

Home.md

@@ -8,6 +8,7 @@
 
 * [Prerequisites](Prerequisites.md)
 * [Installation](Install.md)
+* [Core concepts](Concepts.md)
 * [Usage - versions](Version.md)
 * [Usage - manual build](Build.md)
 * [Usage - batch build](Batch.md)

Install.md

@@ -8,25 +8,21 @@ You can build `loaih` from the sources in [this same
 site](https://git.libreitalia.org/libreitalia/loaih/).
 
 1. Clone the repository:
-```
+
-git clone https://git.libreitalia.org/libreitalia/loaih.git
+        git clone https://git.libreitalia.org/libreitalia/loaih.git
-```
 
 2. Enter the directory with the sources:
-```
+
-cd loaih
+        cd loaih
-```
 
 3. Build sources and distribution files:
-```
+
-python3 setup.py bdist
+        python3 setup.py bdist
-```
 
 4. If you have permissions (e.g. with `sudo`), you can install `loaih`
 system-wide:
-```
+
-sudo python3 setup.py install
+        sudo python3 setup.py install
-```
 
 ## From Releases ##
 
@@ -38,14 +34,12 @@ section.
    [Release](https://git.libreitalia.org/libreitalia/loaih/releases) page and
 download the relative `.whl` file (e.g. `loaih-1.3.3-py3-none-any.whl`);
 2. Ensure you have the `wheel` package installed in your system:
-```
+
-pip install wheel
+        pip install wheel
-```
 
 3. Use `pip` to install the wheel you downloaded:
-```
+
-pip install /path/to/loaih-1.3.3-py3-none-any.whl
+        pip install /path/to/loaih-1.3.3-py3-none-any.whl
-```
 
 ## From PyPI ##
 
@@ -58,7 +52,6 @@ Upgrading to new versions of `loaih` is easier with `pip`, also:
 
     pip install --upgrade loaih
 
-
 ## Test that `loaih` works ##
 
 Just execute `loaih` from the command line with any further options:
@@ -66,4 +59,6 @@ Just execute `loaih` from the command line with any further options:
     loaih
 
 ---
-[Home](Home.md) — [Prerequisites](Prerequisites.md) — [Usage - versions](Version.md) — [Usage - manual build](Build.md) — [Usage - batch build](Batch.md)
+[Home](Home.md) — [Prerequisites](Prerequisites.md) —
+[Core concepts](Concepts.md) — [Usage - versions](Version.md) —
+[Usage - manual build](Build.md) — [Usage - batch build](Batch.md)

Prerequisites.md

@@ -17,4 +17,6 @@ installed on your machine:
   official websites.
 
 ---
-[Home](Home.md) — [Installation](Install.md) — [Usage - versions](Version.md) — [Usage - manual build](Build.md) — [Usage - batch build](Batch.md)
+[Home](Home.md) — [Installation](Install.md) —
+[Core concepts](Concepts.md) — [Usage - versions](Version.md) —
+[Usage - manual build](Build.md) — [Usage batch build](Batch.md)

Version.md

@@ -1,23 +1,26 @@
 # Usage - versions #
 
-`loaih` can be used to find out information about a specific LibreOffice version; the script parses the [official LibreOffice download page](https://www.libreoffice.org/download/download-libreoffice/) and, in specific cases like daily builds, infers their availability from other known repositories.
+`loaih` can be used to find out information about a specific LibreOffice
+version; the script parses the [official LibreOffice download
+page](https://www.libreoffice.org/download/download-libreoffice/) and, in
+specific cases like daily builds, infers their availability from other known
+repositories.
 
 `loaih getversion` can be used as:
 
     loaih getversion 5.4
 
 to receive the following information:
-```
+
-query: 5.4
+    query: 5.4
-version: 5.4.7.2
+    version: 5.4.7.2
-x86: https://downloadarchive.documentfoundation.org/libreoffice/old/5.4.7.2/deb/x86/
+    x86: https://downloadarchive.documentfoundation.org/libreoffice/old/5.4.7.2/deb/x86/
-x86_64: https://downloadarchive.documentfoundation.org/libreoffice/old/5.4.7.2/deb/x86_64/
+    x86_64: https://downloadarchive.documentfoundation.org/libreoffice/old/5.4.7.2/deb/x86_64/
-```
 
 The *query* line would report each argument for the `getversion` verb (see
-below in *Multiple queries*); the *version* is the full version of
+below in *Multiple queries*); the *version* is the full version of LibreOffice
-LibreOffice matching the query; the *x86* and *x86_64* would provide URLs to
+matching the query; the *x86* and *x86_64* would provide URLs to download all
-download all the needed archives to build the AppImage.
+the needed archives to build the AppImage.
 
 ## Textual queries ##
 
@@ -36,7 +39,6 @@ today, and the daily build for yesterday;
   indicated date (in the format 4-digits year, 2-digits month, 2-digits day
 number); for a working example, 20231231 for the December 31st, 2023.
 
-
 ## Fallback to current for missing daily versions ##
 
 If the daily upstream version has not been built today (e.g. likely between
@@ -66,6 +68,7 @@ a JSON output:
 
     loaih getversion fresh -j
 
-
 ---
-[Home](Home.md) — [Prerequisites](Prerequisites.md) — [Installation](Install.md) — [Usage - manual build](Build.md) — [Usage - batch build](Batch.md)
+[Home](Home.md) — [Prerequisites](Prerequisites.md) —
+[Installation](Install.md) — [Core concepts](Concepts.md) —
+[Usage - manual build](Build.md) — [Usage - batch build](Batch.md)