From 317f8bab1bd429bdc1ea1684521163c94db19688 Mon Sep 17 00:00:00 2001 From: Emiliano Vavassori Date: Sat, 9 Mar 2024 17:31:38 +0100 Subject: [PATCH] Updated documentation with core concepts of the script. Updated all the pages to link the core concepts. --- Batch.md | 9 +-- Build.md | 4 +- Concepts.md | 171 +++++++++++++++++++++++++++++++++++++++++++++++ Home.md | 1 + Install.md | 35 +++++----- Prerequisites.md | 4 +- Version.md | 29 ++++---- 7 files changed, 214 insertions(+), 39 deletions(-) create mode 100644 Concepts.md diff --git a/Batch.md b/Batch.md index 47b2ebc..868500f 100644 --- a/Batch.md +++ b/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) diff --git a/Build.md b/Build.md index dda7aca..928ec87 100644 --- a/Build.md +++ b/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) diff --git a/Concepts.md b/Concepts.md new file mode 100644 index 0000000..69e4efd --- /dev/null +++ b/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//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) — [Prerequisites](Prerequisites.md) — [Installation](Installation.md) — [Usage - versions](Version.md) — [Usage - manual build](Build.md) — [Usage - batch build](Batch.md) diff --git a/Home.md b/Home.md index 4e4e856..df2a59f 100644 --- a/Home.md +++ b/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) diff --git a/Install.md b/Install.md index e33c937..b51306e 100644 --- a/Install.md +++ b/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) diff --git a/Prerequisites.md b/Prerequisites.md index 6618a2e..cba6f7b 100644 --- a/Prerequisites.md +++ b/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) diff --git a/Version.md b/Version.md index b47a230..ea08f03 100644 --- a/Version.md +++ b/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 -version: 5.4.7.2 -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/ -``` + + query: 5.4 + version: 5.4.7.2 + 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/ The *query* line would report each argument for the `getversion` verb (see -below in *Multiple queries*); the *version* is the full version of -LibreOffice matching the query; the *x86* and *x86_64* would provide URLs to -download all the needed archives to build the AppImage. +below in *Multiple queries*); the *version* is the full version of LibreOffice +matching the query; the *x86* and *x86_64* would provide URLs to download all +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)