rbt 0.10.215 → 0.11.90

data/doc/README.gen

@@ -1,93 +1,174 @@
 [![logo](https://i.imgur.com/QAAheRP.png)](https://rubygems.org/gems/rbt)
 [![logo](http://shevy.bplaced.net/COOKBOOKS_LOGO.png)](https://rubygems.org/gems/rbt)
 
-ADD_RUBY_BADGE
-ADD_TIME_STAMP
+DEFAULT_HEADER
 
 ## RBT - The "Ruby Build Tools" Project
 
 <img src="https://i.imgur.com/PN2lOHj.png"> Welcome to the 
 <span style="color: darkgreen; font-weight: bold">Ruby Build Tools</span> -
-<b>getting work done</b>!
+<b>getting work done</b>! <b>Making compiling great again</b>. \o/
 
 The <span style="color: darkblue; font-weight:bold ">primary goal</span> for
-the **RBT project** is to allow the user to install software, first and foremost
-on **Linux systems**, and typically from **source** - in other words:
-**to simply compile the program** at hand from a **remote URL**.
-
-While the main platform is predominantly the Linux platform, whenever possible
-support for **other platforms** will be added as well; Linux is the
-**main target OS** for the rbt project, though. Most development for RBT does
-indeed take place on a Linux system currently, but ideally we could reach
-a state where we can test the RBT suite on less commonly used systems
-as well, such as **HaikuOS** or **ReactOS** to name only a few here.
-
-The main goal for the **RBT project** is **to be able to compile a program
-from source**. While this is the primary goal of the RBT project, the **full
-scope** of the **RBT project** is a wider one: the **RBT project** will also
-attempt to help as **a build toolset**, that is, as means to **help people
-manage software** on their respective computer systems in general.
-
-This definition, in principle, includes tasks done by package managers, although
-support for this within RBT itself is presently (2020, as well as in 2021)
-still fairly minimal. Don't expect RBT to become a fully fledged package
-manager right now; but perhaps this use case may be covered one day in the
-future.
-
-I have used RBT specifically to help me in my attempts to **boostrap** a
-LFS/BLFS (Linux from Scratch / Beyond Linux from Scratch) system, so
-this is an additional use case (and goal) for the RBT project as well.
-"From zero to hero" - aka to bootstrap and create a Linux system that
-can be burned on a DVD or simply put on a USB device. This is not yet
-working, but it is on the TODO list. 
+the **RBT project** is to allow a user to install software, first and
+foremost on **Linux systems**, and typically from **source** - in other
+words: **to simply compile the program** at hand from a **remote URL**.
+
+While the main platform is predominantly the <b>Linux</b> platform, whenever
+possible support for **other platforms** will be added as well; Linux is
+the **main target OS** for the rbt project, though. Most development for
+RBT does indeed take place on a Linux system currently. Ideally we
+could reach a state where we can test the RBT suite on less commonly
+used systems as well, such as **HaikuOS** or **ReactOS** to name
+only a few here. And, of course, the more popular ones such as OSX
+or Microsoft's Windows suite.
+
+<b>So what is the main goal for the <span style="color: darkgreen">
+RBT project?</span></b>
+
+The main goal for the **RBT project** is **to be able to compile a
+program from source**, using a remote URL to some tarball, such as
+the .tar.xz file for <b>evince</b> here →
+https://download.gnome.org/sources/evince/42/evince-42.3.tar.xz.
+
+While this is the primary goal of the RBT project, the **full
+scope** of the **RBT project** is a significantly wider one:
+the **RBT project** will also attempt to help as **a build
+toolset**, that is, as means to **help people manage
+software** on their respective computer systems in
+general. This may even extend towards other programming
+languages, be it python, java, C/C++, shell scripts - you 
+name it.
+
+Another "higher" meta-goal that follows this vision is to
+integrate tasks that are typicall done by a package manager.
+Support for this within RBT itself is presently (2022)
+still fairly minimal. Do not expect RBT to become a fully
+fledged package manager right now; but, perhaps this use
+case may be covered one day in the future. Until then 
+singular aspects found in different package managers
+may be included into the RBT suite as well.
+
+Yet another goal for the <b>RBT project</b> is to provide
+all the raw data used for managing <b>all</b> programs
+on a <b>Linux Distribution</b> or another Operating
+system. What you do with this data is up to you; I
+simply wanted to have this all available within a
+<b>single</b> project as-is.
+
+The data is primarily stored in various individual cookbook
+.yml files. These .yml files, though, can be turned
+into a SQL dataset. Since as of <b>August 2022</b> it
+is recommended to use a SQL database - but if you are
+fine using .yml files then you can do so. See elsewhere
+in this document more information pertaining to this.
+(Note that the SQL-based approach is not yet sufficiently
+sophisticated; for the time being I will still default to
+.yml files and it may be easier for you to ignore the
+SQL situation for now, and just use the yaml files. In
+the future, though, I expect that we can handle the
+full dataset offered by RBT via SQL.)
+
+As a brief teaser, though, and short explanation to 
+this, consider the program called <b>htop</b> which is stored
+in the file called <b>htop.yml</b>. <b>anjuta</b> is stored
+in <b>anjuta.yml</b> and so on and so forth. If the
+program name contains any '-' character then these
+are ignored, so the program 
+<b>https://download.gnome.org/sources/gnome-commander/1.14/gnome-commander-1.14.3.tar.xz</b>
+would be stored in the .yml file <b>gnomecommander.yml</b>.
+
+This is a rather simple convention - the name of the
+program will become the name of the yaml file in
+question. These so-called individual "cookbooks"
+(aka "to cook/compile a program from source)
+can then be used by other projects. Note that this
+term is a bit similar to the old linux distribution
+called sorcery (https://sourcemage.org/Sorcery).
+
+<b>Is RBT actually useful?</b>
+
+Well - I have used RBT specifically to help me in my attempts to
+**boostrap** a LFS/BLFS (Linux from Scratch / Beyond Linux from
+Scratch) system, so this is an additional use case (and goal) for
+the RBT project as well. So I think that the RBT suite does
+have some use here or there. For this I would coin the phrase
+<b>"from zero to hero"</b> - which means to <b>bootstrap and create
+a Linux system</b> that can be burned on a DVD or simply put on
+a USB device. This is not yet working flawlessly, but it is
+on the TODO list as well: to support LFS/BLFS builds from scratch
+(aka <b>from zero</b>). 
 
 Additionally, the **RBT** project may aid in the process of <b>autogenerating
-files and code</b> related to installing and compiling, such as **generating
-standalone shell scripts** or **valid archive formats**, such as .rpm or .deb.
-For example, one part of **RBT** can be used to autogenerate completion files
-for bash and zsh; I use this to compile programs, such as "ry autom<TAB>"
-to become the same as "ry automake". Another script, part of RBT, can modify
-**Makefile**s and change the prefix in that file. These are examples for
-such "toolkit" scripts.
-
-In some ways, if you look at it from a wider perspective, **RBT** attempts
-to be the **swiss army knife for compilation/installation** of software 
-projects. The focus here is on **hands-on use** - it is a toolset project
-and has to offer code/functionality that helps solve certain
-computer-related tasks.
-
-Even if you do not intend to install or compile anything through RBT, many
-different programs are registered in this project, which may be of help in
-some other ways, such as if you wish to determine which particular binary
-on a given Linux system belongs to which particular program, or if you
-intend to implement a package manager yourself. (The dataset for the
+files and code</b> related to installing and compiling in general, such
+as **generating standalone shell scripts** or **valid archive formats**,
+such as .rpm or .deb.
+
+For example, one part of **RBT** can be used to <b>autogenerate completion files
+for bash and zsh</b>; I use this to more easily compile programs, such as
+by typing "ry autom<TAB>", to become the very same as "ry automake". This
+thus saves me a few keystrokes on the keyboard.
+
+Another script, part of RBT, can modify **Makefile**s and change the
+prefix in that file, without me having to remember the awkward syntax
+<b>make</b> uses when trying to override the default prefix in
+use. These are examples for such "toolkit" scripts, so the overall
+goal for the RBT suite is to help in regards to such <b>use cases</b>.
+
+In some ways, if you look at the RBT suite from a wider perspective, **RBT**
+attempts to be the **swiss army knife for compilation/installation** of
+software projects. The focus here is on **hands-on use** - it is a
+toolset project and has to offer code/functionality that helps
+solve certain computer-related tasks.
+
+<b>Q: But the RBT suite is so gigantic! I will never need all of
+it.</b>
+
+That's right - you may only need a small subset of the RBT suite. The
+RBT suite attempts to cover different use cases and needs, so it is
+highly likely that not every user needs to use all of the RBT 
+suite.
+
+However had, even if you do not intend to install or compile anything
+through RBT, many different programs are registered in this project,
+which may be of (indirect) help in some other ways, such as if you
+wish to <b>determine which particular binary on a given Linux system
+belongs to which particular application</b>, or if you intend to
+implement a package manager on your own. (The dataset for the
 standalone programs is available under the namespace **RBT::Cookbooks**.
 For a list of all registered programs, you can simply query
-**RBT.available_programs?**).
-
-Another part of the project deals with statistics, although support for
-this is quite minimalistic right now. One script reports some 
-statistics, such as how many of the registered projects depend on
-cmake, or meson, and so forth. This part will be slowly extended over
-the coming years, but it is not the primary use case - just something
-that I found to be interesting to know. (So many projects still depend
-on GNU autoconfigure/configure, for example, with cmake coming second,
-and meson/ninja coming third.) 
-
-The <b>primary core functionality</b> of the RBT project, however had,
-lies in **compiling programs from source**, as this is what I use RBT
-for on an almost daily basis. It also was the original reason why the
-RBT project was started many ears ago.
+the toplevel-method **RBT.available_programs?**).
+
+Related to this question of "How do users benefit from the RBT
+suite", one part of the RBT suite deals with <b>statistics</b>.
+Support for this is somewhat minimalistic right now. One script reports
+some statistics, such as <b>how many of the registered projects depend on
+cmake, or meson, and so forth</b>. This part will be slowly extended
+over the coming years, but it is not the primary use case for the RBT 
+suite - just something that I found to be interesting to know,
+how many different projects out there depend on which compilation
+strategy. (So many projects still depend on GNU autoconfigure/configure,
+for example, with cmake coming second, and meson/ninja coming third.
+I found that monitoring the rise of meson/ninja to be quite 
+interesting.)
+
+The <b>primary core functionality</b> of the RBT project, however
+had, lies in **compiling programs from source**, as this is what I
+use RBT for on an almost daily basis. It also was the original
+reason why the RBT project was started many ears ago.
 
 ## Installing the rbt gem itself
 
-The canonical way to install the **rbt** gem is:
+This subsection addresses the possible user question
+<b>How to install the rbt gem?</b>.
+
+The <b>canonical</b> way to install the **rbt** gem is via:
 
     gem install rbt
 
-However had, I recommend the **--user-install** option; this makes it easier
-to use the **bin/** scripts that are part of this gem, as they will reside
-in your home directory, at **bin/** there:
+However had, I recommend the **--user-install** option; this makes it
+easier to use the **bin/** scripts that are part of this gem, as
+they will reside in your home directory, at **bin/** there:
 
     gem install rbt --user-install
 
@@ -108,33 +189,533 @@ in my opinion - you don't have to guess where the executables
 will reside; they are just in the home directory, somewhere there.
 And you can move them from there to any other location anyway,
 or use **symlinks** and/or **aliases** via your shell to setup
-the system how you want it to be. Or, use the ruby code directly - 
-after all you can create your own executables, since that is
-precisely what all gems do anyway in their corresponding
+the system how <b>you</b> want it to be. Or, use the ruby code
+directly - after all you can create your own executables, since
+that is precisely what all gems do anyway in their corresponding
 **bin/** subdirectory.
 
-Since gems are also **downloaded locally**, and then available as a
-.gem file, other users can easily install these gems into their home
-directory as well, without depending on a global installation. This
-may be especially useful in environments where you are restricted,
-such as at a **campus/university environment**.
+Since gems are also **downloaded locally**, and then available as
+a .gem file, other users can easily install these gems into their
+home directory as well, without depending on a global installation.
+This may be especially useful in environments where you are
+restricted, such as at a **campus/university environment**.
+
+On windows, if you plan to upgrade the rbt gem, I recommend
+to first uninstall all old rbt gems. While this is, strictly
+speaking, not really necessary, I found that it may work
+better if old gems are removed - at the least on windows.
+
+## How I use the RBT project
+
+This subsection was added in <b>January of 2023</b>. Before
+that time, the content was mostly written down already in
+this document, but it was spread over different sub-topics.
+I decided that it was time to give a more thorough overview
+of the project, from a "<b>my point of view</b>". That way,
+hopefully, other users can learn from how I approach 
+problems that the RBT project tries to solve for you.
+
+So, this subsection shall try to helpfully explain **how I
+use the RBT project most of the time**, as that may give
+some indication how the RBT project could be used by
+other people as well.
+
+We have to declare a few things upfront, though.
+
+I use **linux** as my main operating system, so this is also
+the primary operating system for the scripts offered by
+the rbt gem. While I also try to support windows, windows
+at this point in time is a second-class citizen. At a later
+time this may change, but as of 2023 this is still the
+case so.
+
+On Linux, I often found to have a need to quickly compile
+some software, such as when a new release of a given project
+occurs. For example, say that there is a new **php** source
+archive released.
+
+So, what do I do in this case?
+
+Well, first, I have to update the local version of <b>php.yml</b>,
+with the new URL to the latest tarball of PHP. This is also
+stored in that **.yml** file, under the <b>url1</b> entry.
+
+How do I then update the content of said .yml file?
+
+I usually start by navigating to the <b>php/</b> subdirectory
+first, of the directory where I keep all source directories
+(which is **/home/x/src/** on my home setup). Strictly
+speaking this cd-operation (change directory) is not necessary;
+the RBT scripts will work fine from other directories too.
+But I found it is easier if I first go to the directory
+where I keep the corresponding source archive. In the
+context of this paragraph, php could then be found
+at <b>/home/x/src/php/</b>. I follow the "one directory
+per program" rule. It is a simple approach.
+
+Now that I have (hopefully) managed to navigate to the
+source directory at hand (<b>/home/x/src/php/</b>), I
+can then run the following command on the commandline:
+
+    incrementversion
+    incr # or just this alias to the above ^^^ instead
+
+This command will actually invoke class
+**RBT::Cookbooks::IncrementProgramVersion** which will
+try to find a new upstream release tarball, using **curl**
+or **wget*+ to check if such a remote tarball exists. 
+Note that I use many aliases on my home system; all
+aliases are kept in the gem called <b>rcfiles</b>.
+
+Now, if the remote file specified at url1 in the
+file called php.yml exists then it will be 
+<b>downloaded</b> the moment I try to compile
+the program at hand (in this case php).
+
+So I can simply type this:
+
+    rbt php
+
+And if things go alright from that point forward (which they
+tend to do, at the least for php and many other programs
+that can be compiled), then php will have been compiled
+and installed afterwards into the /usr/ prefix, or the
+AppDir prefix on my home system, which would be
+**/home/Programs/Php/8.0.3/**, for instance. That's
+it for the most part: I just compiled a program from
+source.
+
+So, as you can see, this is actually quite simple to use,
+in principle. I don't want to make this really more complicated
+than that. In fact: I even simplify the above, by using
+the alias "<b>trad</b>", which will first update, by incrementing
+the version (of php), download the actual source archive, 
+extract the source archive and then compile php into the
+/usr/ prefix, which is the "traditional" prefix (hence the
+abbrevation "trad").
+
+From a historic point of view, it was somewhat too tedious for
+me to keep on compiling things manually, via the old
+"./configure; make; make install" route, so it made sense
+to me to create some scripts in ruby that could simplify
+this for me. Back in 2004 when I was using Linux, I
+discovered **GoboLinux**,  which is a great distribution, with
+an excellent philosophy. I did not understand the shell scripts
+they used, though, so I tried to write (and re-create) the
+logic behind it in <b>ruby</b>.
+
+This goal of making RBT compatible with GoboLinux still exists
+as of today: the RBT project must work on GoboLinux, out of
+the box. I have not tested this in quite some time, though ...
+need to do so eventually.
+
+But the RBT project has other goals as well, aside from this:
+more common goals. As a project, RBT tries to **remain flexible**,
+so that people can repurpose this project to their own use
+cases.
+
+I really want to be able to use the project on linux, on windows,
+on <b>mac OS X</b>, on the various BSDs, ideally also on haiku and
+so forth one day. <b>One project to rule them all!</b> \o/
+
+This means that **RBT** has to remain flexible, as much as that
+is possible. It has to be adaptable to different operating
+systems on the fly; or at the least easily.
+
+Additionally, **I want to use different prefixes**. Most
+existing package managers make it hard to install applications
+into a particular prefix, and have things work from there.
+
+For example, debian does not allow you to use a layout
+similar to how GoboLinux works by default. I don't know
+why they do not allow it - probably because nobody wrote
+the code for dpkg/apt to handle different prefixes.
+
+From that original goal that was historically the **bootstrap phase**
+of the RBT project, I added more and more code over time. I did want
+to provide better error messages as well, and hints how to resolve
+something whenever a problem happens - way before **StackOverflow**
+existed.
+
+Most compile-related errors are quite useless and cryptic to
+newcomers. They don't understand the problem domain. So RBT also
+tries to help users in that regard. Errors may be collected, and
+then something useful is displayed on the commandline - at the least
+that is one goal for the RBT project. This may not always be very
+useful, but at the least that is one goal for the RBT
+project. The code for this is not ideal; I am slowly
+rewriting it since March 2020. (Actually, I think I may have
+to rewrite the whole project past 2021 one day; but I delay this
+for now. I want to be better prepared before I rewrite it.)
+
+I can compile most of the programs that are listed in RBT
+via the following commands:
+
+    rbt NAME
+    rbt php
+    rbt python
+
+and so forth, so this is really convenient. I don't depend on
+another package manager that upstream developers control.
+
+In **September 2021** I decided to cut back on time investment
+for the RBT project. This is mostly because other projects
+take away more of my time. I won't abandon rbt, but it should
+be pointed out that I am mostly only doing maintenance work,
+fixing some problems here and there, polishing this or that -
+but it is a very beta-ish project, and I can not make any
+guarantee that the project will ever leave its beta-ish 
+roots.
+
+
+## How do I use the RBT project personally
+
+How do I use the **rbt project** primarily, on my **Linux** systems?
+
+What follows next is, more or less, a description of generic use
+cases that I may face on a daily basis.
+
+When I compile a (new) program via **RBT**, such as by issuing "compile
+htop" or "rbt htop" or "ry htop" (I make use of aliases a lot), then
+the **RBT-scripts** will (try to) compile the program **htop** for me,
+as specified by the corresponding "htop.yml" file, which is part of
+the RBT project - within the **Cookbooks** namespace. Hence, within
+**RBT::Cookbooks**.
+
+If I need to make a change to the compilation process, such as by
+using a different default **prefix**, then I simply edit the
+**htop.yml** file, change, add or remove the corresponding entry,
+and things will (should) work past this point - but I can also
+override the settings from the commandline, so I have all the
+flexibility required available.
+
+This, in turn, means that I control most of what I compile via
+.yml files, first and foremost - a text file. Other package managers
+do something similar if you look at them. Arch, for instance,
+uses PKG_BUILD or some file like that; gentoo uses ebuilds,
+debian also uses some designated files, and so forth.
+
+The "default settings" that I may use for these programs go into 
+a specific .yml file, whereas the **commandline switches** allow
+me to specifically override or cherry-pick other settings, based
+on the machine that I am working with. For example, on **GoboLinux**
+the AppDir prefix makes a lot of sense. On **slackware** on the
+other hand I may decide to just use **/usr** as option given
+to **--prefix=**.
+
+On **traditional** linux distributions, **/usr** as prefix is
+not the only possibility of course. Another popular way is to
+compile into the **user's home directory**. A commandline switch
+exists for the latter, for the RBT project, called **--home-directory**.
+This is equivalent to whatever the user's home directory ought to
+be, such as **/home/debug/** or **/home/joe/**. (I typically have
+a user account called **debug** on my systems, which is mostly
+concerned with debugging something on the target computer.)
+
+So, --home-directory for the user joe would be equivalent to
+**--prefix=/home/joe/**.
+
+This is useful in the sense that, ideally, I can get away with only
+passing the name of the program that is to be compiled, without
+needing to change anything. It allows me to be lazy - and
+just get things to "work", when they are compiled (if the compilation
+process itself will work).
+
+
+
+
+
+
+## Most recent release series (some kind of "changelog" entry)
+
+The most recent release series, which is <b>version 0.11.x</b>,
+has been (mostly) rewritten from scratch for at the least the
+following <b>five reasons</b>:
+
+- I needed to add support to compile from source, via
+a sqlite-database. Hence class RBT::CompileViaSQLDatabase
+has been added. This was actually the primary reason for
+the rewrite: I had to re-arrange the internal logic
+anyway, so I thought that I should start from a
+sqlite-database this time. This is also easier to use
+on windows - one database to rule them all. The trade-off
+is that you have to install sqlite on windows but this
+is quite trivial; see the download link for sqlite
+on windows (the .exe file).
+
+The location of the database should be a path such as
+<b>/home/Temp/rbt/database/registered_programs.db</b>
+or <b>/tmp/rbt/database/registered_programs.db</b>
 
-## Conventions and Aliases used for the purpose of this document
+- I wanted better GUI support, in particular via libui, so that
+this all works fine on windows as well. I also wanted to add
+more screenshots.
 
-Commands that you can typically use on the commandline are shown
-with an indent of four ' ' space character on the left hand side.
+- I needed better support on windows too, so the rewrite
+had this as one goal.
+
+- Clean-up in general, including removal of old, unmaintained
+software.
+
+- Extend all actions. That is, note down everything in the
+RBT suite that can be done via such actions.
+
+## Conventions and Aliases used for the purpose of this document as well as the RBT project in general
+
+Commands that you can typically use on the commandline, such as
+via the <b>bash</b> shell on Linux, are shown with an indent
+of four ' ' space character on the left hand side.
 
 Example:
 
     rbt htop # ← This would try to compile the program called htop.
 
-Here, rbt refers to bin/rbt, as part of the RBT project.
+Here, <b>rbt</b> refers to bin/rbt, as part of the RBT project.
 
 Note that on my home system I have aliased **ry** to **rbt**,
 so that is why all the examples below this paragraph will actually
 use **ry**; mostly because it is more convenient for me to use 
-**ry** rather than **rbt**. 
-    
+**ry** rather than **rbt**. Either way, some of the old
+documentation may use either <b>ry</b> or <b>rbt</b>, both
+of which is equivalent.
+
+By default the programs that are part of RBT will make use of
+colours. You can disable this in general via the commandline
+flag <b>--disable-colours</b>.
+
+The class name will typically be shown on the commandline;
+primarily to let the user know which class is handling a
+specific step of the installation/compiling process.
+
+The class name will typically be shown via :: such as
+<b>RBT::Installer</b>.
+
+If an external class is called then the arrow symbol
+→ will be used.
+
+The following picture shows this:
+
+<img src="https://i.imgur.com/j54KXl1.png" style="margin:1em">
+
+## Copying the expanded directory
+
+It may be helpful if you simply copy the expanded cookbooks
+directory after you installed the gem.
+
+This can be done via:
+
+    rbt --copy-expanded-directory
+    # or
+    # installer --copy-expanded-directory
+
+You can also generate the expanded dataset anew, or use
+the SQLite wrapper, but in general using the above 
+option is faster and easier for most (new) users.
+
+Once that has been done you should be able to compile
+programs from source.
+
+Keep in mind that currently you have to maintain the
+dataset by yourself, or default to the changed dataset
+every now and then. The good news is that the .yml
+files are rarely changing in format, so you can
+easily "plug in" or remove new/old .yml files here.
+
+## Background explanation: FAQ entry "Why a new project rather than extending existing code?"
+
+This is a valid question - why not <b>contribute to an existing project</b>
+rather than create a new project from scratch? There are a few
+problems with the existing projects out there, though.
+
+The scope of these projects is fairly often limited. For example:
+mac **homebrew** is a package manager, but other than that it isn't
+doing that much; and it does not work that well on linux or windows -
+I tried it in <b>2019</b> on linux and it did not work for me. Perhaps
+things improved since then, but since I felt that linux is a
+second-class citizen in homebrew, I did not invest more time
+into the issues I had faced with homebrew back then.
+
+Another reason is that I do want to have a project that works as
+well as ruby does on any given operating system, as long as ruby
+is supported. I want to use it on windows, on haiku, on the BSDs,
+solaris, for cross-compilation targets and so forth.
+
+But there are **API-differences** as well and the way how these systems
+are used. For example, the classical **package managers** on linux <b>do
+not allow you to easily use another prefix</b>.
+
+Most of them, at the least on linux, assume that **/usr/** is the
+only prefix that is to be used (or /usr/cellar or something like
+this). I do not like this restriction - I want more flexibility,
+and complete control over the prefix in use <b>at all times</b>. I
+want to be able to use a hybrid system too - partially using
+/usr/ as prefix, and partially using **versioned AppDirs**
+such as into my home directory.
+
+With most package managers I would be forced into using just
+/usr/ as the global prefix - no alternatives to this approach.
+
+I absolutely dislike this restriction. Some of them even split
+it into /usr/ and /usr/local - for example, debian has python,
+perl and ruby packages under <b>/usr/local/</b>. What is this
+madness? Why do I need to bother with it? How can I easily
+change it? Why is there no consistency in this? The "explanation"
+they try to give is a joke. In general the whole FHS is a mess -
+and a joke. It makes no sense.
+
+Debian in general is a total mess. Let me show you a single
+entry as example demonstrating why, as taken from the
+following webpage:
+
+https://wiki.debian.org/PerlFAQ
+
+So they ask the question:
+
+<b>What if you want to install an updated version of perl
+in /usr/local for experimental work but keep the
+Debian/Release version in usr?</b>
+
+And they answer it via:
+
+"This setup may not work out well with the Debian Perl
+package for Sarge since it has its own ideas about
+Perl stuff in <b>/usr/local/</b>."
+
+I mean, seriously? Perl is so outdated that they don't
+even know how to install packages? So /usr/lib/
+becomes an eternal struggle with /usr/local/lib/?
+What the actual ... 
+
+As far as I am aware, there is no trivial way to change 
+any of that once you are using a distribution. They
+expect things to be a certain way.
+
+This above listing of reasons can be extended really, and
+you can find numerous more issues - but ultimately it was
+less of an issue here to create a new project that has these 
+different goals in mind, rather than try to retrofit
+existing code bases out there towards my own use cases.
+
+I also preferred to use ruby rather than perl or python,
+so the number of available package managers was even
+more limited here.
+
+## Package Users
+
+The concept behind <b>package users</b> is fairly simple to
+understand:
+
+<b>Every package belongs to a certain user.</b>
+
+So, for instance, the program called <b>evince</b> (a 
+.pdf reader) would belong to a user called Evince, or
+perhaps with some prefix, such as UserEvince, if we
+have to avoid name collision.
+
+This way you can immediately identify which file
+on your computer system belongs to which package,
+if the underlying operating system supports this -
+which linux does.
+
+By default this setting is <b>turned off</b> though. I
+am not entirely certain whether RBT should support
+this - but it is here mentioned in this document
+to demonstrate that some thought has been given
+about this feature/functionality. I first read it
+when someone wanted to do a BLFS build (Beyond
+Linux From Scratch).
+
+## PDF Generation for users of the RBT suite
+
+If you want to generate PDF files which you can print or distribute
+anyway you see fit, have a look at the PdfGenerator.rb script.
+Note though, right now the output is a bit ugly... I will look into
+this again at a later point in time.
+
+The above is fairly old content - generation of pdf-files 
+may not work properly anymore. It is not so important, though,
+as the RBT suite's primary objective is to support compilation
+of programs, from source.
+
+## Determining the version of the RBT suite
+
+You can issue the following from the commandline to determine
+the version of the RBT suite:
+
+    rbt --version?
+
+The version is kept in the file <b>rbt/version/version.rb</b>.
+
+You can also query it from within ruby via:
+
+    require 'rbt'
+    RBT.version?
+
+## Viewing all packages
+
+To view a list of all packages on your system, do this:
+
+    rbt php packages?
+    rbt python packages?
+
+The result would be something like this:
+
+    ["/Depot/Packages/Python-2.5.tar.bz2"]
+
+## Simulate running a program of the RBT suite
+
+This option - also known as <b>no harm</b> Option, allows you
+to run the RBT Scripts in a simulation mode.
+
+This works like so:
+
+    rbt php simulate
+    rbt php --simulate
+
+## class IncrementProgramVersion
+
+This class can be used to automatically try to find
+whether any given program was upgraded.
+
+This assumes that programs are numbered in a
+semantic version scheme.
+  
+## Extended cookbooks
+
+You can require the <b>cookbooks</b> submodule in an
+extended variant, such as via the following instruction:
+
+    require 'rbt/module_programs'
+
+The functionality is assumed to <b>extend</b> the
+RBT namespace directly. In the past the file was
+simply called <b>extended.rb</b>, but the name
+<b>module_programs</b> is more logical, so it was
+renamed to <b>module_programs.rb</b> some years
+ago.
+
+This is also called "modular apps". The idea is that
+the dataset can be queried from the toplevel namespace
+<b>RBT</b> directly.
+
+After having done the above require statement, you can
+then tap into this functionality allowing you to
+directly call the dataset via the individual name, such
+as by issuing:
+
+    RBT.ruby
+    RBT.htop
+    RBT.python
+
+Now you can see the data for ruby, htop, python and so forth.
+
+Personally I do not recommend that users of the rbt gem should
+use this functionality - it was mostly added to offer that
+functionality syntax-wise, so that you can just type the RBT
+namespace, and then the program name. Either way, you decide whether
+you want to use it or not; I only wanted to make sure that this
+functionality is possible for RBT as well.
+
 ## The history and philosophy of the RBT Project - philosophic considerations
 
 This subsection in this README-document (autogenerated as **README.md**)
@@ -145,30 +726,39 @@ conventions and the terminology used by **RBT**.
 
 The **RBT project** in itself started out initially as means to
 <b>re-create the shell scripts' logic</b>, and functionality,
-used in <b>GoboLinux</b>, several years ago.
-
+used in <b>GoboLinux</b>, several years ago. I do not recall the
+exact starting year, but I believe it must have been in the year
+<b>2005</b> or so, give or take; perhaps 2006 at the latest.
+    
 I was already using **Ruby** at that time and I did not understand the
-shell scripts that were used in **GoboLinux**. Shell scripts can be quite
-confusing to read; parameters do typically not go into a **regular 
-function** via a function/method signature, but instead are accessed as
-special **semi-global variables** such as **$1** or **$2** within the
-function body. I find this **extremely unintuitive**, confusing - and
-quite ugly. I would not mind it so much if it could be used in addition
-to regular syntax, but if you look at most shell scripts out there
-available on the www, you will see how unbelievably ugly they are. The
-more code you write that way, the harder it becomes to untangle that
-spaghetti mess. To be fair: **GoboLinux** had one of the prettiest
-shell script-based code out there. It is actually quite readable
-compared to a lot of other shell code in the www.
-
-So the seemingly logical thing to do here for me was to re-create the
-functionality that GoboLinux offered in **Ruby**, as I find well-written
-ruby code **much** simpler and easier to read and understand than shell
-scripts. Of course people can write ugly and confusing code in ruby as
-well; and there is a lot of somewhat decently written shell code spread
-over the www, too. But by and large, I found it to be true that well-written
+shell scripts that were used in **GoboLinux**.
+
+Shell scripts can be quite confusing and difficult to read; parameters
+do typically <b>not</b> go into a **regular function** via a function/method
+signature, but instead are accessed as special **semi-global variables**
+such as **$1** or **$2** within the function body. I find this
+**extremely unintuitive**, confusing - and quite ugly. I would not mind
+it so much if it could be used in addition to regular syntax, but if you
+look at most shell scripts out there available on the world wide web, you
+will see how unbelievably ugly these are. It's spaghetti code with tons of
+syntax noise.
+
+The more code you write that way in this way, the harder it becomes to
+untangle that spaghetti mess. To be fair: **GoboLinux** had one of the
+prettiest shell script-based code out there, so I have to give the
+**GoboLinux** authors credit. It is actually quite readable compared
+to a lot of other shell code in the www. But, even then, I still think
+that well-written ruby code is so much prettier and easier to read. (Of
+course you can write horrible ruby code too, but I am not referring
+to such cases. By and large, I found it to be true that well-written
 ruby code tends to be a lot better to read/maintain/change than
-well-written shell code, for the **equivalent functionality**.
+well-written shell code, for the **equivalent functionality**.)
+
+So, the seemingly logical thing to do here for me was to <b>re-create the
+functionality that GoboLinux offered</b>, in **Ruby**, as I find well-written
+ruby code **much** simpler and easier to read and understand than shell
+scripts - at the least the functionality that these shell scripts try to
+offer.
 
 At the least for me personally, I have a hard time trying to understand
 what shell scripts do in general, even though the shell scripts used in
@@ -252,7 +842,8 @@ project, primarily to make syncing the code easier. The **RBT::Cookbooks**
 namespace handles the source files' logic, whereas RBT itself handles
 how to interprete this information, in particular through the main
 class to use for compiling something, which is the class
-**RBT::Compile**.
+**RBT::Installer**. (The old class RBT::Compile has been deprecated
+in <b>2022</b>.)
 
 When you have a look at the RBT project, including the documentation
 on the homepage of the RBT gem, you may notice that the documentation
@@ -274,7 +865,7 @@ route.
 • The **second reason**, and more important one, is that I want to treat
 users as intelligent people, so I will try to explain to them how 
 some of the RBT internals work. Naturally not all of RBT will be
-explained that way, but more important parts, such as e. g. **RBT::Compile**
+explained that way, but more important parts, such as e. g. **RBT::Installer**
 in particular, will have several entries that will explain what is
 done, and why. My ideal aim would be to actually write a specification
 as a text, and then let ruby simply parse and evaluate that text -
@@ -387,265 +978,60 @@ of information, which could lead to confusion and frustration,
 so this subsection tries to explain at the least a few things
 in addition to other subsections here that do so as well, as-is.
 
-It may help if I explain **how I use the RBT project mostly**,
-as that may give some indication how the RBT project could
-be used by other people as well:
+In January 2023 this subsection was changed; the "How I use
+the RBT project" was added as a separate subsection closer
+to the top of this page. That way new users can quickly
+read and learn how I use the RBT project.
 
-I use **linux** as my main operating system, and I often found 
-to have a need to quickly compile some software, such as when
-a new release of a given project occurs. For example, say
-that there is a new **php** source archive released.
+## @source_base_directory
 
-So, what do I do in this case? Well, first, I have to update
-the local version (stored in a **.yml** file).
+The very important instance variable **@source_base_directory**, defined
+at the toplevel **module RBT**, can be used to **denote the directory
+where archives of different programs are to be kept** (or are
+already kept).
 
-I do this by usually navigating to the php/ subdirectory first,
-of the directory where I keep all source directories
-(which is **/home/x/src/** on my home setup), and then I
-run the following command on the commandline:
+For **example**, on my home system I store the source code to many
+different programs in the directory **/home/x/src/**. That name 
+emerged mostly due to historic reasons, as the user "x" was just
+a generic name I would use for various different tasks, including
+making regular backups. (I did not want to type too much when
+doing a backup, hence why just one letter was used there.)
 
-    incrementversion
-    incr # or just this alias instead
+As other users of the **RBT** project may wish to use another
+directory rather than the one listed above, such as
+a directory like **/Files/Archives/** or **/Depot/Archive/**
+or anything like that, there are essentially **three different
+ways** how to define your own target directory for keeping
+such **source archives**:
 
-This command will invoke class **RBT::Cookbooks::IncrementProgramVersion**
-which will try to find a new upstream release tarball, using
-**curl** or **wget*+ to check if such a remote tarball exists.
+(**1**) Simply set a new target altogether, via the **toplevel-method**
+called **RBT.set_source_base_directory()**. A shorter API exists
+as well, an alias to this method, called **RBT.set_source_directory()**.
 
-If it exists it is then downloaded. I can then compile it
-by simply issuing:
+You can also use **RBT.source_directory = path**, if you would like to.
 
-    rbt php
+As **argument** to this method, simply pass in **the path to the
+directory** that you wish to use, such as **/opt/** or **/home/src/** or
+any other location that you may wish to use.
 
-And if things go alright from that point (which they tend to do, at the
-least for php and many other programs that can be compiled), then
-php will have been compiled and installed afterwards into the
-/usr/ prefix, or the AppDir prefix on my home system, which would
-be **/home/Programs/Php/8.0.3/**, for instance. That's it.
+Explicit examples for the API that was mentioned above, will be shown
+next:
 
-So you can see that this is actually quite simple to use, in 
-principle. I don't want to make this really more complicated
-than that. In fact: I even simplify the above, by using
-the alias "trad", which will first update, by incrementing
-the version, download, and then compile into /usr/, which
-is the "traditional" prefix (hence the abbrevation "trad").
+    RBT.set_source_directory('/opt')
+    RBT.set_source_base_directory('/opt')
+    RBT.source_directory = '/opt'
+    
+    # Or for the target /Depot/Archive/
 
-I was somewhat tired to compile things manually, via the old
-"./configure; make; make install" route, so it made sense
-to me to create some scripts in ruby that could simplify this for
-me.
+    RBT.set_source_directory '/Depot/Archive/'
 
-That describe **original use case** was not the sole deciding
-factor, though. I also did discover **GoboLinux** back in 2004
-or so, which is a great distribution, with an excellent
-philosophy. I did not understand the shell scripts in use,
-though, so I tried to write (and re-create) the logic through
-ruby.
-
-This goal is still existing as of today. :) The RBT project
-must work on GoboLinux, out of the box. (I have not tested
-this in quite some time, though ... need to do so eventually.)
-
-But the RBT project has other goals as well, more common goals,
-and as a whole, RBT tries to **remain flexible**.
-
-I really want to be able to use the project on linux, on windows,
-on mac OS X, on the various BSDs, ideally also on haiku and so
-forth. One project to rule them all!
-
-This means that **RBT** has to remain flexible, as much as that
-is possible. It has to be adaptable to different operating
-systems on the fly; or at the least easily.
-
-Additionally, **I want to use different prefixes**. Most
-existing package managers make it hard to install applications
-into a particular prefix, and have things work from there.
-
-For example, debian does not allow you to use a layout
-similar to how GoboLinux works by default. I don't know
-why they do not allow it - probably because nobody wrote
-the code for dpkg/apt to handle different prefixes.
-
-From that original goal that was historically the **bootstrap phase**
-of the RBT project, I added more and more code over time. I did want
-to provide better error messages as well, and hints how to resolve
-something whenever a problem happens - way before **StackOverflow**
-existed.
-
-Most compile-related errors are quite useless and cryptic to
-newcomers. They don't understand the problem domain. So RBT also
-tries to help users in that regard. Errors may be collected, and
-then something useful is displayed on the commandline - at the least
-that is one goal for the RBT project. This may not always be very
-useful, but at the least that is one goal for the RBT
-project. The code for this is not ideal; I am slowly
-rewriting it since March 2020. (Actually, I think I may have
-to rewrite the whole project past 2021 one day; but I delay this
-for now. I want to be better prepared before I rewrite it.)
-
-I can compile most of the programs that are listed in RBT
-via the following commands:
-
-    rbt NAME
-    rbt php
-    rbt python
-
-and so forth, so this is really convenient. I don't depend on
-another package manager that upstream developers control.
-
-In **September 2021** I decided to cut back on time investment
-for the RBT project. This is mostly because other projects
-take away more of my time. I won't abandon rbt, but it should
-be pointed out that I am mostly only doing maintenance work,
-fixing some problems here and there, polishing this or that -
-but it is a very beta-ish project, and I can not make any
-guarantee that the project will ever leave its beta-ish 
-roots.
-
-## Why a new project rather than extending existing code?
-
-This is a valid question - why not contribute to an existing project
-rather than create a new project from scratch? There are a few
-problems with the existing projects out there, though.
-
-The scope of these projects is fairly often limited. For example: mac
-**homebrew** is a package manager, but other than that it isn't doing
-that much; and it does not work that well on linux or windows - I tried
-it in 2019 on linux and it did not work for me. Since I felt that Linux is a
-second-class citizen, I did not invest more time into the issues I
-had faced with homebrew.
-
-Another reason is that I do want to have a project that works as well
-as ruby does on any given operating system, as long as ruby is
-supported. I want to use it on windows, on haiku, on the BSDs, solaris,
-for cross-compilation targets and so forth.
-
-But there are **API-differences** as well and the way how these systems
-are used. For example, the classical **package managers** on linux do
-not allow you to easily use another prefix. Most of them, at the least
-on linux, assume that **/usr/** is the only prefix that is to be used
-(or /usr/cellar or something like this). I do not like this
-restriction - I want more flexibility, and complete control over
-the prefix in use at all times. I want to be able to use a hybrid 
-system too - partially using /usr/ as prefix, and partially using
-**versioned AppDirs**. With most package managers I would be forced
-into using just /usr/ as the global prefix - no alternatives. I
-don't like this restriction. Some of them even split it into
-/usr/ and /usr/local - for example, debian has python, perl and
-ruby packages under /usr/local/. What is this madness? Why do
-I need to bother with it? How can I easily change it?
-
-As far as I am aware, there is no trivial way to change any of
-that.
-
-This above listing of reasons can be extended really, but ultimately 
-it was less of an issue here to create a project that has these 
-different goals in mind, rather than try to retrofit existing code 
-bases out there towards my own use cases. I also preferred to use
-ruby rather than perl or python, so the number of available 
-package managers was even more limited.
-
-## How do I use the RBT project personally
-
-How do I use the **rbt project** primarily, on my **Linux** systems?
-
-What follows next is, more or less, a description of generic use
-cases that I may face on a daily basis.
-
-When I compile a (new) program via **RBT**, such as by issuing "compile
-htop" or "rbt htop" or "ry htop" (I make use of aliases a lot), then
-the **RBT-scripts** will (try to) compile the program **htop** for me,
-as specified by the corresponding "htop.yml" file, which is part of
-the RBT project - within the **Cookbooks** namespace. Hence, within
-**RBT::Cookbooks**.
-
-If I need to make a change to the compilation process, such as by
-using a different default **prefix**, then I simply edit the
-**htop.yml** file, change, add or remove the corresponding entry,
-and things will (should) work past this point - but I can also
-override the settings from the commandline, so I have all the
-flexibility required available.
-
-This, in turn, means that I control most of what I compile via
-.yml files, first and foremost - a text file. Other package managers
-do something similar if you look at them. Arch, for instance,
-uses PKG_BUILD or some file like that; gentoo uses ebuilds,
-debian also uses some designated files, and so forth.
-
-The "default settings" that I may use for these programs go into 
-a specific .yml file, whereas the **commandline switches** allow
-me to specifically override or cherry-pick other settings, based
-on the machine that I am working with. For example, on **GoboLinux**
-the AppDir prefix makes a lot of sense. On **slackware** on the
-other hand I may decide to just use **/usr** as option given
-to **--prefix=**.
-
-On **traditional** linux distributions, **/usr** as prefix is
-not the only possibility of course. Another popular way is to
-compile into the **user's home directory**. A commandline switch
-exists for the latter, for the RBT project, called **--home-directory**.
-This is equivalent to whatever the user's home directory ought to
-be, such as **/home/debug/** or **/home/joe/**. (I typically have
-a user account called **debug** on my systems, which is mostly
-concerned with debugging something on the target computer.)
-
-So, --home-directory for the user joe would be equivalent to
-**--prefix=/home/joe/**.
-
-This is useful in the sense that, ideally, I can get away with only
-passing the name of the program that is to be compiled, without
-needing to change anything. It allows me to be lazy - and
-just get things to "work", when they are compiled (if the compilation
-process itself will work).
-
-## @source_base_directory
-
-The very important instance variable **@source_base_directory**, defined
-at the toplevel **module RBT**, can be used to **denote the directory
-where archives of different programs are to be kept** (or are
-already kept).
-
-For **example**, on my home system I store the source code to many
-different programs in the directory **/home/x/src/**. That name 
-emerged mostly due to historic reasons, as the user "x" was just
-a generic name I would use for various different tasks, including
-making regular backups. (I did not want to type too much when
-doing a backup, hence why just one letter was used there.)
-
-As other users of the **RBT** project may wish to use another
-directory rather than the one listed above, such as
-a directory like **/Files/Archives/** or **/Depot/Archive/**
-or anything like that, there are essentially **three different
-ways** how to define your own target directory for keeping
-such **source archives**:
-
-(**1**) Simply set a new target altogether, via the **toplevel-method**
-called **RBT.set_source_base_directory()**. A shorter API exists
-as well, an alias to this method, called **RBT.set_source_directory()**.
-
-You can also use **RBT.source_directory = path**, if you would like to.
-
-As **argument** to this method, simply pass in **the path to the
-directory** that you wish to use, such as **/opt/** or **/home/src/** or
-any other location that you may wish to use.
-
-Explicit examples for the API that was mentioned above, will be shown
-next:
-
-    RBT.set_source_directory('/opt')
-    RBT.set_source_base_directory('/opt')
-    RBT.source_directory = '/opt'
-    
-    # Or for the target /Depot/Archive/
-
-    RBT.set_source_directory '/Depot/Archive/'
-
-Note that this method will **ensure** that a trailing '/' token will be
-the last character here. (Directories should end with a trailing **/** -
-it makes the subsequent code easier to handle when we can assume that
-this is always the case. I am not entirely sure why Linux/UNIX does
-not seem to share the same notion, but this may be due to a POSIX
-requirement perhaps, and a way how the filesystem is addressed in
-general, such as via **./**.)
+Note that this method will **ensure** that a trailing '/' token will be
+the last character here. (Directories should end with a trailing **/** -
+it makes the subsequent code easier to handle when we can assume that
+this is always the case. I am not entirely sure why Linux/UNIX does
+not seem to share the same notion, but this may be due to a POSIX
+requirement perhaps, and a way how the filesystem is addressed in
+general, such as via **./**.)
 
 The method call to **RBT.set_source_directory()** will **not** make
 the above directory persistent, mind you, so you may want to read
@@ -1142,9 +1528,10 @@ More specifically, on my home system, I'd do the following things manually
     cd /home/x/src/htop
     wget http://hisham.hm/htop/releases/2.0.2/htop-2.0.2.tar.gz
 
-If you, for instance, want to store multiple versions of GLib, then a 
-downcased directory called glib/ has to exist within that 
-source archive directory - just as the example above shows.
+If you, for instance, want to store multiple versions of GLib, then
+a downcased directory called glib/ has to exist within that 
+source archive directory - just as the example above shows for
+htop.
 
 Different versions of **GLib** can then be stored in that directory.
 
@@ -1154,11 +1541,13 @@ The path would, in my case, be:
 
 That's it, essentially!
 
-Past this point, the cookbooks project can feedback some information
-about htop via "scookie".
+Past this point, the cookbooks project - or rather, the Cookbooks
+submodule of the RBT namespace - can feedback some information
+about htop via the executable called "scookie".
 
-For example, to use scookie (<b>bin/scookie</b>) and thus display information
-about a program in a colourized manner, on the commandline, do:
+For example, to use scookie (<b>bin/scookie</b>) and thus display
+information about a program in a colourized manner, on the
+commandline, do:
 
     scookie glib
     scookie htop
@@ -1257,22 +1646,22 @@ information content is the same.)
 
 ## Optional dependencies for the RBT gem
 
-The **wget gem** is recommended, but you can also use the RBT
-project without the wget gem. In that case, if the wget gem is not 
-available, the RBT project will attempt to use the wget 
-binary via a **system()**-call, hence an "external" program,
-to ruby.
+The **wget gem** is recommended as an optional dependency for the
+RBT gem, but you can also use the RBT project without the wget
+gem just fine. In that case, if the wget gem is not available, the
+RBT project will attempt to use the wget binary via a
+**system()**-call, hence an "external" program, to ruby.
 
-This requires the installation of **wget** e. g. from this URL (or from
-your package manager's repository), unless wget is already available
-on your local computer system:
+This requires the installation of **wget** e. g. from this URL (or
+from your package manager's repository), unless wget is already
+available on your local computer system:
 
 http://ftp.gnu.org/pub/gnu/wget/?C=M;O=D
 
-Of course, most Linux systems will have "wget" available by
-default, so the above more applies towards operating systems
-such as windows (although more recent windows versions
-also include a linux-subsystem including bash, the **WSL**).
+Of course, most Linux systems will have "wget" available by default,
+so the above more applies towards operating systems such as windows
+(although more recent windows versions also include a linux-subsystem
+including bash, the **WSL**, so this should also not be a problem).
 
 ## Increment Program Version
 
@@ -1511,20 +1900,6 @@ This is why the **notification part** is more important than the
 **auto-correct part**. See the next subsection for some
 autocorrection that can be done.
 
-## Autocorrecting some errors
-
-The RBT scripts can attempt to auto-correct some errors. This
-is presently in testing. The few errors that RBT can try to
-auto-correct are mostly related to libtool.
-
-If the file use_autofixing.yml contains a String called t or
-true, meaning "enable autofixing", then auto-correcting will
-be used. There is another option that has to be set to true
-though, which is the "is_on_roebe?" settings, which indicates
-my home directory use. Presently (Sep 2017) this option does
-not work too reliably, so I am still testing it. You can 
-test it too though if you enable "is_on_roebe".
-
 ## Finding all programs that start with a specific letter
 
 If you wish to find all registered programs that start with
@@ -1577,7 +1952,7 @@ This requires the configuration option time_compilation set to
 true it the corresponding yaml file (within the <b>configuration/</b>
 subdirectory).
 
-If this setting is set to <b>true</b>, then RBT::Compile will show, on the
+If this setting is set to <b>true</b>, then RBT::Installer will show, on the
 commandline, how long it took to compile a program, in seconds (and also
 in minutes). The default for this setting is <b>true</b> as of <b>January
 2018</b>.
@@ -1585,7 +1960,7 @@ in minutes). The default for this setting is <b>true</b> as of <b>January
 Note that the time it took to compile the given program at hand will
 only be shown if there was no proble/error during the compilation
 process. This may be fine-tuned at a later time, but for now, the
-functionality at the least exists as part of <b>RBT::Compile</b>.
+functionality at the least exists as part of <b>RBT::Installer</b>.
 
 The time it took, in seconds, will also be stored in the file
 called <b>database_storing_compile_times.yml</b>, in a simple key-value
@@ -1601,6 +1976,22 @@ The commandline option for this is:
 
     rbt --show-compile-time-statistics
 
+## Packaging the RBT scripts
+
+You can package all the latest RBT Scripts by using a commandline
+flag such as this:
+
+    rbt package_cookbooks
+    rbt --package_cookbooks
+
+This will create a directory in /Depot/Archives/ and package the
+RBT Scripts into that directory.
+
+Of course you can do so manually as well, but I wanted to have
+this functionality at the least available for when a user is
+on windows and may need to transfer the files, for whatever
+the reason(s).
+
 ## systemd
 
 I personally do not like systemd in the slightest nor can I align
@@ -1649,6 +2040,22 @@ among many more; and that's just computer-related
 projects. I have many non-computer related projects,
 hobbies and things that require time investment.)
 
+## Subversion
+
+You can try to download from SVN sources, by issuing the
+following command:
+
+    rbt dosbox svn # This would download dosbox using svn
+
+Note that this depends on the setting <b class="color: royalblue">svn_url</b>
+in the respective cookbook file (in this case dosbox.yml).
+
+The <b>svn_url</b> setting must be specified, as otherwise RBT
+can not download the code via svn.
+
+It is quite rare that source archives depend on svn
+nowadays, though.
+
 ## Creating a .yml yaml file for a specific program
 
 If you modify a .yml file, from the rbt project,
@@ -1714,7 +2121,7 @@ is available.
 
 Do note that the variable <b>RBT_SOURCE_DIRECTORY</b> will
 <b>overrule every other setting</b>, except for values
-set from the commandline to RBT::Compile, such as via
+set from the commandline to RBT::Installer, such as via
 <b>--use-this-source-directory=</b> - so use this variable
 with care. If you do not need it, I recommend to simply not
 set it at all; it really only exists in the event that
@@ -1839,7 +2246,7 @@ examples:
 
 The code for this resides in the method
 **try_to_output_how_many_processors_this_computer_has**, which
-is part of **class RBT::Compile**. (This statement is correct at
+is part of **class RBT::Installer**. (This statement is correct at
 the least for **October 2018**).
 
 ## Compile/Installation shell
@@ -1942,13 +2349,18 @@ Note that you can also generate a .html page for some select programs,
 via the commandline. For instance, if you wish to show ruby, python
 and php, then you can use this commandline invocation:
 
-    cookbook --create-html-page-for-these-programs=ruby,python,php
+    rbt --create-html-page-for-these-programs=ruby,python,php
 
 The input program names should be separated via **,** and not 
 include any '-' or '_' character. There are also some ways to
 display the full, e. g. **KDE stack**. More on this in another
 section of this README file.
 
+To query all available programs, do:
+
+    rbt --all_available_programs?
+    installer --all_available_programs? # or use RBT::Installer.
+
 ## Checking for binary duplicates
 
 If you ever want to find out whether you have **binary duplicates**
@@ -1975,26 +2387,30 @@ Usage examples for the commandline invocation:
 **Compile hooks** are defined in the **rbt gem**, in the file
 **compile_hooks.yml**
 
-In that file you can *hook* the compilation of some programs to
+Via that file you can *hook* the compilation of some programs to
 the compilation of other programs.
 
-This is somewhat similar to the chained programs.
+This is somewhat similar to the chained programs feature - 
+a chained program means that several programs will be
+compiled one after the other, sort of like a <b>dependency
+chain</b>.
 
-For example, if you compile **ffmpeg**, and have mpv installed,
-then a new compilation of ffmpeg will trigger the re-compilation
-of mpv. This will only be done if you have mpv installed
-at $PROGRAMS/Mpv though.
+For example, if you compile <b>ffmpeg</b>, and have <b>mpv</b>
+installed, then a new compilation of ffmpeg will trigger the
+re-compilation of mpv. This will only be done if you have
+mpv installed at $PROGRAMS/Mpv though.
 
-<b>Be careful with this, though </b>- it can lead to problems,
+<b>Be careful with this functionality</b> - it can lead to problems,
 in particular when compilation may fail. I do not know whether
 I will keep this functionality (as of the year 2018); the
 future will tell. It does add some complexity after all, and
 I am not sure if it is a good idea to have this.
 
-For now I recommend to use this feature only sparingly, if at
-all. Manual control over the process may be simpler in the
-long run since you are in the driver seat.
-
+For now I recommend to use this feature only sparingly, if at all.
+Manual control over the process may be simpler in the long run
+since you are sitting in the driver seat and can decide what 
+you need and what you don't need.
+    
 ## Advanced usage of the RBT project - helpful information
 
 This **subsection** here will explain **how to use rbt on a linux
@@ -2063,9 +2479,9 @@ Invocation examples:
     rbt mpcr
     rbt gcc
 
-Keep in mind that you can also use the LFS/BLFS instructions.
-They are available via the "blfs" entry in the respective
-.yml cookbook file.
+Keep in mind that you can also use the LFS/BLFS instructions. They
+are available via the "blfs" entry in the respective .yml cookbook
+file.
 
 **Glibc** is obviously also a target candidate that could/should
 be upgraded eventually, but this is a rather delicate step - many
@@ -2130,37 +2546,6 @@ the user to decide which behaviour is to be used - but for
 the time being (February 2020) the described behaviour is
 the only valid way.
 
-## Build directories
-
-Some progams insist on using a build directory that is
-separate from the directory where the source code is
-kept.
-
-For example, the KDE program called **kirigami2** requires
-an "out-of-source" build directory.
-
-There is a relevant entry in the cookbooks .yml files that
-can be used, called **use_build_directory**. If this entry
-is set to **true** or to **yes** (both are equivalent to 
-one another) then the RBT project will make use of a
-build directory for compiling a particular program.
-
-You can also get an overview over the programs that make
-use of a build directory, by using any of the following
-APIs on the commandline:
-
-    rbt --show-all-programs-that-make-use-of-a-build-directory
-    rbt --all-build-directory
-    rbt --all-build-directories
-    rbt --build-directories?
-    rbt --build-directories
-
-In order for this to work on your system you may have to
-create the expanded cookbook directory. We could use the
-internally distributed directory since as of 2021, but
-for the time being the above approach will still be
-valid as-is.
-
 ## RBT project will install these executables
 
 The RBT project will install the following executables in the **bin/**
@@ -2212,6 +2597,29 @@ and so on. Using **numbers** may be simpler, though, as you do not
 have to remember the names as-is, while still being able to use
 the correct compilation order.
 
+If you want to compile all mate-components into their own standalone
+prefix via an environment value, you can use the following list:
+
+    env_compile_via_prefix matedesktop MATE_DESKTOP
+    env_compile_via_prefix libmatemixer MATE_DESKTOP
+    env_compile_via_prefix libmateweather MATE_DESKTOP
+    env_compile_via_prefix matemenus MATE_DESKTOP
+    env_compile_via_prefix matepanel MATE_DESKTOP
+    env_compile_via_prefix matenetbook MATE_DESKTOP
+    env_compile_via_prefix matemedia MATE_DESKTOP
+    env_compile_via_prefix marco MATE_DESKTOP
+    env_compile_via_prefix matesettingsdaemon MATE_DESKTOP
+    env_compile_via_prefix libmatekbd MATE_DESKTOP
+    env_compile_via_prefix matecontrolcenter MATE_DESKTOP
+    env_compile_via_prefix matesensorsapplet MATE_DESKTOP
+    env_compile_via_prefix caja MATE_DESKTOP
+    env_compile_via_prefix cajaextensions MATE_DESKTOP
+    env_compile_via_prefix engrampa MATE_DESKTOP
+    env_compile_via_prefix eom MATE_DESKTOP
+    env_compile_via_prefix mateutils MATE_DESKTOP
+    env_compile_via_prefix pluma MATE_DESKTOP
+    env_compile_via_prefix mateterminal MATE_DESKTOP
+
 ## Module programs (the extended cookbook dataset)
 
 **Module programs** refers to the ability to access all registered programs at
@@ -2404,8 +2812,15 @@ so forth (if there are several entries that is).
 
 <b>RBT</b> will then apply these sed-modifications by default.
 
+(Internally there is even a SedWrapper class that can be used
+as replacement for GNU sed - but it has a few bugs and is
+mildly deprecated. Perhaps one day I may fix it, but for
+the time being it will stay as it is. We will default
+to GNU sed as far as RBT itself is concerned.)
+
 If you do not need this for a given program then you can
-<b>disable</b> this behaviour on the <b>commandline</b>, via:
+<b>disable</b> this behaviour on the <b>commandline</b>,
+you can disable it via the following commandline flag:
 
     rbt htop --disable-sed
     rbt htop --disable-sed-modifications
@@ -2445,13 +2860,18 @@ a cookbook .yml file, then you can invoke:
     RBT::ApplySedOperations.new :glibc
     RBT::ApplySedOperations.new :htop
     RBT::ApplySedOperations.new 'coreutils'
-
+    
 ## Compiling a random program
 
-If, for whatever reason, want to compile a random program, then
-you can use a commandline switch such as the following:
+If, for whatever the reason, you want to compile a random
+program, then you can use a commandline switch such
+as the following:
 
     rbt --random-program
+    # or if you aliased "compile" onto "rbt"
+    
+    compile RANDOM
+    compile random
 
 ## Upgrading programs through a file
 
@@ -2473,30 +2893,38 @@ Invocation examples:
 The reason why a default filename exists is so that other projects
 can auto-generate such a file, which we can then use for **RBT**.
 
-## Compiling the dependencies of a program as well
+## Compiling the dependencies of a program as well - handling dependencies via the RBT gem
 
-You can compile the dependencies of a program if you want to,
-via a commandline such as:
+You can <b>compile the dependencies</b> of a program if you want to,
+via a commandline instruction such as:
 
-    rbt kbreakout --compile-dependencies-as-well
-    rbt  rbt kbreakout --with-deps
+    rbt kbreakout --compile-dependencies-as-well # verbose, but good to read, in my opinion
+    rbt kbreakout --with-deps                    # shorter and easier to type
+    rbt php with-deps                            # this should work as well, but using -- is recommended
+    rbt gcc3 wdeps                               # similar as above
+    rbt feh wdeps                                # and yet another example
 
-Note that this will try to compile all the dependencies AND the program
-as well, with the dependencies first, and the program that was given
-as argument coming last.
+Note that this will try to compile <b>all</b> the dependencies AND the
+program as well, with the dependencies first, and the program that
+was given as argument coming last.
 
-This presently (October 2018) works in a brute-force manner, meaning
-that it will compile the dependencies even if they are already installed.
+This presently (as of <b>October 2018</b>) works in a brute-force manner,
+meaning that it will compile the dependencies even if they are already
+installed.
 
-In the future, this behaviour may change, but for the time being,
-that has to suffice (the feature is thus somewhat experimental
-right now; it has to be tested further).
+In the future, this behaviour may change, and code may be added to
+check which dependencies are met and which ones are not met, but for
+the time being, that has to suffice (the feature is thus somewhat
+<b>experimental</b> right now; it has to be tested further). It may
+be simpler to not use this feature for now, and instead compile
+programs on an individual basis instead.
 
 Do note that since as of March 2020 you can display all programs
 that depend on another program whose name is known.
 
 For example, if you wish to find out which programs all depend
-on cmake then you can use the following:
+on <b>cmake</b> then you can use the following commandline
+flag:
 
     rbt --show-programs-with-this-as-dependency=cmake
 
@@ -2527,26 +2955,22 @@ Usage example:
 So you get an Array back, telling you which programs are the
 dependencies of these three programs (the Array that contains
 php, ruby and python).
-  
-## Internals of class RBT::Compile
 
-**class RBT::Compile** is the main class of the RBT project, as it allows
-us to compile or install a program from source. It is, more or less, the
-central entry point to RBT - even though you can invoke the other .rb 
-files directly, RBT::Compile often provides a simpler convenience access
-to the disparate functions of the RBT project.
+Dependencies can be specified as <b>ranged</b>, which means that
+they will be valid only under some conditions.
 
-This subsection here will explain a few key decisions made, in the long
-run; and will also explain a few internals.
+For example, consider the following entry which you can
+find in some entries of the individual cookbooks (the corresponding
+.yml files):
 
-Do not worry if this may be a bit confusing at first - it is meant
-primarily for me, and for others who may want to extend the RBT
-project one day.
+    glib2 >= 2.17.6
 
-The method set_configure_base_directory(), defined in the file **misc.rb**,
-is used to determine the directory where the configure script ought to
-reside. That way we can enter a separate build directory yet still be
-able to invoke configure (or cmake) at the right directory target.
+This entry means that the program requires glib2 of at least
+version 2.17.6 or higher.'
+
+The <b>Ruby Build</b> Tools will notify the user if the dependency
+does not match. The default compilation mode will be to interrupt
+compilation when a dependency is not met. 
 
 ## Games support
 
@@ -2733,10 +3157,10 @@ on my system, but you could take any other name too, such as /pkg/ or
 /home/programs/ and so forth.)
 
 **class RBT::CleanupSystemTags** can eliminate stray (non-existing)
-symlinks, and it is invoked from class RBT::Compile, so the directory
+symlinks, and it is invoked from class RBT::Installer, so the directory
 at **/System/Tags/** will be guaranteed to **not** have any stray symlinks
-whenever RBT::Compile is run. (This is checked in the **post-installation**
-part of class RBT::Compile.)
+whenever RBT::Installer is run. (This is checked in the **post-installation**
+part of class RBT::Installer.)
 
 The class **RegisteredTags** can be used to register all available
 tags in a .yml "database".
@@ -2772,7 +3196,7 @@ handled by the RBT project.
 
 In general, the main functionality resides in the file
 **rbt/toplevel_methods/symlink.rb**. When it comes to class
-**RBT::Compile then the file is rbt/compile/symlink.rb**.
+**RBT::Installer then the file is rbt/compile/symlink.rb**.
 
 Certain settings in the cookbook .yml files can be used to do
 some trivial symlinking jobs, such as symlinking **lib64/** to
@@ -2821,7 +3245,7 @@ into the /usr/lib/ directory. The name for this class is fairly unwieldy,
 but I needed the functionality in a specific .rb file that I could
 call from the commandline.
 
-By default, RBT::Compile does **not** make use of this class, but you
+By default, RBT::Installer does **not** make use of this class, but you
 can enable it via any of the following commandline flags:
 
     rbt gtk+ --symlink-into-usr-lib-dir
@@ -2970,60 +3394,20 @@ The result will then be something like this:
 
     RBT: There are 4102 registered binaries in all cookbook files.
 
-## Environment settings
+## Suggest the content of a cookbook .yml file
 
-Sometimes environment settings, stored in ENV as far as ruby itself
-is concerned, may interfere with compilation. For example, assigning
-to the env variable called TZ may cause a build to fail (TZ stands
-for TIMEZONE).
+If you compile a program from source successfully, say **glib**,
+into an AppDir prefix such as **/Programs/Glib/2.58.1/**, then
+you may use class **RBT::SuggestCookbookFor** to display the
+content of a .yml file for glib. This is obviously not perfectly
+accurate, but may help to get things started when you wish to
+create your own .yml files.
 
-I consider this pretty awful for shells such as bash or zsh, but
-I did not design any of them.
+Invocation examples from the commandline:
 
-What this means as far as the RBT project is concerned is that we
-may need a way to easily **AVOID** using any ENV variable that may
-be faulty.
-
-The simplest way how to do this may be by not using any ENV variable,
-save for PATH (which has to work, as otherwise the compiler can not
-find anything).
-
-Usage examples:
-
-    rbt nss  --clear-envs ntrad
-    rbt nspr --clear-envs ntrad
-
-This would attempt to compile both nss and nspr without any environment
-variables (save for PATH).
-
-Since as of **December 2018**, a new class called 
-**RBT::CompileViaEnvironmentVariableAsPrefix** can be used to 
-specifically compile into a prefix that is specified via an
-**environment variable**.
-
-This allows me to then use something like this on the commandline:
-
-    env_prefix xfconf
-
-And it will compile the XFCE xfconf component into the prefix 
-specified by the environment variable called XFCE_PREFIX,
-which I happen to have set to a value such as
-**/Programs/Xfce/4.12.0/**.
-
-## Suggest the content of a cookbook .yml file
-
-If you compile a program from source successfully, say **glib**,
-into an AppDir prefix such as **/Programs/Glib/2.58.1/**, then
-you may use class **RBT::SuggestCookbookFor** to display the
-content of a .yml file for glib. This is obviously not perfectly
-accurate, but may help to get things started when you wish to
-create your own .yml files.
-
-Invocation examples from the commandline:
-
-    rbt --suggest-cookbook-for=glib
-    rbt --suggest-cookbook-for=htop
-    rbt --suggest-cookbook-for=pango
+    rbt --suggest-cookbook-for=glib
+    rbt --suggest-cookbook-for=htop
+    rbt --suggest-cookbook-for=pango
 
 **Note** that this depends on these programs being installed
 in the **programs_directory?**, which on my system is equal
@@ -3093,6 +3477,35 @@ as in a restricted environment like at a university campus site), a
 
     rbt htop --disable-colours
 
+## Disabling colours
+
+If you dont want to display or use colours, either disable
+them globally in the config.yml file (the entry is called 
+`use_colours_output` there) or pass --nocolor (or --nocol or
+--nocolour) on the commandline, like this:
+
+    rbt libmemcached --nocolor
+    rbt libmemcached --nocolor
+    rbt libmemcached --nocolour
+    rbt libmemcached --nocolours
+    rbt libmemcached nocolours
+
+Note that you can also change the colours. For this, edit the
+file <b>colours.yml</b>
+
+The above will, however had, only disable the colours for the
+<b>current</b> run.
+
+You can find out whether you use colours specifically or
+not, by issuing this command:
+
+    rbt --use-colours?
+
+You can also <b>permanently disable the colours</b> by issuing
+the following command:
+
+    rbt --permanently-disable-colours
+
 ## Auto-updating libraries installed under a versioned AppDir
 
 You can auto-update the "libraries:" entry in a given .yml file,
@@ -3306,43 +3719,6 @@ If this configuration option is set to **true**, then we will
 run "strip --strip-unneeded" by default.
 
 On my home system this defaults to **true**.
-    
-## Batch-downloading all source archives
-
-You can download all registered **source archives** by
-calling **class RBT Cookbooks::DownloadAllSourceArchives**.
-
-I use an alias to call that **.rb** file. Then I can do,
-for example:
-
-    download_all_source_archives
-
-Alternatively, you can also **invoke the file from the commandline 
-directly, by issuing either one of the following**:
-
-    rbt --download-all-source-archives
-    rbt --downloadallsourcearchives
-    rbt --grab-source-archives
-    rbt --grabsourcearchives
-
-From within Ruby code, you can use the following **toplevel-API**
-to download all source archives:
-
-    RBT.download_all_source_archives
-
-You can also download only those files that have a certain **tag**
-registered. For example, if you want to download all programs that
-have the tag "plasma" attached, you can issue the following 
-command (and argument) this:
-
-    download_all_source_archives --tags=plasma
-
-In order for this to work, the tag has had to be **registered**
-(and thus, logically, exist).
-
-If you need an overview over the existing tags, issue this command:
-
-    cookbooks --available-tags
 
 ## Available utility scripts of the RBT project
 
@@ -3398,6 +3774,15 @@ Of course this works through **rbt** as well:
 
 ## Postinstallation steps
 
+First, we have to define the "postinstallation phase".
+
+The <b>Postinstall-Phase</b> will begin after compilation has 
+finished. This also means that the postinstall step can only happen
+if the compilation procedure was successful - at the least from
+a technical point of view. We could assume that a post-install
+step must always happen, but then we should not call it
+post-installation step.
+
 If you **compile a program from source**, sometimes there may be post-installation
 steps that may have to occur after the program has been compiled. For example,
 if you wish to **symlink** **cc** to point to **gcc**, then we need to have
@@ -3424,7 +3809,7 @@ The leading ' - ' in the line above is for **YAML** and it denotes an entry that
 is to be kept as an Array. The rest of this Array is quite easy to understand.
 The instruction <b>copy_files</b> will simply copy several files; and these files
 are denoted within the **square brackets { }**. These entries can b a file or a
-directory and **RBT::Compile** will correctly handle these.
+directory and **RBT::Installer** will correctly handle these.
 
 The very **LAST entry** is the target location that you wish to copy these
 files to, which in the above case is at
@@ -3462,6 +3847,18 @@ file is any of the following two:
 
 Have a look at the file called **vte.yml** for a complete example.
 
+Various additional macros exist that can be used in this regard.
+
+For instance, to create a directory in the app-dir prefixed
+target, one can use this:
+
+    postinstall:
+    - mkdir APPDIR_INSTALLATION_PREFIX/logs/
+
+This requires that the program is to be compiled via an
+appdir prefix (such as via --ntrad or --apdir on the
+commandline, to <b>RBT::Installer</b>).
+
 Since as of June 2022 you can also invoke the postinstall
 action from the commandline.
 
@@ -3473,6 +3870,19 @@ Example for this:
 This was added in particular because docbook is quite painful
 to install.
 
+Usually, via <b>postinstall actions</b>, you can do something like
+remove certain directories or files, create new files or new
+directories, handle symlinks and similar actions. It is quite
+rarely needed, but at least this functionality exists
+whenever you need it.
+
+You can of course disable this behaviour if you want to, 
+at run-time.
+
+Use something like this:
+
+    rbt htop --no-postinstall
+
 ## The $PATH variable
 
 You can put <b>/usr/bin/</b> at the beginning of $PATH, via:
@@ -3496,23 +3906,54 @@ that within **ruby**, PATH is available under:
 
 ## Autogen
 
-Some programs require the program called "autogen". In the respective
-cookbook file, this is the corresponding entry called
-<b>use_autogen</b>.
+Some programs require a (very old) program called "autogen".
+This refers to <b>GNU autogen</b>; if you wish to read up more about
+<b>autogen</b> then you could do so here:
 
-If this entry is set to **true**, then **RBT::Compile** will invoke
-autogen for that particular program.
+https://www.gnu.org/software/autogen/
 
-If you want to find out whether a program, such as "pacman",
+In the respective cookbook file, as far as the RBT gem is concerned,
+support for autogen will be handled via the corresponding entry
+called <b>use_autogen</b>.
+
+If this entry is set to **true** (or **yes**), then **RBT::Installer**
+will <b>invoke autogen</b> for that particular program, before
+trying to run <b>./configure</b>.
+
+If you want to find out whether a program, such as "<b>pacman</b>",
 requires the use of autogen, you can use this query to find
 out on the commandline:
 
-    rbt pacman -use-autogen?
+    rbt pacman --use-autogen?
 
 The result may be output like this:
 
-    RBT::Compile: No, autogen will NOT be used for the program pacman.
+    RBT::Installer: No, autogen will NOT be used for the program pacman.
+
+To specifically enable autogen for the current invocation
+run you can use:
+
+    rbt htop --enable-autogen
+
+Conversely, you can also specifically disable autogen, via
+--disable autogen. This is only necessary in rare cases
+when you do not wish to have autogen to be run. Only a
+few programs will require autogen normally.
+
+Example to disable autogen for the current invocation
+run:
+
+    rbt htop --disable-autogen
+
+## hebang Fixing
 
+You can fix all Shebangs of the RBT scripts by issuing:
+
+    rbt --shebang
+
+Use with care, though. Most users will never need to
+use this functionality.
+    
 ## Picking a specific program version
 
 You can e. g. select a local version via:
@@ -3628,13 +4069,41 @@ a white or light background, but I would need a specific suggestion
 and a name for this colour "scheme". Then I can add more colours
 and even colour schemes for use here.
 
+Note that you can customize the colours a little bit, via the
+.yml file called <b>colours.yml</b>. The content of that .yml
+file may look like this:
+
+    information: lightblue  # 
+    warn:        red        # For warnings to the user. 
+    error:       red        # 
+    file:        magenta    # 
+    normal:      green      # The default colour to use.
+    important:   brown      # cyan
+    directory:   cyan       # brown
+    fancy:       teal       # bold green
+
+Not all output by the RBT project is currently handled via that
+file, but most output could be customized; and eventually it
+is planned to allow a user to modify <b>all</b> colours that
+way. If you want to change the colours in use then you have
+to modify that .yml file. That file can be found at 
+<b<rbt/yaml/colours/colours.yml</b> - you may have to look 
+at your local ruby installation to find out where that .yml
+file will reside. For instance, on my home system that
+file, once the rbt gem is installed, can be found here:
+
+    /home/Programs/Ruby/Current/lib/ruby/site_ruby/3.2.0/rbt/yaml/colours/colours.yml
+
+For most other users it may be in /root/.gem/gems/ or
+in another directory.
+
 ## Specifying which build system to use
 
 By default, most **.yml** files that are part of the RBT project will
 make use of the **GNU configure** build system - e. g. **configure**,
 **make** and **make install**. You can, on the commandline, determine
 which build system is to be used; and you can also instruct
-**RBT::Compile** to **use another build system**.
+**RBT::Installer** to **use another build system**.
 
 For example, if you wish to specifically use **configure**, then
 you can do this:
@@ -3780,17 +4249,6 @@ compilation has completed successfully, symlink into the
 
 **IS_ROEBE** to a value of 1).
 
-## porg
-
-Porg is a small utility that allows a user to track which files are
-installed. RBT supports the use of porg through a configuration
-file, called **use_porg.yml**.
-
-To query from the commandline whether porg is available on the
-given computer system, try:
-
-    rbt --is-porg-available?
-
 ## Some options for the individual cookbook files explained
 
 This section will explain some entries in a .yml file.
@@ -4010,7 +4468,7 @@ you can see the following line:
 
     configure_command_to_use: ./configure.sh
 
-It thus specifies that RBT::Compile will make use of that
+It thus specifies that RBT::Installer will make use of that
 **configure.sh** shell scripts rather than the more generic
 **configure** invocation run.
 
@@ -4215,13 +4673,20 @@ Until November 2019, the RBT project had **class RBT::Infobox**. This
 was moved into the AsciiParadise project in November 2019, and renamed
 to **Flexbox**.
 
+Let's have a look how the new Flexbox looks, on the commandline:
+
+<img src="https://i.imgur.com/NwC33Gu.png" style="margin: 1em">
+
+(Ignore the colour bug in the middle; this may be fixed at a later
+time. It's just a cosmetic issue, not a functional regression.)
+
 The **Flexbox** can show some information about the program that is to
 be compiled/installed next - or a program that you may wish to install.
-It is thus only a **visual aid**, through colours, and Unicode symbols,
-on the commandline.
+It is thus only a **visual aid**, through colours, and <b>Unicode
+symbols</b>, on the commandline.
 
-For this to work, the program has to be **registered** prior, as part
-of the RBT project.
+For this to work, the program has to be **registered** prior, as
+part of the <b>RBT project</b>.
 
 You can specifically tell RBT to only show the Flebox, by making use of
 the commandline flag called **--show-flexbox-only**.
@@ -4287,6 +4752,12 @@ of the filesystem, and so forth. While this can be tweaked by
 the user, for the time being, it is best to just follow these
 assumptions for now. 
 
+## Currently compiling programs
+
+You can query which program(s) are currently compiled by issuing:
+
+    rbt currently_compiled?
+
 ## Show all statically compiled programs on the given computer system
 
 If you need to show all statically compiled programs on the given
@@ -4303,7 +4774,7 @@ The class was added in November 2019 to the rbt project.
 Some problems and errors may happen during compilation or
 installation of programs.
 
-These are handled internally by RBT::Compile, but they will
+These are handled internally by RBT::Installer, but they will
 also be registered in a module-method onto the RBT Namespace.
 
 It is available via the following code:
@@ -4321,12 +4792,12 @@ be done by the following commandline flag:
     rbt --dont-stop-on-errors
     rbt --ignore-errors
 
-This would instruct **RBT::Compile** to **not** stop on
+This would instruct **RBT::Installer** to **not** stop on
 errors and instead (try to) continue.
 
 ## Pre-install actions
 
-**Pre-install actions** are actions taken before **RBT::Compile**
+**Pre-install actions** are actions taken before **RBT::Installer**
 will invoke the configure script, or cmake invokation.
 
 Typically the pre-install action(s) may involve calling a shell
@@ -4396,7 +4867,7 @@ if you forgot the name and don't want to look up or can
 not look up, you can try to leverage class 
 **RBT::MapThisInputToThatRegisteredProgram**.
 
-class **RBT::Compile** also makes use of that class if the
+class **RBT::Installer** also makes use of that class if the
 input is not a registered program.
 
 ## Configure profiles / decorators
@@ -4533,7 +5004,7 @@ do so, via <b>rbt</b> like in the following examples:
     rbt --create-program=python-3.3.3
 
 Do take note that CreateAppDirSkeleton may be called from some RBT scripts,
-in particular **RBT::Compile**. Some directories will not see that
+in particular **RBT::Installer**. Some directories will not see that
 their default symlink (called **Current**) is removed, such as gcc or
 binutils, as otherwise subsequent compilation runs would not work
 to the **Current** not being set properly.
@@ -4623,7 +5094,7 @@ like so:
 
     create_pkgconfig :htop
 
-This means that RBT::Compile will be used internally, and then
+This means that RBT::Installer will be used internally, and then
 generate the file **htop.pc**. (In this case create_pkgconfig
 is an alias to **bin/create_pkgconfig_file**).
 
@@ -5046,6 +5517,39 @@ Invocation example:
 
     rbt kerberos --use-blfs-instructions # Compile kerberos in the BLFS way.
 
+Since LFS/BLFS is such a useful project, the RBT suite has some
+more support in this regard. This is unsurprising, as the
+<b>Linux From Scratch</b> (LFS) Project has instructions
+on how to compile programs from source. So it has a somehwat
+similar meta-goal, like RBT.
+
+These instructions are immensely useful. A lot of the information
+from LFS/BLFS was integrated into the RBT project.
+
+Many individual cookbook yaml files can point towards the
+LFS/BLFS page, which will often contain additional useful
+information in case you get stuck with something.
+
+You can try to show this URL by doing this:
+
+    blfs curl
+
+This would show the BLFS remote URL of the program called
+<b>curl</b>.
+
+Since as of <b>July 2017</b>, you can also directly paste the
+content of the remote BLFS webpage onto the terminal, if there
+is a remote BLFS page associated with a given program.
+
+The way to do this is as follows:
+
+    rbt gcc --paste-blfs-page
+
+If you want to show all programs that have a blfs entry, use the
+following command:
+
+    rbt --show-programs-with-a-blfs-entry
+
 ## Copying archives to the current working directory
 
 I sometimes needed to be able to copy source archives to the current
@@ -5247,6 +5751,17 @@ If you wish to generate a new gobo-recipe, try:
     require 'rbt/linux/gobolinux/create_recipe.rb'
     RBT::Gobolinux::CreateRecipe.new('htop') # <- Name of the program should go in here.
 
+## Copy only the headers
+
+If you want to copy only the headers of a program, do this:
+
+    rbt gmp only_headers
+    rbt gmp --only_headers
+
+Of course you can do so manually, but in particular on windows
+I tend to be lazy, so support for this was added. Most users
+rarely, if ever, will need to do so, though.
+
 ## Finding headers (.h files) of registered programs
 
 If you need a toplevel API to determine which .h files belong
@@ -5304,7 +5819,7 @@ project. I am open to extend this functionality to allow other
 projects to use another dataset, though.
 
 The boolean constant **ALSO_AUTOMATICALLY_INSTALL_THE_UPDATED_GEM**,
-defined in class RBT::Compile, controls whether the updated gems
+defined in class RBT::Installer, controls whether the updated gems
 will automatically be installed by the RBT project. If set to
 true then RBT will not only download the respective gem, but
 also install it. Since not everyone may want this, the constant
@@ -5419,7 +5934,7 @@ fully describe an individual recipe (cookbook). Just
 look the .yml file and you should have all the data
 necessary to compile the program at hand - of course
 you may still need wrapper code that actually makes
-use of that dataset, such as **RBT::Compile** does
+use of that dataset, such as **RBT::Installer** does
 normally.
 
 ## KDE
@@ -5611,10 +6126,12 @@ project rather than the RBT project.)
 
 ## Downloading in general and downloading a remote URL into a specific local directory
 
-The **rbt project** has some support for downloading a remote archive into the
-local filesystem/directory. This functionality was added primarily to aid in
-the setup stage of the RBT project, in particular when you are before a freshly
-setup computer system.
+The **rbt project** has some code support for downloading a remote archive or any
+other remote file into the local filesystem/directory. This functionality was added
+primarily in order to aid the user in setting up the RBT project properly, in
+particular when the user is before a freshly setup computer system. In other words,
+to help and support "boostrapping". This is not the only use case, of course; other
+use cases exist as well as to why this functionality was added to the RBT project.
 
 If you would like to download an archive from a **remote URL** into a specific
 (local) directory, you can use an **API** such as this here, from the
@@ -5633,11 +6150,15 @@ current working directory. If this is the case, you can use
 this variant instead:
 
     rbt htop --downloadhere
+    rbt htop --dhere # This works too, if you are really laze.
 
-This will download the htop archive into the current working directory.
+This command invocation will download the htop archive into the current
+working directory. Note that this almost exactly identical to <b>wget 
+https://github.com/htop-dev/htop/releases/download/3.1.2/htop-3.1.2.tar.xz</b>.
 
-If you wish to quickly download e. g. htop or another program, you can
-also use the following simpler **toplevel API** (from within ruby):
+If you wish to quickly download e. g. htop or another program, and wish
+to do so from within ruby itself, you can use the following simpler
+**toplevel API**:
 
     RBT.download :htop
 
@@ -5646,12 +6167,13 @@ the following API with the full URL instead:
 
     RBT.download 'http://hisham.hm/htop/releases/2.2.0/htop-2.2.0.tar.gz'
 
-It thus is simply **a convenience feature** and works really well
+Thus, it is simply **a convenience feature** and works really well
 in **irb*. Obviously "wget http://hisham.hm/htop/releases/2.2.0/htop-2.2.0.tar.gz"
-may be simpler on Linux-based systems, but since RBT makes use
-of ruby, functionality such as this has to be included. We want
-to remain flexible and succint whenever that is meaningfully
-possible.
+may be even simpler on Linux-based systems, but since RBT makes
+use of ruby, functionality such as this has to be included. We
+want to remain flexible and succint whenever that is meaningfully
+possible in regards to supporting different use cases for the
+project.
 
 You can also use the current directory as input, e. g. if you
 would first create the directory htop, then cd into it, and
@@ -5668,9 +6190,13 @@ the **bin/rbt** script, such as in the following examples:
     rbt --download ruby
     rbt --download python
     rbt --download php
+    rbt --download m4
+    rbt --download=m4 # This variant works too, if you prefer to use =
 
 This would download **htop**, or **ruby**, or **python**, respectively,
-into the **current working directory**.
+into the **current working directory**. The latter variant, with 
+<b>=</b>, actually downloads into the designated source directory
+so you do not even have to cd into that directory manually before.
 
 Note that the following syntax works as well:
 
@@ -5678,22 +6204,23 @@ Note that the following syntax works as well:
     rbt --download=ruby
     rbt --download=python
 
-Use whatever you prefer here, ' ' or '=' work just fine. I recommend
-to use the '=' all the time since the code checking this is a bit
-simpler. As **argument** you can use any registered program in
-the RBT project - so **over 3600 programs**.
+Use whichever syntax you prefer here; both ' ' or '=' work just fine.
+I recommend to use the '=' all the time since the code checking this is
+a bit simpler. As **argument** you can use any registered program
+in the RBT project - so **over 3600 programs**.
 
 This commandline option thus allows you to quickly **download remote
 source archives**.
 
 If you do not want to type "rbt --download" then you could
-also use **bin/rbt_download**, aka:
+also use **bin/rbt_download** instead, aka:
 
     rbt_download
     rbt_download htop
     rbt_download python
 
-Or put an alias to this to make this even shorter.
+Or put an alias to this to make this even shorter - which is
+exactly why this oddly named executable was added.
 
 If you wish to find out which programs can be downloaded that
 way, you could try to issue this command:
@@ -5701,12 +6228,12 @@ way, you could try to issue this command:
     rbt --show-downloadable-programs
 
 This will display all the names of the registered programs,
-more than 3500 (so it is quite a long output; you may want
+more than 3600 (so it is quite a long output; you may want
 to pipe the output into **more** or **less** on Linux).
 
 You can also download remote programs into the **proper local
-directory**. The "proper" directory is the one where RBT
-expects source archives to reside at.
+directory**. The "<b>proper</b>" directory is the one where
+RBT expects source archives to reside at.
 
 Examples:
 
@@ -5716,9 +6243,9 @@ Examples:
 On my home system, this would download
 http://hisham.hm/htop/releases/2.2.0/htop-2.2.0.tar.gz into
 the local directory **/home/x/src/htop/**. The exact local
-position depends on your SRC_DIR (source directory). See
-elsewhere in this documentation how the source directory
-can be set for the RBT project.
+position depends on your <b>SRC_DIR</b> (source directory).
+See elsewhere in this documentation how the source
+directory can be set for the RBT project.
 
 Do note that since as of April 2019 we can also attempt to
 download different versions of a given program. As an example, let's
@@ -5738,6 +6265,23 @@ should work reliably well, though).
 
 Certain github-based URLs may also not work.
 
+Note that different version may be supported as well,
+such as:
+
+    rbt kernel --version=2.6.30.1 download
+
+This would then attempt to download the linux kernel version
+2.6.30.1. However had, this was last tested a long time ago,
+so it may be easier to stick to the other mentioned
+use cases.
+
+This has an additional chance for failure, such as wehn
+the remote FTP/website changes - so it is no foolproof
+mechanism.
+
+Also note that there is a configuration option which allows
+you to automatically attempt to download a missing file.
+
 ## The method try_to_find_an_alias_to_this_input_unless_the_program_exists()
 
 The method **try_to_find_an_alias_to_this_input_unless_the_program_exists()**
@@ -6196,7 +6740,7 @@ is mostly due to convenience alone.
 To quickly extract into the current working directory, use
 **--extract-here** such as in:
 
-    ry gimp --extract-here
+    rbt gimp --extract-here
 
 This would extract into the current working directory, if the
 archive has been downloaded into the default working directory
@@ -6353,9 +6897,9 @@ a program.
 
 Users of RBT should be able to fully disable coloured output
 at any moment in time. See the section **controlling the
-output of class RBT::Compile**.
+output of class RBT::Installer**.
 
-## Controlling the output of class RBT::Compile
+## Controlling the output of class RBT::Installer
 
 By default, IO.popen() is used to parse the result of
 system-calls, and colourize some of them.
@@ -6497,7 +7041,7 @@ Anyway - **cmake support** is available within the RBT project too,
 to some extent.
 
 If you want to compile specifically via cmake, making use of
-**class RBT::Compile**, then you can use the following instruction
+**class RBT::Installer**, then you can use the following instruction
 on the commandline:
 
     --use-cmake
@@ -6585,10 +7129,13 @@ distinction between a single archive, and multiple archives
 ## class RBT::Cookbooks::MultiUrlDisplayer
 
 **class RBT::Cookbooks::MultiUrlDisplayer** can be used to quickly 
-show several programs on the commandline, provided that they are 
-part of a component, and are registered in the cookbooks.
+show several programs and their associated remote URLs to their
+respective source archive on the commandline. In order for
+this to work, naturally, these have to be part of a component,
+and registered in the cookbooks.
 
-Usage example follows:
+Let's look at a specific usage example to demonstrate this
+functionality:
 
     require 'rbt/cookbooks/multi_url_displayer.rb'
 
@@ -6611,9 +7158,13 @@ Example listing:
     plasmaphonecomponents:       https://download.kde.org/stable/plasma/5.19.4/plasma-phone-components-5.19.4.tar.xz
     kwaylandserver:              https://download.kde.org/stable/plasma/5.19.4/kwayland-server-5.19.4.tar.xz
 
-If you are only interested in the URL entries, on the right
-side, without the leading name, such as when you wish to
-use wget to batch-download this easily, try any of the
+On my computer system the output this will generate is as follows (as an image):
+
+<img src="https://i.imgur.com/vC3Zfyt.png" style="margin: 1em">
+
+If you are only interested in the raw URL entries, on the
+right side, without the leading name, such as when you wish
+to use wget to batch-download this easily, try any of the
 following variants from the commandline:
 
     multi_url_displayer plasma5 --show-only-URLs
@@ -6651,6 +7202,98 @@ was linked to "m", rather than "vte". I kept on having symlinks to
 "m" all the time, which made no sense, until I finally tracked this
 annoying bug down and squished it.
 
+## Compiling several programs in one go (Chain-Compiling)
+
+Compiling several programs one-after-the-other is what the RBT
+tools will refer to as <i>chain-compiling</i>.
+
+It is handled by the ruby script called chain_compile.rb,
+<b class="crimson">class RBT::ChainCompile</b>. The code
+can be found within the file called
+$RBT/utility_scripts/chain_compile.rb
+
+This script allows you to compile several programs in one go, thus
+making your life easier if you need to compile several programs
+quickly.
+
+There are basically <b>two ways</b> to trigger this.
+
+lem 'The first one uses Installer.rb, i.e. the file we aliased to
+`compile` earlier on.
+
+The syntax for this is:
+
+    rbt sdl wrap # This is no longer working. I removed this feature 
+                 # for now. If you need this feature, use "chained sdl"
+                 # instead.
+
+    rbt sdl chained
+
+Because the above idiom may be commonly used, you may omit the 
+last argument if you prepend a <b class="yel">@</b> to the name.'
+
+For example:
+
+    rbt @sdl
+
+In this regard, @ acts as a shortcut for wrap/chained mode.
+
+However, there were a few design problems, and for now this is
+disabled - use "chained sdl" instead. One day I may reenable
+this feature.
+
+The other way uses chained directly. Example:
+
+    chained sdl
+
+Personally I prefer the latter version <cyan>"chained sdl"</>, 
+mostly because I feel it is cleaner to use another command 
+for compiling multiple programs in one go.
+
+In this example <b>chained</b> is aliased to 
+<b>ChainedCompiling.rb</b>.
+
+In later versions I switched to "chained" command instead
+of chained.
+
+Examples with some modular xorg chains follow:
+
+    chained xorg_protos
+    chained xorg_apps
+
+The above commands would compile several xorg related
+ programs.
+
+This is also doable from within rbt itself, as of
+June 2017. Issue this command:
+
+    rbt protos
+
+To find out which chain is used, simply look 
+at the <b>cookbook_chained_programs.yml</b> file.
+
+If you only want to compile a single program from within
+that chain for some reason, you can use specific positions.'
+
+For example:
+
+    chained xorg_apps 3
+
+would compile the third program of xorg_apps. 
+(At the time of this writing, this program would be 
+<b>beforelight</b>)
+
+The default is also to report the size of the tarballs used in
+this chained compilation process - this can be altered via the
+config file. (At March 2009 this was not a very sophisticated
+solution - it needs to be heavily improved.)
+
+The info for compiling several programs at once is written 
+(and can thus be changed) inside 
+<span class="lightblue marl2em">chained_programs.yml</span>'
+
+    cat $RBT_COOKBOOK_DIRECTORY/cookbook_chained_programs.yml
+
 ## Showing the components of a chained compile setup via the commandline
 
 If you wish to quickly see all components that belong to, e. g. the
@@ -6852,14 +7495,13 @@ since I tend to store those .tar.xz files anyway. If you
 don't need it, just disregard that feature and delete
 the file, or re-package as you want it to.
 
-Since as of November 2020 another way exist as well,
+Since as of <b>November 2020</b> another way exist as well,
 a bit shorter than the above:
 
     rbt --git-clone=htop
 
-The difference there is that you simply specify the
-program last, e. g. via the **--git-clone=** 
-commandline switch.
+The difference there is that you simply specify the program
+last, e. g. via the **--git-clone=** commandline switch.
 
 ## Copying all headers to the current working directory
 
@@ -6884,6 +7526,18 @@ variant will only copy .h files that reside in an AppDir-like
 prefix, so it is more likely to fail. It will, however had,
 never pick up any possibly incorrect .h files from **/usr/include/**.
 
+## Glib-schemata
+
+Some programs, such as <b>evince</b>, require a .xml file that is
+installed into a certain directory.
+
+You can enable symlink-action of that .xml file by issuing the
+following command:
+
+    rbt ntrad --use-glib-scheme
+
+Note that this has not been tested extensively though.
+
 ## Determine to which program a particular .h file in /usr/include/ or an executable in /usr/bin/ may belong to
 
 If you ever do want to find out to which program a particular .h
@@ -6955,10 +7609,10 @@ is the rationale as to why that functionality has been added.
 
 **LLVM** offers the **clang compiler**. Compiling most programs should
 be possible via **clang**. The content of the configuration file
-**use_this_compiler.yml** tells RBT::Compile which compiler to
+**use_this_compiler.yml** tells RBT::Installer which compiler to
 favour. If clang is available, and the content of the file
 use_this_compiler.yml is clang, then clang will be used - 
-otherwise RBT::Compile will default to **gcc**, as the latter is
+otherwise RBT::Installer will default to **gcc**, as the latter is
 more commonly used than clang (in 2020 at the least).
 
 The environment variable **RBT_USE_THIS_COMPILER** can overrule 
@@ -7123,77 +7777,121 @@ be given to meson:
 
     --wrap-mode=nodownload
 
-## Deprecations within the RBT project
-
-Over the years, quite a lot of old code was removed or rewritten. As I can
-not keep track of everything mentally, I will use this subsection to note
-down when something was removed.
-
-- In the past, cmake configure options were stored as **configure_options: **
-in the corresponding .yml file. However had, since some time the new
-option **cmake_configure_options: ** exists. For about two years, if
-no such cmake_configure_options was existing, yet cmake was used as
-the build system, then the RBT scripts would assume that the user
-wanted to make use of **configure_options** anyway, so this was used.
+## Licence of this project
 
-In April 2021, though, I decided that it is cleaner to only use
-**cmake_configure_options** and thus deprecate that old behaviour where
-**configure_options** could be substituted.
+Now to some semi-boring legalese, aka the "no warrant disclaimer"
+in particular.
 
-## Licence of this project
+Forst, copyright notice:
 
-Copyright 2021 Robert A. Heiler
+Copyright 2022 Robert A. Heiler
 
 Up until the beginning of **April 2021**, the rbt project was
-using the GPL-2.0 licence (no later clause).
+using the <b>GPL-2.0 licence</b> (no later clause).
 
 In **April 2021**, though, I decided to switch to the **MIT**
-instead for this project. The older GPL code will remain 
-available for some time, most likely at the least a full
-year, perhaps even longer. But the older code is now 
+licence instead for this project. The older GPL code will
+remain available for some time, most likely at the least a
+full year, perhaps even longer. But the older code is now 
 deprecated as far as I am concerned; others would have to
-maintain it. I only focus on the MIT variant now.
+maintain it. I only focus on the MIT variant from this
+point onward.
 
-You can read this licence here:
+You can read up on the MIT licence here:
 
 https://opensource.org/licenses/MIT
 
+To make it even more explicit, let me additionally formulate
+the no-warranty disclaimer:
+
+The source code is <b>provided as is</b>. No explicit
+guarantees are given of any kind whatsoever.
+
+Whenever possible, bugs will be fixed. However had, do
+not expect there to be no bugs in this software suite.
+Chances should be fairly high that it will run on
+your system.
+
 Why was it decided to switch to MIT rather than GPL?
 
 Well, there are several reasons.
 
 First, and most importantly: while I will continue to maintain
 the project here for a long while (I am using it on a daily
-basis), it is not really a project I particular "care" about
-in the sense of wanting to restrict how users use it. It is
-just a ruby gem, not anything I am using for a "mission-critical
+basis after all), it is not really a project I particular "care"
+about in the sense of wanting to restrict how users use it. It
+is just a ruby gem, not anything I am using for a "mission-critical
 project". It also is not important to me in regards to my 
-financial status; nothing against donation by kind people, 
-but I did not create the project for any of that. I created
-the project mostly because I needed to compile software or
-otherwise install software.
+financial status; nothing against donation by interested 
+folks, but I did not create the project for any of that.
+I created the project mostly because I needed to compile
+software or otherwise install software.
 
 Second, though, the GPL is a strict licence. This can be very
-useful - see the Linux Kernel. You also depend less on 
-corporations controlling the software stack, so the GPL has
-very laudable goals. But ... is the GPL really important for
-a project like this one here? I am not sure. I think you can
-already "generate value" if a project is useful, so the 
+useful - see the Linux Kernel. You may also depend less on 
+corporations controlling the whole software stack, so the GPL
+has quite laudable goals. But ... is the GPL really important
+for a project like this one here? I am not sure. I think you
+can already "generate value" if a project is useful, so the 
 licence then is of a secondary concern, in particular when
-it is a smaller project.
+it is a smaller project anyway.
 
 These were my two main reasons. There are a few smaller issues,
-such as the MIT licence being much simpler to use and adhere
-to, but by and large these were the main reasons.
+such as the MIT licence being <b>much</b> simpler to use and
+adhere to, but by and large these were the main reasons.
+
 And if a company ever decides to want to make use of RBT
-then I feel flattered - it means that the project has some
-real value, right? Otherwise people would not use it.
+then I feel flattered, anyway - it means that the project
+has some real value after all, right? Otherwise people
+would not use it.
+
+Be wary of bugs, though; even the MIT licence comes with a
+"no warranty" clause, so always test things first in a
+secure environment (chrooted jail environment, for instance,
+then you can copy or package the compiled packages to 
+wherever you need them(.
+
+While I use this project since over a decade, my use cases
+may not be the same as how other people use the project.
+
+## highest.rb - showing the highest n programs
+
+You can use the file highest.rb to show the largest local
+programs, a Top 50 for instance, by doing:
+
+    rbt --highest
+
+You can specify an argument to it to denote how many
+programs to find. It defaults to 20 programs right now
+if no such argument is supplied.
+
+    rbt --highest=50
+
+## find_alternative_archive.rb
+
+^^^ Use this when you could not find an existing
+    archive first. After this has failed, we can try
+    to check if we have to download a new archive.
+
+## new_cookbook.rb
+
+^^^ Use this when you wish to create a new yaml
+    file.
+
+## scan_source_archive.rb
 
-Be wary of bugs, though; even the MIT comes with a "no
-warranty" clause, so always test things first in a secure
-environment. While I use this project since over a decade,
-my use case may not be the same as how other people use
-the project.
+^^^ Use this when you wish to scan through the
+    local Source archive. This class will report which
+    entries are missing.
+
+## merge_cookbooks.rb
+
+^^^ Use this when you wish to create one big
+    new cookbookfile containing all other entries.
+
+## generate_machomebrew_formula.rb
+
+^^^ Use this to generate a machomebrew formula.
 
 ## GNOME
 
@@ -7328,7 +8026,7 @@ functionality. It is available via:
 
 There is a configuration setting available as part of the **RBT
 project**, called <b>use_ccache</b>. If this is set to yes, aka 
-**enabled*, then the RBT project, in particular **RBT::Compile**,
+**enabled*, then the RBT project, in particular **RBT::Installer**,
 will attempt to **make use of ccache for compilation**.
 
 This **may speed up repeated compilation cycles** of the same
@@ -7493,7 +8191,7 @@ An example for this in regards to meson can be found in the
 file **networkmanager.yml**.
 
 Some of these configure options can be directly passed to an
-instance of class **RBT::Compile** as well.
+instance of class **RBT::Installer** as well.
 
 For example, if you wish to use **--enable-shared** then you can
 simply pass it, like so:
@@ -7675,7 +8373,7 @@ This is why the commandline option **--gibberish** has been
 added in **October 2021**. You can use other names, which
 may make more sense for you, so for example: 
 
-    ry htop --random-extracted-dir
+    rbt htop --random-extracted-dir
 
 This would use a randomly named, extracted directory.
 
@@ -7692,11 +8390,11 @@ into the /usr/ prefix as well as an AppDir prefix.
 Note that this does not yet work 100% perfectly, because
 RBT uses a different variant to compile such programs,
 based on "logic snapshots" - these are individual steps
-that are taken. Right now class RBT::Compile can not
+that are taken. Right now class RBT::Installer can not
 handle them perfectly well. In the future this may all
 be re-organized and work better at one point in time,
 but for now this has to suffice. The whole compile-logic
-behind RBT::Compile became too complex. I will split
+behind RBT::Installer became too complex. I will split
 this up eventually into smaller, logical chunks - perhaps
 even store them into a yaml file.
 
@@ -7773,7 +8471,7 @@ can not be found.
 
 The exact command I used was:
 
-    ry coreutils --static --rootprefix
+    rbt coreutils --static --rootprefix
 
 ## Download the remote documentation from the commandline
 
@@ -7787,7 +8485,7 @@ flag has been added was because the xorg-server may sometimes
 not work but you may want to look at the documentation locally,
 such as via the browser called **lynx**.
 
-## Future Goals
+## Future Goals for the RBT suite
 
 The **RBT project** may not necessarily have truly grand goals,
 such as "changing the world of package managers" - the scope of
@@ -7869,6 +8567,24 @@ In **December 2021** I thought about adding "actions" and
 subsection **Defined actions in the RBT project** for more
 information about this.
 
+The future is hard to predict, but I do have some ideas 
+on my mind. Not everything seems to be possible in pure 
+Ruby, but who knows - maybe we will include some C.
+Perhaps integrate crystal.
+
+I will also include other fancy ideas. Here goes:
+
+- Ability to compile a project without being 
+dependent on hardcoded Makefiles, cmake, or whatever.
+
+- Ability to snapshot these compilations at any time,
+and being able to resume the compile process lateron.
+
+- Ability to generate Makefiles etc... for projects.
+
+- We should realize a generic plugin architecture,
+so that build types like cmake or scons work easily.
+
 ## Installing the Linux Kernel Header files and/or extracting the Linux Kernel archive
 
 The **LFS project** has a step where the kernel headers are
@@ -7901,6 +8617,19 @@ To do this, use:
 
     rbt --install-kernel-headers-into-the-home-dir
 
+## Determining the log directory for the RBT project
+
+The RBT project needs a base directory for log files, that
+is when it attempts to create log files and store these
+in a directory.
+
+If you want to know where the log directory is on your
+given system, then you can ask rbt, using this
+commandline flag:
+
+    rbt rbt_log_dir?
+    rbt --log_dir?
+    
 ## Statistics used by the RBT project in general (and class RBT::CompileStrategies in particular)
 
 The RBT project includes code that is related to **statistics**.
@@ -7963,7 +8692,7 @@ processed.)
 
 The cookbook-submodule of the RBT project also includes some
 statistics, which can be next seen **here**, displayed (and
-stored) in the file called **rbt/doc/cookbook_statistics.md**:
+stored) in the file called **rbt/doc/statistics/cookbook_statistics.md**:
 
 In **April 2021**, the output of class RBT::ShowHowManyFilesAreTracked was
 as follows:
@@ -7978,14 +8707,15 @@ as follows:
 This should give you some overview as to how many files are 
 tracked so far, within the RBT project as-is.
 
-INCLUDE_THIS_FILE doc/cookbook_statistics.md
+INCLUDE_THIS_FILE doc/statistics/cookbook_statistics.md
 
 The number of registered binaries are also kept in a file - 
 specifically look at the file at <b>doc/statistics/n_binaries.md</b>.
-To show only two entries:
+To show only three entries:
 
     On the 30.04.2021 there were 5497 registered binaries.
     On the 12.05.2022 there were 5531 registered binaries.
+    On the 05.02.2023 there were 5651 registered binaries.
 
 These are executables that reside under the **bin/** hierarchy
 of a given program. As you can see, the number of registered
@@ -7994,11 +8724,12 @@ more programs are added.
 
 ## Defined actions in the RBT project
 
-<b>Defined actions</b> are actions that always "stay the same".
-They should be <b>reproducible</b>. They also should not require of
-the user of the RBT project to know the class-name or the 
-file-name (of the .rb file that handles this task) as such
-whatsoever - this is a detail that is not necessary to know.
+<b>Defined actions</b> are actions that <b>always</b>
+"<i>stay the same</i>". They should be <b>reproducible</b>.
+They also should not require of the user of the RBT project
+to know the class-name or the file-name (of the .rb file
+that handles this task) as such whatsoever - this is a
+detail that is not necessary to know.
 
 So, rather than think in terms of classes and .rb files,
 we think of every important part of RBT to be "actionable".
@@ -8052,20 +8783,30 @@ alphabetically:
     :blfs                                    # Show the BLFS entry of the given program. This only works if there is a registered BLFS entry for the given .yml file.
     :build_detector                          # The build detector can be used to determine whether a program uses "configure" or "cmake" or "meson" and so forth.
     :chainer                                 # Chain-compile a series of programs, such as the "KDE5 applications".
+    :chroot_compile                          # Compile into a chrooted environment as prefix-target.
     :colour_make                             # Run "make" in a colourized manner, that is, with colour support.
     :colour_make_install                     # Run "make install" in a colourized manner, that is, with colour support.
+    :compile_in_traditional_manner           # This will compile the passed programs via the /usr/ prefix.
     :compile_into_home_dir                   # This will compile the given program into the HOME directory of the user, e. g. /root/ for the superuser.
     :compile_program                         # Compile a specific program. Symbols exist for shortcuts such as :lfs1.
+    :compile_strategies                      # Give an overview over the available compile-strategies in use.
     :compile_these_programs                  # Compile several programs one after the other, e. g. the batch-variant to the :compile_program action.
+    :compile_the_python_addons               # Compile/Install all registered python add-ons (registered in the RBT suite that is)
     :cookbooks                               # Create a new instance of RBT::Cookbooks::SanitizeCookbook.
     :create_appdir_skeleton                  # Create a new AppDir skeleton structure for the given program.
     :create_cookbook_yaml_file               # Create a new .yml file for the given program.
     :create_log_directory                    # Create a new base log directory for the RBT project.
     :create_pkgconfig_file                   # This action will attempt to create a (pkgconfig) .pc file.
     :create_program_skeleton                 # Create a new AppDir skeleton for the given program. This is the same as ^^^ above, thus just another aliased name for it.
+    :create_programs_version_html_file       # Create a large programs-version .html file. Not that useful for most end users, though.
+    :create_program_version_url_file         # This will create the default .md file containing all URLs, before the rbt gem is uploaded. Not that useful for most end users, though.
+    :create_programs_url_file                # This action will create the programs-URL file e. g. programs_version_url.md.
+    :create_registered_tags                  # Create the registered-tags file. Normal users don't really need this.
     :create_snapcraft_file                   # Create a .snapcraft file for the given program.
+    :custom_toolchain                        # This action will compile as if the user passed the three options '--static --home-dir --do-not-symlink' to RBT::Installer.
     :download                                # Download a specific source archive. Alias "aliased" to :rbt_download.
     :download_all_source_archives            # Download all source archives, e. g. more than 3500 programs. Use only when you need to bootstrap your own local copy of archives.
+    :dual_compile                            # First compile the program at hand via /usr/ prefix, then again via an AppDir prefix.
     :extra_information                       # Show extra information about the given program at hand.
     :extract                                 # Extract a tarball/zip archive to some location.
     :expand_cookbooks                        # This will expand from the short .yml files to the sanitized, longer .yml files, for all cookbooks.
@@ -8074,11 +8815,13 @@ alphabetically:
     :filter_for_valid_program_names          # Try to turn the given input into a required program, such as the input "ph" becoming "php".
     :find_all_archive_types                  # Find all local archives of a specific type, such as ".tar.gz".
     :find_url_for                            # Find the URL for a specific program, such as "htop".
+    :generate_all_slack_desc_files           # Generate all slackware-description files for every registered program.
     :generate_version_file                   # Generate the large programs_version.yml file.
     :highest                                 # Show the "largest" programs, that is, the biggest file archives stored locally.
     :home_dir_without_symlinking             # Compile into the home directory, such as /root/, but do not symlink afterwards.
     :homepage                                # Simply report the homepage of the given argument, e. g. RBT.action(:homepage, 'php').
                                              # :report_the_homepage is an alias to :homepage, by the way.
+    :install_this_rubygem                    # To quickly install a rubygem .gem file
     :libtool                                 # A wrapper over libtool, to try to make libtool suck less.
     :make                                    # A wrapper over "make", primarily done to add colour support when doing "make" on the commandline.
     :make_app_prefix                         # Run "make" but pass an explicit app-dir prefix towards it.
@@ -8091,6 +8834,7 @@ alphabetically:
     :query_file_association                  # This will query to which package a specific file belongs to (if it has been registered).
     :remove_outdated_archives                # This will remove outdated (that is old) archives, if more than one such archive exists locally.
     :remove_symlinks                         # This action will remove all broken symlinks (at the least in the PROGRAMS_DIRECTORY hierarchy).
+    :rename_konsole_tab                      # This action will (try to) rename a konsole tab (that is KDE konsole), which is the terminal I tend to use.
     :report_how_many_binaries_are_registered # Report how many binaries are registered in the RBT project.
     :report_host_cpu                         # Report the host CPU in use, such as "x86_64".
     :report_the_mate_desktop_version         # Report the mate-desktop version, on the commandline.
@@ -8106,12 +8850,17 @@ alphabetically:
     :simple_appdir_configure                 # Compile a program via an app-dir prefix, e. g. /Programs/Htop/1.2.3/.
     :store_abbreviations                     # This will store all abbreviations to the registered program names.
     :suggest_cookbook_for                    # Suggest a cookbook for a specific program, such as "htop".
+    :symlink_into_the_usr_bin_hierarchy      # Symlink the given Array into the /usr/bin/ hierarchy.
     :test_this_alias                         # Test whether the input is an alias to a program, such as "ht" towards "htop".
     :to_current                              # Create a "Current" symlink.
     :toolchain                               # This will attempt to build a standalone toolchain for compilation, similar to what LFS does.
+    :trad                                    # Compile a program in the traditional manner, aka prefix /usr/. The symbol :traditional is an "alias" to this entry point.
+    :uchroot_chompile                        # Compile via user-chroot prefix.
+    :url_action                              # Support instructions such as /install/php/6.3.1, in particular for www-related use cases.
     :update_all_ruby_gems                    # This will update all ruby .gem files that are registered in the RBT project.
     :update_entry                            # Update a specific program-entry, into the corresponding .yml file.
     :update_kde_application                  # Update all KDE applications (kde apps).
+    :update_tags                             # This will update all registered tags.
 
 So, when you want to invoke :update_kde_application then you can simply
 do this:
@@ -8144,6 +8893,47 @@ Note that the above overview does **not** include all available
 actions; some are mostly internal actions that have very little
 value for regular users.
 
+The actions may be a bit verbose and not necessarily easy to
+read compared to a method.
+
+Consider the following:
+
+    RBT.action(:install_this_rubygem, 'path_to_the.gem')
+    RBT.action(:install_this_rubygem, '/tmp/thor-1.2.0.gem')
+
+This would install this rubygem, if it exists locally, e. g.
+the <b>thor</b>-gem.
+
+Now compare this to this toplevel method:
+
+    RBT.install_this_rubygem('/tmp/thor-1.2.0.gem')
+
+The second variant is a bit shorter and easier to read, in
+my opinion. So it is the better variant, yes?
+
+Well, it depends. Brevity is useful, but think about the
+benefit you get via RBT.action(): you can simply call
+one unified method (e. g. action()) to do the required
+action. And we can add lots of aliases to this, to 
+make working with it easier. And you don't have to 
+worry about **where** the code resides - you just
+use the action without a need to do any manual require
+call.
+
+I think if you think this through for a while then you may
+realise that RBT.action() is not such a bad idea - it
+provides <b>actionable</b> entry points to the whole
+RBT suite.
+
+Since as of <b>September 2022</b> all executables that
+are part of the RBT suite, under the bin/ subdirectory,
+are "actionable". That is they are implemented via
+<b>RBT.action()</b> calls. New executables will conform
+to this new default. The only two exceptions are bin/rbt
+and bin/rbt_config - these two will not use RBT.action().
+But who knows - perhaps at some point in time in the
+future they may.
+
 ## Different datasets
 
 The first, raw material for the dataset is a fairly short .yml
@@ -8203,6 +8993,21 @@ instead. But right now this is limited, so
 stay tuned for more updates in this regard
 at a later time.
 
+You can also query the raw dataset from that sqlite
+database quickly. I made sure that we can use
+simple select statemets, such as <b>WHERE
+PROGRAM_VERSION =</b> to quickly query sub-components
+as-is.
+
+The sqlite dataset is currently (August 2022) distributed
+within the rbt gem, to help you bootstrap the project.
+However had, it is quite large (almost 1MB already)
+and since it is generated from the expanded cookbook
+dataset it is not necessary to distribute it. So this
+may change in the future. For now it is the way it
+is, though. If it is changed then the section here
+will be updated as well.
+
 ## Databases and the RBT project
 
 This subsection was created in <b>August 2022</b>. In the
@@ -8228,6 +9033,40 @@ be able to read in the dataset solely from a single
 sqlite database. Stay tuned for more updates in this
 regard in the coming weeks and months.
 
+## RBT.make_app_prefix
+
+This method can be used to create a make command such
+as the following:
+
+    make PREFIX=/home/Programs/Xfce4-panel/4.14.3/ install
+
+In other words: we will automatically use the specified
+PROGRAMS_DIRECTORY entry, and then run the actual
+Makefile, via that "make" command. I was too lazy to
+remember the specific syntax, so this method was added
+to the rbt suite.
+
+## Registering errors during compilation/installation
+
+Some problems and errors may happen during compilation or
+installation of programs.
+
+These are currently handled internally by <b>RBT::Installer</b>,
+but they will also be registered in a toplevel-method
+onto the RBT Namespace.
+
+It is available via the following code:
+
+    RBT.error_message?
+
+Note that this will be reset to nil, its default value,
+whenever a new program is compiled.
+
+The whole error-handling part doesn't work that well
+in RBT. At some point in the future it will be
+rewritten - but first we will collect more errors
+that can occur during compilation.
+
 ## Last updated programs
 
 The following programs were updated with this release,
@@ -8269,16 +9108,908 @@ That way you can use it on your local system easily, if you would
 like to, e. g. to quickly scan for any entry there and
 determine the URL or something like that.
 
-MACRO read_file_as_pre_tag /home/x/programming/ruby/src/rbt/lib/rbt/yaml/programs_version/available_programs_versions.md
+## Makefiles and support for Makefiles in the RBT suite
 
-DONATE_MACRO
+Most open source projects on Linux that require you to compile
+C or C++ code, come with a file called a <b>Makefile</b>.
 
-## Feedback wanted and appreciated
+The command "make" can then be used to interpret the rules
+stored in said file.
 
-Please consider providing feedback about rbt, whether you found
-anything useful in it, whether there are some bugs or other
-problems, and suggestions to improve the project.
+Sometimes no such file is provided, though, and instead,
+some other variant is used, that typically generates such
+a <b>Makefile</b>. For instance, a generic file called
+<b>Makefile.linux</b> can be found, or some other 
+generator.
+
+This file is a <b>template</b> file that can be used to
+generate such a <b>Makefile</b> file.
+
+The common syntax for how to invoke this this would
+be like this:
+
+    make -f Makefile.linux
+
+So you pass the <b>-f</b> flag to <b>make</b>.
+
+However had, the RBT scripts will automatically check
+whether such a file exists, in the event that no Makefile
+exists. If this is indeed the case, then the make command
+will be modified to first create this Makefile. Note
+that this behaviour may be subject to change at some
+point in the future, but for the time being I wanted
+to document this, in case a modification may be 
+necessary.
+
+## How to find out how many programs are registered in the RBT suite
+
+To find out how many programs are registered in the RBT suite,
+do one of the following:
+
+    rbt --n_programs?
+    rbt n_registered?
+    rbt registered?
+    
+It will then feedback something such as:
+
+RBT::ReportTheRegisteredPrograms: 2619 programs are registered
+in our cookbooks as of 30.03.2014.
+
+RBT::ReportTheRegisteredPrograms: 2832 programs are registered
+in our cookbooks as of 18.02.2016.
+
+RBT::ReportTheRegisteredPrograms: 2862 programs are registered
+in our cookbooks as of 18.08.2016.
+
+RBT::ReportTheRegisteredPrograms: 3185 programs are registered
+in the cookbooks as of 06.10.2017.
+
+As can be seen, more and more programs are (slowly) added
+and registered over time. We are now (2022) past over
+3500 programs already. \o/
+
+## View the remote URLs of certain programs
+
+To view the URLs of certain programs, you can do this:
+
+    rinfo
+    rinfo video
+    rbt libxrandr url
+    url libxrandr
+
+Also note that you can set the program name by using 
+USE_URL - we will then use the URL from <b>url1</b>.
+
+The USE_URL is automatically assumed if you only provide
+a remote URL.
+
+## class RBT::Cookbooks::SearchForTags
+
+This class can be used to <b>search for specific
+tags.</b>
+
+## Graphical User Interface (GUI) for the RBT suite
+
+A GUI simplifies interacting with the computer for most
+(regular) users. The RBT suite makes use of some GUIs
+as well.
+
+For the purpose of this subsection we will count the
+www (world wide web) as part of a GUI too, as it is
+quite similar to traditional desktop applications.
+
+In <b>August 2022</b> support for ruby-gtk2 was removed
+from the rbt gem. Only ruby-gtk3 is supported now.
+
+While in theory it would have been possible to maintain
+the ruby-gtk2 bindings, in practice I found that it was
+not worth the extra time spent to do so. ruby-gtk3 is
+simply significantly better than ruby-gtk2 at this point,
+for the most part, in particular the CSS support it brings
+made the GUIs look so much more pleasant. Some of the
+functionality in gtk2 no longer works, which is unfortunate,
+but it is simply a trade-off. We have to "go with the flow"
+and move onto ruby-gtk3.
+
+A few libui widgets exist as well. To start the main one
+you can simply pass --libui such as via:
+
+    rbt --libui
+
+Keep in mind that this could, in theory, change one day.
+
+## How many classes are available in the RBT suite?
+
+This is kept track via the .md file
+called <b>n_classes_in_total_in_this_project.md</b>.
+
+## Displaying the AppDir prefix of a given program via the commandline
+
+Use the following code if you want to know the AppDir
+prefix of a given program:
+
+    require 'rbt/toplevel_methods/configure_appdir_prefix.rb'
+
+    puts RBT.return_appdir_prefix(ARGV)
+    puts RBT.return_appdir_prefix('libssh-0.9.6')
+
+The latter would yield this as a result:
+
+    /home/Programs/Libssh/0.9.6/
+
+## General information about the RBT project via a generated HTML file
+
+The RBT project allows you to also generate some HTML pages,
+similar to how the LFS (<b>Linux from scratch</b>) project.
+
+The central ruby script that does that is called
+<b>central_information_agency.rb</b>.
+
+In order to generate a bunch of HTML pages, do this:
+
+    cia lfs
+
+or
+
+    cia html_pages
+
+## Using / Reusing old configure options
+
+If you wish to re-use very long configure options, such
+as from gcc, then you can use this command:
+
+    rbt gcc --use-this-version=7.1.0 --use-old-configure-options
+
+This will use the configure options from the currently
+installed gcc compile.
+
+## class RBT::ScanSourceArchive
+
+class <b>RBT::ScanSourceArchive</b> will scan through the
+(local) main archive repository and check if a tarball archive
+was encountered that is not registered within the RBT suite.
+
+I use it to make sure that the local copy I keep is "sane"
+and correct. The class could need a rewrite, though - it
+is a fairly old class at this point in time.
+
+## Environment settings and the external gem called environment_information
+
+Sometimes environment settings, stored in ENV as far as ruby itself
+is concerned, may interfere with compilation. For example, assigning
+to the env variable called TZ may cause a build to fail (TZ stands
+for TIMEZONE).
+
+I consider this pretty awful for shells such as bash or zsh, but
+I did not design any of them.
+
+What this means as far as the RBT project is concerned is that we
+may need a way to easily **AVOID** using any ENV variable that may
+be faulty.
+
+The simplest way how to do this may be by not using any ENV variable,
+save for PATH (which has to work, as otherwise the compiler can not
+find anything).
+
+Usage examples:
+
+    rbt nss  --clear-envs ntrad
+    rbt nspr --clear-envs ntrad
+
+This would attempt to compile both nss and nspr without any environment
+variables (save for PATH).
+
+Since as of **December 2018**, a new class called 
+**RBT::CompileViaEnvironmentVariableAsPrefix** can be used to 
+specifically compile into a prefix that is specified via an
+**environment variable**.
+
+This allows me to then use something like this on the commandline:
+
+    env_prefix xfconf
+
+And it will compile the XFCE xfconf component into the prefix 
+specified by the environment variable called XFCE_PREFIX,
+which I happen to have set to a value such as
+**/Programs/Xfce/4.12.0/**.
+
+As we discussed the situation concerning environment-variables,
+at the least to some extent, it should be mentioned that there
+is an external gem called <b>environment_information</b>,
+written by the same (original) author of the RBT project.
+That project is not depending on the rbt gem, but if you have
+both gems installed then you can use the <b>environment_information</b>
+gem to indicate which programs you could install still. I use this
+actually to see whether I have to update some programs on the
+given computer system (on Linux typically). See the commandline
+option <b>--really-everything</b> to obtain that information.
+
+## Batch-downloading all source archives
+
+You can download all registered **source archives** by calling
+**class RBT Cookbooks::DownloadAllSourceArchives**. Warning:
+before you do so, consider that this will really download
+a <b>LOT</b> of source archives - several GB. On my home 
+setup, where I keep all archives in the directory
+<b>/home/x/src/</b>, in <b>September 2022</b>, this reached
+a size of <b>31GB</b>. That's quite a LOT.
+
+I use an alias to call that **.rb** file, if I ever have a use
+case to invoke this functionality. Then I can do, for example,
+on the commandline:
+
+    download_all_source_archives
+
+Alternatively, you can also **invoke the file from the commandline 
+directly, by issuing either one of the following** to 
+<b>bin/rbt</b>:
+
+    rbt --download-all-source-archives
+    rbt --downloadallsourcearchives
+    rbt --grab-source-archives
+    rbt --grabsourcearchives
+    rbt --batch-download-all-source-archives
+
+From within Ruby code, you can use the following **toplevel-API**
+to download all source archives, if you have a use case to 
+support this in any of your ruby files:
+
+    RBT.download_all_source_archives
+
+You can also download only those files that have a certain **tag**
+registered. For example, if you want to download all programs that
+have the tag "plasma" attached (for KDE5), you can issue the
+following command (and argument) for this functionality:
+
+    download_all_source_archives --tags=plasma
+
+In order for this to work, the <b>tag</b> (in this case
+<b>plasma</b> has had to be **registered** (and thus,
+logically, exist). This registration typically happens on
+the individual .yml file, which can then be expanded into
+a SQL database. However had, I primarily work with the yaml
+files, so this is where I make modifications first - see
+the corresponding entry called <b>tags</b> in these
+yaml files.
+
+If you need an <b>overview</b> over the existing tags, issue
+this command:
+
+    rbt --available-tags
+
+## Deprecations within the RBT project
+
+Over the years, quite a lot of old code was removed or rewritten. As I can
+not keep track of everything mentally, I will use this subsection to note
+down when something was removed.
+
+- In the past, cmake configure options were stored as <b>configure_options:</b>
+in the corresponding .yml file. However had, since some time the new
+option <b>cmake_configure_options:</b> exists. For about two years,
+if no such cmake_configure_options was existing, yet cmake was used as
+the build system, then the RBT scripts would assume that the user
+wanted to make use of **configure_options** anyway, so this was used.
+
+In April 2021, though, I decided that it is cleaner to only use
+**cmake_configure_options** and thus deprecate that old behaviour where
+**configure_options** could be substituted.
+
+The constant FILE_SOURCE_DIRECTORY was finally removed in August 2022;
+it was deprecated in May 2020 and commented out. Use the method
+RBT.file_source_directory if you need to find out the file that
+specifies the source directory.    
+
+In <b>September 2022</b> I decided to slowly deprecate class
+<b>RBT::SymlinkFromToCurrent</b>. There is currently a bug in
+this class where it does not symlink into the /usr/bin/
+hierarchy. As that class is a huge mess, rather than spending
+time to fix it, I decided to slowly rewrite its logic step
+by step. First step is to no longer allow it to handle
+<b>bin/</b> and <b>sbin/</b> entries. At a later time it
+may be removed completely.
+
+class RBT::Installer was taken as base to create RBT::Install
+in <b>September 2022</b>. Several old code parts were
+removed. For instance, @internal_hash[:original_input] was
+removed, as well as the two method names input? 
+and original_input?. Both were not really in use. If I ever
+need these again I may look at this deprecation notice here.
+But I am fairly certain that the rewritten code won't need
+this.
+
+## Querying the licence for a program
+
+The file <b>feedback_licenses.rb</b> can help you if
+you want to determine the licence for a program from
+the commandline. It will feedback the known
+(aka registered) licenses.
+
+Usage example where <b>flic</b> is an alias to the
+.rb file:
+
+    flic gpl
+    flic bsd
+
+## Mandating a specific licence on the commandline
+
+<b>Gentoo</b> has an interesting feature through Portage, since
+as of version 2.1.7.
+
+The user can designate a specific mandatory licence to
+be used, on the commandline. If the program at hand does
+NOT fulfil this licence then the program will not be
+installed/compiled.
+
+In other words, <b>the user can accept or reject software installation
+based on its license</b>. The RBT suite added support for
+this in <b>September 2022</b>.
+
+Note that presently many licences are missing in the rbt
+suite - this information has to be added over time. But
+in the long run it is expected that this feature will be
+supported fully, so stay tuned in this regard.
+
+The goal here is to <b>have a pure system in regards to
+licences</b> - or at the least the possibility.
+
+How does this work syntax-wise?
+
+Use any of the alternatives shown below - simply pick
+the one that makes most sense to you:
+
+    rbt php --honour-this-licence=GPLv3
+    rbt php --check-for-licence=GPLv3
+    rbt php --check-licence=GPLv3
+    rbt php --only-this-licence=GPLv3
+    rbt php --only-this-licence=gplv3
+    rbt xfce4panelprofiles --licence=gplv2
+    rbt exo --licence=gplv2
+    rbt exo --licence=gplv3
+    rbt plasmapa --licence=gplv2
+
+Internally this is sanitized and checked by the method
+<b>RBT.sanitize_licence()</b>.
+
+What will happen when you pass the "incorrect" licence?
+
+Consider the following two uses cases:
+
+    rbt exo --licence=gplv2
+    rbt exo --licence=gplv3
+
+Only one of these two would compile. The other one would
+show this error:
+
+    RBT::Installer: The licences do not match. Expected licence
+    RBT::Installer: was: GPLv3, specified licence was: unknown
+
+## class RBT::Installer
+
+This class was added in September 2022 and may eventually replace
+the old class RBT::Installer class. In December 2022 class
+RBT::Compile has been deprecated; class RBT::Installer is now
+the way to go, but RBT::Compile will be available for a somewhat
+longer time. Consider transitioning to RBT::Installer, though.
+
+class RBT::installer has been started from scratch. Note that for the time
+being RBT::Compile will co-exist with RBT::Installer; it may still
+receive bug fixes and other updates. But other than that,
+the code base in RBT::Installer should be better, and it may
+offer a greater functionality than does RBT::Compile - so in
+the long term (future), class RBT::Installer will become
+the new default. It will then be decided whether RBT::Compile
+will be retained or not after that.
+
+Note that RBT::Compile will be maintained for a longer time,
+so two ways to install something will co-exist. In the long
+run RBT::Installer will likely be better, but you may find
+it easier to use RBT::Compile instead for now.
+
+The rewritten class RBT::Installer has integrated various
+improvements. For instance, it is now possible to simply
+ignore compilation errors and other errors - this is
+sometimes necessary, because RBT erroneously reports
+some mistakes that are not real mistakes. The display
+and handling of messages has been improved in general -
+you can now decide to NOT read the extract-archive
+information, which used to be very spammy in the past.
+
+The flag --use-this-program-version is still available,
+but a new syntax has been added:
+
+    installer htop@3.1.2
+
+This may even work with locally existing archives.
+ 
+## The method RBT.filter_for_valid_program_names()
+
+The method <b>RBT.filter_for_valid_program_names()</b> can be
+used to turn short input into a valid program name.
+
+It is best to demonstrate this via an example.
+
+Consider the following code tapping into RBT:
+
+    require 'rbt/toplevel_methods/filter_for_valid_program_names.rb'
+    RBT.filter_for_valid_program_names('libarch')
+
+This would return the string <b>libarchive</b>, which is
+a registered program in RBT.
+
+The remote URL for this program is
+<b>
+https://github.com/libarchive/libarchive/releases/download/v3.6.1/libarchive-3.6.1.tar.xz
+</b>.
+
+Thus, this method can be used by a user to find programs that
+he or she wants to download and subsequently compile.
+
+On the commandline I can then do this:
+
+    rbt libarch
+
+And it will compile libarchive for me. Saves some keystrokes
+thus - mostly it is a convenience feature. (You can also use
+tab-completion, so you could then type <b>rbt libarch</b>
+and hit the TAB key, if you loaded the completions in your
+shell. But this happens before input is sent to RBT itself;
+I wanted to be able to support both the case of tab completion
+as well as the case where the user did not use tab completion,
+for whatever the reason.)
+
+Note that <b>RBT.sanitize_this_program_name</b> is an alias
+to this method.
+
+The method was added because different .rb files in the
+RBT suite may require such abbreviations, so it was
+easier to just bundle all these use cases into a single
+methods.
+
+I am making slow but steady progress with class RBT::Installer.
+For instance, we can now install any different program
+version via the @ special syntax.
+
+Let's explain this.
+
+Say that you have two archives locally,
+glib-2.74.0.tar.xz and glib-2.72.3.tar.xz.
+
+Normally the RBT suite will cater to the most recent
+program version, such as glib-2.74.0, but this is not
+always wanted - sometimes a program does not compile.
+
+So we need a way to specify another program version
+on the commandline.
+
+In the past the following syntax was used, with RBT::Compile:
+
+    rbt glib --use-this-version=2.72.3
+
+But this was quite verbose.
+
+For <b>RBT::Installer</b>, the above syntax will work
+(eventually), but you can also use the @ syntax (which
+already does work, and was one reason why RBT::Installer
+has been written to begin with) like this:
+
+    installer glib@2.72.3
+
+So this will infer the version after the @ part, rather
+than requiring of you to pass it explicitely on the
+commandline.
+
+This is quite convenient and shorter to type than the
+old variant - just compare it. It is so much shorter
+and more succint. Laziness for the win! \o/
+
+## Installing only the headers of a program
+
+You can use this:
+
+    ry gmp --only-headers
+
+This will just copy the .h files into <b>/usr/include/</b>.
+      
+## Build directories
+
+Some progams insist on using a <b>build directory</b> that
+is separate from the directory where the source code is
+kept.
+
+For example, the KDE program called **kirigami2** requires
+an "out-of-source" build directory. I typically use the
+generic name <b>BUILD_DIRECTORY/</b> for such a build directory.
+
+There is a relevant entry in the cookbooks .yml files that
+can be used, called **use_build_directory**. If this entry
+is set to **true** or to **yes** (both are equivalent to 
+one another) then the RBT project will make use of a
+build directory for compiling a particular program. Conversely
+if set to **false** or to **no** - or omitted - then this
+will default to "no, we will not use a build directory 
+for installing/compiling this program.".
+
+You can get an overview over the programs that make
+use of a build directory, by using any of the following
+APIs on the commandline:
+
+    rbt --show-all-programs-that-make-use-of-a-build-directory
+    rbt --all-build-directory
+    rbt --all-build-directories
+    rbt --build-directories?
+    rbt --build-directories
+    Installer --build-directories?
+
+In order for this to work on your system you may have to
+create the expanded cookbook directory (or copy the existing
+expanded directories via <b>rbt --copy-expanded-directories</b>).
+We could use the internally distributed directory since as of
+2021, but for the time being the above approach will still be
+valid as-is. I recommend to simply copy the expanded directories
+after installing the gem, for now.
+
+That still leaves a question of design consideration: if some
+build systems mandate a separate build directory, such as
+meson, how to handle this situation?
+
+Well - there are two basic ways how to go about it here:
+
+(1) One could cd into a separate build directory in
+general, and then require that build systems, such as
+meson, cd back into the original "configure base directory".
+
+(2) Or one could not cd into a separate build directory
+in general, and instead require a separate cd-action
+to change into a build directory.
+
+While (1) is probably the more elegant solution, as it
+leads to less duplication of code, in September 2022
+I decided to pick option (2). Perhaps at a later time
+in the future this may be changed, and then this subsection
+will have to be updated, but for now I wanted to specify
+this behaviour and rationale here, when I was creating
+class RBT::Installer.
+
+## class RBT::CreateLogFile
+
+<b>class RBT::CreateLogFile</b> is going to be used for all
+log-related functionality of the RBT suite eventually.
+
+Right now in <b>September 2022</b> it is only used by class
+<b>RBT::Installer</b>, but in the long run it is expected to
+handle all log-related aspects. The idea is that this
+class can be so flexible as to create all log files,
+including via .yml, that a user may want to look at
+or inspect at some later point in time.
+
+## Java-related code in the RBT project
+
+More Java-related code will be added to the RBT project in
+the coming months and years. These Java-related parts are
+currently not quite complete, not even an early beta. It is
+most likely that one has to handle these parts with more
+care, such as manually downloading source archives before
+invoking the java-related parts. Having said that, though,
+some parts work somewhat: for instance, I can do:
+
+    java BuildTools expat
+
+And on my home system this would mean to work on:
+
+    /home/x/src/expat/expat-2.4.9.tar.xz
+
+At some later point in time I may then turn this 
+into an executable via GraalVM and just do:
+
+    buildtools expat
+
+In the long run, perhaps years from now on, I intend
+to have RBT also work via Java. There should be a 
+noticable speed-up when one combines this with
+GraalVM.
+
+## Binary and Library Checking
+
+You can also compile a program if you only know the name of a
+binary. For example, to compile the package "xine-ui", you could
+supply the name of one of its <span class="yel">binaries</span>, 
+like so:
+
+    rbt xine-check
+
+xine-check is a binary of xine-ui. The above will actually 
+compile <b>xine-ui</b>.
+
+Another example:
+
+    rbt basename
+
+<b class="yel">basename</b> belongs to the package 
+<b>coreutils</b>, and thus we will attempt to compile 
+coreutils.
+
+Note that you can change this in the config file, look
+for the option `check_for_binary_names`.
+
+One last example - say, you know the binary name which is
+called `startx`. You attempt to compile it, and we will set
+it to the proper package name:
+
+    rbt startx
+
+<b>startx</b> belongs to xinit and the above is the same as:
+
+    rbt xinit
+
+And the same mechanism works for library names just as well
+(if they were registered in RegisteredLibaries.yml that is).'
+
+So for instance:
+
+    rbt libqui.so
+
+The above would actually try to compile QT4 and would thus be 
+the same as if you would have entered:
+
+    rbt qt4
+
+In the end, this is just a slight convenience to make your 
+life easier.
+
+The default behaviour for the scripts is to treat the given
+input as alias to a real program name, and if this alias is
+not found we check for binary names, then for library names.
+
+Sometimes, this is not desired.
+ 
+Consider that you input "ld". Now let us also assume that you 
+already have an entry called "ldmud" in your scripts. But "ld" 
+is also the name of the binary "ld" in the binutils package.
+
+To force that we seek for the binary "ld" and not for 
+"ldmud" you could do this:
+
+    rbt ld treat_as_binary_name
+
+Same works for library names as well:
+
+    rbt ld treat_as_library_name
+
+## Gstreamer
+
+If you want to compile all gstreamer components, use:
+
+    rbt --all-of-gstreamer
+
+I added this functionality because I can not offhand
+remember the proper compile order, e. g. gst-plugins-bad,
+gst-plugins-ugly and so forth.
+
+## porg
+
+<b>Porg</b> is a small utility that allows a user to track which files
+are installed by a given program that is compiled from source. RBT
+supports the use of porg through a configuration file, called
+**use_porg.yml**. You can set its content to either true/false,
+or yes/no - these are synonymous to one another. I prefer the
+yes/no nomenclature.
+
+To query from the commandline whether porg is available on the
+given computer system, try:
+
+    rbt --is-porg-available?
+
+If it is not available then you can compile porg of course,
+via:
+
+    rbt porg --trad
+
+The raw command for porg to run the make install step is like this:
+
+    porg -lp htop-2.2.0 "make install"
+
+So, to give you a more specific example, say you compile zlib
+via the rbt gem, like this:
+
+    rbt zlib --ntrad
+
+And you also have porg enabled.
+
+Then you can run the following on the commandline to let
+porg tell you which files were installed:
+
+    porg -f zlib
+
+The output will then be something like this:
+
+    zlib-1.2.13:
+    /home/Programs/Zlib/1.2.13/include/zconf.h
+    /home/Programs/Zlib/1.2.13/include/zlib.h
+    /home/Programs/Zlib/1.2.13/lib/libz.a
+    /home/Programs/Zlib/1.2.13/lib/libz.so
+    /home/Programs/Zlib/1.2.13/lib/libz.so.1
+    /home/Programs/Zlib/1.2.13/lib/libz.so.1.2.13
+    /home/Programs/Zlib/1.2.13/lib/pkgconfig/zlib.pc
+    /home/Programs/Zlib/1.2.13/share/man/man3/zlib.3
+
+Quite convenient to have! \o/
+
+You can read up more about porg here:
+
+https://porg.sourceforge.net/
+
+# Handling errors and problems in regards to the RBT project
+
+## Autocorrecting some errors
+
+The RBT scripts can attempt to auto-correct some errors. This
+is presently in testing. The few errors that RBT can try to
+auto-correct are mostly related to libtool.
+
+If the file use_autofixing.yml contains a String called t or
+true, meaning "enable autofixing", then auto-correcting will
+be used. There is another option that has to be set to true
+though, which is the "is_on_roebe?" settings, which indicates
+my home directory use. Presently (Sep 2017) this option does
+not work too reliably, so I am still testing it. You can 
+test it too though if you enable "is_on_roebe".
+
+## Helpful hints when a .h header file is missing
+
+Since as of December 2022 the RBT suite will give information
+to the user as to when a .h header file is missing, and if that
+missing .h header file is (in turn) registered as part of the
+RBT project.
+
+Let's explain this statement via a specific example.
+
+The software called <b>usbutils</b> depends on a header file called
+<b>libusb.h</b>.
+
+This header file (libusb.h) is part of <b>libusb</b>.
+
+So, if the user tries to compile usbutils, but the error reported
+refers to a missing libusb.h file, then the RBT::Installer class will
+inform the user about this situation.
+
+This message may look like this:
+
+    RBT::Installer: You could consider compiling it via:
+
+      rbt libusb
+
+That way the user can then consider compiling this program if
+he would like to.
+
+Before that code was added, if the user got some error about
+a missing .h file, there was no indicator as to what
+was missing. Now, since as of December 2022, the user
+will get this notification <b>if</b> the program is 
+registered in the RBT project.
+
+## class RBT::SimpleAppdirConfigure
+
+class <b>RBT::SimpleAppdirConfigure</b> can be used to quickly
+use the appdir-prefix at hand.
+
+Note that you can also use the following toplevel-method for
+this functionality:
+
+    RBT.simple_appdir_configure # ← simply pass arguments to this method.
+
+## class RBT::Installer
+
+The following subsection will explain the tasks handled by class
+RBT::Installer in more detail, as this is by far the most important
+class of the <b>rbt</b> gem.
+
+### Internals of class RBT::Installer
+
+**class RBT::Installer** is the main class of the RBT project, as it allows
+us to compile or install a program from source. It is, more or less, <b>the
+central entry point to RBT</b> - even though you can invoke the other .rb 
+files directly, RBT::Installer often provides a simpler convenience access
+to the disparate functions of the RBT project. It integrates other 
+classes, sort of like a <b>glue</b>.
+
+This subsection here will explain a few key decisions made, in the long
+run; and will also explain a few internals.
+
+Do not worry if this may be a bit confusing at first - it is meant
+primarily for me, and for others who may want to extend the RBT
+project one day.
+
+The method set_configure_base_directory(), defined in the file **misc.rb**,
+is used to determine the directory where the configure script ought to
+reside. That way we can enter a separate build directory yet still be
+able to invoke configure (or cmake) at the right directory target.
+
+### Commandline options for class RBT::Installer
+
+As was already written down somewhere else in this document, you
+can pass in several commandline options to class RBT::Installer.
+
+You can also use commandline options that include 
+<b>--</b> and these options can overrule other
+configure options, on an ad-hoc basis.
+
+For instance, let's assume that the configure options in a
+given yaml file, such as <b>weechat.yml</b>, include an
+option such as <b>--enable-gtk</b>. But you don't want
+any GTK GUI for Weechat. So either you modify the .yml
+file, or you decide to override this flag, on the
+commandline, by doing:
+
+    rbt weechat --disable-gtk
+
+This will now overrule the setting in the weechat.yml
+file for the given compilation run, and compile
+weechat with gtk <b>disabled</b>. That way you can
+leave weechat.yml unmodified, yet you are still
+able to get the desired change. (For a permanent
+change you would have to modify the .yml file of
+course.)
+
+If you want to get a quick overview, issue:
+
+    rbt --overview
+
+This should give a brief overview over
+the available utility scripts.
+
+### class RBT::Installer - the commandline option --compile-the-first-entry-in-the-current-working-directory
+
+On my computer system I have done the following alias:
+
+    this → rbt --compile-the-first-entry-in-the-current-working-directory
+
+So, I can then navigate to a directory containing a source archive
+that can be compiled. Then I type "this" and hit enter. RBT::Installer
+will proceed to compile the first entry of this directory.
+
+This allows me to be lazy and efficient. I will simply compile the first
+entry in any given directory, without having to type the name or even
+write the beginning of the name and use '*' as substitution character,
+such as via:
+
+    rbt php*.xz
+    rbt php*.xz
+
+I recommend that users of the rbt gem also use an alias such as "this",
+but of course this is up to them, not me. For me, personally, just
+typing "this" is very convenient should I need it.
+
+## Pseudo Macros in use
+
+Some Pseudo-Macros are used in the RBT Project - at the least in
+the past.
+
+This section here details them:
+
+    PROGRAM_NAME    # Will be replaced with the name of
+                    # the program, for instance: "htop"
+    PROGRAM_VERSION # Will be replaced with the actual
+                    # version of the program, example: "1.0.0"
+
+MACRO read_file_as_pre_tag /home/x/programming/ruby/src/rbt/doc/statistics/n_classes_in_total_in_this_project.md
+
+## Available programs versions
+
+MACRO read_file_as_pre_tag /home/x/programming/ruby/src/rbt/lib/rbt/yaml/programs_version/available_programs_versions.md
+
+DONATE_MACRO
+
+## Feedback wanted and appreciated, as well as contributions to the RBT project
+
+Please consider providing <b>feedback</b> about rbt, whether you
+found anything useful in it, whether there are some bugs or other
+problems, and suggestions to improve the project.
+
+Especially appreciated are new ideas about new
+or missing features and functionality.
 
-ADD_EMAIL
+Code contribution of all sorts are also desired. Please try
+to adhere to the coding standard(s) though - at the least 
+document new code extensively.
 
 ADD_CONTACT_INFORMATION