environment_information 1.4.29

data/doc/README.gen

@@ -0,0 +1,893 @@
+ADD_RUBY_BADGE
+
+## About the environment_information gem
+
+This project is called **EnvironmentInformation** (**environment information**).
+
+Its primary goal is **to gather information about the environment that ruby is
+presently running on** - in other words, **the host system** and its
+capabilities.
+
+This gathered information can then be shown to the user on the commandline,
+or via a ruby-gtk widget, or via a sinatra-interface on the www. The main focus
+for this project is on the **commandline-usage**, though. For example, the
+file at **bin/fenvi**, which is part of this project, can be used to
+quickly show all versions of different programs on the target computer
+system.
+
+To provide a short overview how this may look, taken on the **KDE konsole**
+and **bash**, have a look at the following image:
+
+![alt text][screenshot1]
+[screenshot1]: https://i.imgur.com/KiXIIVV.png
+
+Invocation example:
+
+    fenvi
+
+Generated output (only showing the first five entries):
+
+    atk       2.32.0      
+    bash      5.0.0       
+    binutils  2.32        
+    bison     3.4.1       
+    bzip2     1.0.8
+
+Do note that by default **colours** will be used, so atk may appear
+in green, and the associated version will be shown in a blue 
+colour (actually steelblue, by default). If you do not want to use
+colours, you can disable them for the current invocation run, like
+in this way:
+
+    envi --no-colours
+    envi --no-colors
+    envi --disable-colours
+    envi --disable-colors
+
+Take note that you can tweak most of the behaviour of **EnvironmentInformation**
+via specific **commandline flags**.
+
+To obtain **a listing of the available options**, you can invoke the
+main executable called **envi** (**bin/envi**) via:
+
+    envi --help
+
+What is meant with the term **environment**?
+
+**Definition**:
+
+The term **environment**, within the context of the **environment_information gem**,
+is **the (software) environment** that can be discovered by the ruby version
+found within the **$PATH** variable, on the given computer system at hand.
+
+Recall that there may be situations where there is more than one
+version of ruby installed, on a given computer system, in different
+locations - e. g. **/usr/bin/** versus **/usr/local/bin/**
+versus **/home/**  or **/opt/** setups. Thus, $PATH should be kept in mind in
+the event that you have multiple ruby versions on the given computer system
+at hand, as the incorrect ruby version may be discovered, in certain
+situations. Furthermore keep also in mind that multiple binaries may exist
+at the target system, e. g. bzip at /bin but also at /usr/bin or elsewhere.
+
+Thus, I recommend to always ensure that **$PATH** is correctly set on the
+target machine. First come, first serve, so it is a good advice to keep
+PATH clean, and 'logical'.
+
+At any rate, the **information** that will be gathered by the
+**EnvironmentInformation** project may also be stored more persistently
+in a **standalone .html file**, if you so desire to. This .html file
+could then be used for static display of the information (but may
+become quickly outdated, so keep this in mind as well).
+
+The **Environment information** project may include any of the
+following as its output:
+
+- The **GCC Version** in use on the given computer host system.
+- The (Linux) Kernel in use.
+- Which Ruby Version is used.
+- Which Rubygem version is used.
+- The path to the rubygem directory.
+- What the Host CPU Model is (on Linux at the least).
+- What is the the **GTK*+, **GLIB*+ and **gdk-pixbuf** version, respectively.
+- Which **dhcpcd version** is available.
+- What Xorg components are available, such as libX11, libxcm, libxp,
+libxau.
+
+And so on and so forth - and a lot more.
+
+Why are there many **different ways** to query the version of a locally
+installed programs?
+
+The main reason as to why **different ways** have to be supported is because
+different software is installed in different ways, making use of 
+information in, well - different ways.
+
+For example: not every software comes with a **.pc** file, so we can not
+rely on .pc files uniformly for every installed program. Sometines no
+commandline-binary is provided, so the **--version** flag can not be
+used either; and if no .pc file exists for a given program, we may
+have to query the name of the **.so files** (on a linux system),
+and infer the version from that.
+
+The main class in this project is **class EnvironmentInformation**,
+which resides under **module EnvironmentInformation**.
+
+The actual query of the version is done on the toplevel, so for example:
+
+    EnvironmentInformation.gcc?
+
+would display the version of GCC at hand.
+
+The code there will typically try to query .pc files via **pkg**-config,
+but may sometimes try to infer the version from the .so file at hand,
+and sometimes it will try to run the system binary (or an associated
+binary) with a -V or -v or --version flag, and parse that output.
+
+Typically the components that will be displayed, are handled by code
+that resides in the file **display.rb**. The instance variable
+**@display_these_components** keeps track of which components will
+be displayed, so that information about these disparate programs
+and components can be tracked.
+
+There are in general only two entries that are of interest to 
+class EnvironmentInformation here:
+
+    (a) The name of the program.
+    (b) The associated specific program version, as String, of that program.
+
+So, for example, we may see a key→value association like:
+
+    ruby => 2.5.1
+
+If you need a **String** representation of the dataset then you can
+use the method <b>.string?</b> or <b>.stringified</b>, which will give
+you a **String** instead. The **.stringified** method exists
+primarily due to **convenience** alone, for people who don't
+want to do much conversion on their own and just be done with it).
+
+There are various additional helper methods, such as a reader-method
+called <b>.main_string?</b> or <b>.string</b> (they are equivalent to
+one another, aka one is an alias).
+
+This should allow you to re-use the information from this gem in
+other projects, such as if you wish to get the String of all
+available programs, and display this on a webpage. Or, alternatively,
+just use a toplevel method call, such as:
+
+    EnvironmentInformation.glibc_version?
+
+## How to make use of the project
+
+There are, essentially, three recommended ways how to use the main
+class of this project:
+
+(1)
+
+From the commandline, just call **envi** directly and pass in
+specific commands to this executable (optionally).
+
+For instance: invoke the envi-executable with the argument "ALL"
+or "--all" and the class will show all information that could
+be found. This is personally my favourite way how to invoke
+this class. I even combine it with "FALL" or "RALL" (**--really-all**
+or **--really-everything**), which will also compare the programs
+versions that are available, if the RBT project is available
+(**gem install rbt**), and then inform me as to which programs
+are **not** up-to-date on the local computer system at hand. This
+then allows me to compile/install these programs. This idea came
+to be because I liked the Linux from Scratch project a lot, and
+there you may often have to upgrade programs.
+
+Note that **--really-everything** may be hard to type. I suggest to
+use an alias in that case, or just the upcased variant **FALL** or
+**RALL**. See the file <b>menu.rb</b> for more aliases to that.
+
+(2)
+
+The other use case is the "embedded use", i.e. for use in a
+<b>.cgi page</b> or perhaps for a ruby-on-rails webpage.
+
+An example for the former follows:
+
+    _ = EnvironmentInformation.new(:do_not_run_yet) # The symbol allows us to prepare the class first.
+    _.set_n_tokens 58
+    _.disable_colours # <- Recommended, since the colours are thought for the commandline only.
+    _.be_silent
+    _.dont_show_ruby_stuff # <- If you do not need information about ruby.
+    _.run
+
+But you do not have to instantiate a new object; you can
+simply use another toplevel API, since as of September 2019.
+
+(3)
+
+For example, to query the glibc version, you could use this:
+
+    EnvironmentInformation.glibc? # => "2.29"
+
+Which variant to prefer? This depends on your use case. If you
+need more flexibility then you should use the class; if you
+only need the version-string, number 3 may be best as it is
+the simplest.
+
+You can also display some additional information, such as the version
+of GTK, Glib, Atk and Pango, by passing in "f" or "full" or "--full"
+on the commandline, without the quotation marks.
+
+See the help section to this this script, which can be invoked by
+passing "help" or "--help" as argument to envi.
+
+You can also pass this information through a block, if you would like to:
+
+    _ = EnvironmentInformation.new(:do_not_run_yet) {
+      n_tokens: 58,
+      use_colours: no,
+      be_silent: true
+      show_ruby_stuff: no
+    }
+    _.run
+
+Do note that the following **API** also works, primarily due to 
+convenience - you can try it in **irb**, of course:
+
+    require 'environment_information'
+
+    EnvironmentInformation[]
+
+The executable version for class EnvironmentInformation is called <b>envi</b>.
+It will reside under **bin/envi** of this gem.
+
+So you can invoke the script by typing "envi" from the commandline,
+without the quotes; if you installed it as a gem into a prefix
+other than /usr, it may be that the bin/ directory resides only
+in that gem, though. Setting an alias may help in this case.
+
+## Colours used by the EnvironmentInformation project
+
+Support for colours is available through the **colours** gem. In theory
+any other colour-related gem could be used as well, but this may require
+someone to write support-code for this, in regards to other gems.
+
+Presently (August 2020) this project only uses the **colours** gem
+(**gem install colours**) though.
+
+You can specifically **disable** the use of colours for the current
+invocation run, from the commandline, via either:
+
+    envi --disable-colours
+    envi --disable-colors
+    envi --nocolours
+    envi --nocolors
+    envi --no-colours
+
+    envi --really-all --disable-colours
+    envi --really-all --disable-colors
+
+    envi --all --disable-colours
+    envi --all --disable-colors
+
+Both UK and US spelling should work fine; use whatever you prefer.
+
+Internally, the **@use_colours** variable is used to determine
+whether colours are to be used. You can query the current
+setting via the following toplevel method:
+
+    EnvironmentInformation.use_colours?
+
+You can also query whether colours are used via **envi* as
+well (the **bin/envi** file):
+
+    envi --use-colours?
+    envi --use-colors?
+
+## fenvi
+
+There is an executable at **bin/fast_envi**, as part of this gem, which
+complements the executable at **bin/envi**. envi is simply an abbreviation
+to "environment information"; and fenvi stands for "fast environment
+information". That is exactly the primary use case for fenvi - it shall
+allow for maximum speed, without "maximal usability". The latter means
+that fenvi will not offer as much customization/flexibility as envi
+does. In fact - the EnvironmentInformation project was rewritten in
+**September 2019** precisely to make the whole project much more
+performant and faster; the old code was too slow, for various reasons.
+(Note: I am using an alias called fenvi that refers to fenvi; the
+official name of the executable **fast_envi** though.)
+
+Nonetheless, **fenvi** also supports some commandline flags.
+
+For example, if you wish to only show the registered xorg components
+and their corresponding versions, then you can issue the following
+flag:
+
+    fenvi --xorg
+
+This would **show all xorg components**.
+
+    fenvi --help
+
+Would show the help options. Right now this is limited to just two
+options (or perhaps a bit more than that in the long run).
+
+Another option is:
+
+    fenvi --compare-to-program-versions
+
+This can be used to quickly compare the program versions of the
+local computer system. Note that this functionality depends on
+the RBT gem:
+
+    gem install rbt
+
+## Determining which programs should be shown on your own
+
+You can decide to only show the version of some programs, via the
+**commandline** specifically.
+
+For example, say that you wish to see only the versions of **ruby**,
+**python** and **perl**, then you could try the following:
+
+    envi --use-these-programs=ruby,python,perl
+
+If you wish to display the local versions of **bash**, **binutils**
+and **bison**, then you can try this:
+
+    envi --use-these-programs=bash,binutils,bison
+
+If you wish to show all components that may be important for
+the LFS (linux from scratch) project then you can use this:
+
+    envi --use-these-programs=bash,binutils,bison,flex,bzip2,coreutils,diffutils,find,awk,gcc,grep,gzip,linux,make,m4,patch,perl,python,sed,tar,texinfo,xz
+
+Since that is a bit annoying to type (it's quite long), you can also
+use the **fake-symbol** :lfs for this instead:
+
+    envi --use-these-programs=:lfs
+
+Or, even simpler than that:
+
+    envi --lfs
+
+In fact, this functionality has been added precisely to 
+avoid using a shell script, such as this one:
+
+http://www.linuxfromscratch.org/lfs/view/development/chapter02/hostreqs.html
+
+The name **fake-symbol** is given because via the commandline
+you can only pass e. g. a String, not a Symbol, as bash does
+not know what a Symbol is. So if a string has a leading :
+then the EnvironmentInformation project will assume that the
+user wanted to convey a **special meaning**.
+
+If you do not wish to save any local file then invoke EnvironmentInformation
+in this way:
+
+    envi --lfs --no-save
+
+If you wish to show the local version of openssl as well, try
+adding this commandline flag:
+
+    envi --openssl
+
+## xorg components
+
+To display the registered **xorg components**, you could use any of
+the following commandline flags:
+
+    envi --xorg-components
+    envi --xorg
+
+Do note that not necessarily every xorg component is registered,
+but most of the xorg-components should be covered by now.
+
+## Reading from a local file
+
+The **EnvironmentInformation project** can read from a **local file**
+containing the programs whose version you would like to show, on the
+commandline.
+
+The commandline invocation goes like this:
+
+    envi --read-from-this-file=/Depot/j/display_these_programs.md
+    envi --file=/Depot/j/display_these_programs.md
+    envi --input-from=/Depot/j/display_these_programs.md
+
+The reason as to why this functionality has been made available
+is so that people can use their own custom input to the main
+class of this gem, if they would like to.
+
+A requirement for this to work is that there is a corresponding
+component that can query the version of a program. I am open for
+suggestions what to add, if anything is missing, as well as 
+including a more generic way to make a query. Either way this
+depends on others to make suggestions.
+
+## Sorting the components alphabetically
+
+You can display the components in an alphabetical manner, if you
+would like to, through this:
+
+    envi --sort-alphabetically
+
+## Sinatra interface
+
+Since as of **May 2019** there is now a small sinatra "interface"
+available.
+
+To start it, try:
+
+    envi --sinatra
+
+In order for this to work, you need to have sinatra installed, such as
+via this way:
+
+    gem install sinatra
+
+or
+
+    gem install sinatra --user-install # into the home directory
+
+It is not a mandatory dependency for this gem, so it is not registered
+to be a hard dependency in the **.gemspec** file.
+
+## The science cluster
+
+There are also a few science-related applications, such as for hmmer
+or relion. To query their versions specifically you can issue:
+
+    envi --science
+
+## Show the URL of every registered program
+
+You can, if you like to, show the remote URLs to the different
+programs, if you have the **RBT project** installed (**gem install rbt**).
+
+Then, you should be able to do the following:
+
+    envi --everything --show-remote-url
+
+This variant will not only display the local programs found,
+but will additionally also show the **remote URLs** on the
+commandline, on the right hand side, to the corresponding
+program at hand.
+
+## Only display the operating system in use
+
+If you are only interested in seeing the operating system, try
+this **commandline flag**:
+
+    envi --os?
+
+## Showing additional programs on an ad-hoc basis
+
+You can also show additional individual components via the **--additional**
+flag, like this:
+
+    envi --additional=php,python,perl
+
+This would display the local versions of the installed programs
+**php**, **python** and **perl**.
+
+Note that since as of **September 2019** you can also add the
+name of the component directly. For example, to show the 
+version of bash, you can invoke envi like this:
+
+    envi --bash
+
+To also show php and python, you can do this:
+
+    envi --bash --php --python
+
+Use whichever variant you prefer - the choices are up to the user.
+
+## Ruby-gtk bindings
+
+A small **gtk-widget** exists, which can be started via either of:
+
+    envi --gui
+    envi --gtk
+
+Note that this requires the **ruby-gtk package**, in particular
+**gtk2**, and possibly also the gem called **gtk_paradise**.
+
+Installing these could be done through the following commandline
+invocations:
+
+    gem install gtk2
+    gem install gtk3
+    gem install gtk_paradise
+
+You may need the "devel" packages (.h files) for this to work.
+
+The **gtk** widget is really just extremely simple, and thus not too
+terribly useful, since it lacks functionality; I only wanted to be
+able to **embed this information** into other ruby-gtk applications.
+At some point in the future, the functionality may be extended - but
+for the time being, it will remain simple. **Simple is beautiful**,
+too.
+
+Presently (September 2019) the gtk-bindings in the
+**environment_information** project only support **ruby-gtk2**,
+but in the future I may switch to **ruby-gtk3** - or at the
+least offer means for the user to decide which variant is
+to be used.
+
+## No changelog entries any longer
+
+In the past, changes to this project were listed specifically, together
+with the date - a short changelog.
+
+However had, most users are probably more interested in the options
+and features that are supported as-is; the features that are available
+right **now**. Seeing every unimportant change made in the long
+forgotten past, is not that useful for most users. Additionally, for
+**small projects**, a changelog is not really that worthwhile to be
+had to begin with.
+
+So, I have abandoned the concept of a changelog for this project. Do
+note that if there is something noteworthy that has been changed, it
+will be mentioned and documented here in this file (**README.md**)
+anyway.
+
+## How to add new components/entries to this project
+
+The file <b>environment_information/constants/array_tracked_components.rb</b>
+keeps track over all available entries.
+
+The method called **return_default_programs_on_a_linux_computer**,
+defined in the file <b>environment_information/base/misc.rb</b>,
+will add all the entries that are, assumingly, useful on a linux
+computer by default.
+
+If you want to change the entries, or add new ones, look there first.
+If you wish to register a new program, you have to add it onto the
+main Array (in the constants.rb file) first.
+
+You will also have to add a method that does the actual **query**
+part for the program version at hand, within the
+<b>environment_information/individual_components/</b> subdirectory.
+
+It may be simplest to just copy one of those .rb files, by giving it
+the same name as the program you wish to see displayed. You will
+then have to **change the content** of that method too, in that
+new file, but this is quite trivial and takes at maximum five
+minutes (for those who have not seen it before; it takes
+significantly less time for those who already know what to change
+there). Entries that come with **pkg-config .pc files** are even
+simpler to add - this is much easier than manually parsing
+**--version** flags.
+
+In the future I may switch to a yaml file rather than hardcode
+the entries in .rb directly, but for the time being, I will stick
+to the method described above.
+
+## Short display variant
+
+If you only wish to quickly view the most important information
+about the local computer system, then you can use the following
+variant:
+
+    envi --short
+
+## Caveats
+
+Note that the **EnvironmentInformation** project has to sometimes guess
+how to obtain the necessary information, in order to determine which
+program is installed. For example, for programs such as **readline**
+there is no trivial way to determine which version is used, to 
+**EnvironmentInformation** will attempt to read the .so files, and
+determine the version from the .so files. This may fail, depending
+on the setup of the host computer.
+
+In general, the two best ways to determine the version of programs
+are via a **--version** flag or simply by using **pkg-config** to
+query the .pc file of the package. But this is not available for
+all programs, so ultimately **EnvironmentInformation** may not 
+display completely accurate information on all given computer
+systems.
+
+## Clearing the old dataset
+
+Via **--clear** on the commandline you can remove all old entries.
+This commandline flag thus resets **class EnvironmentInformation**
+to a totally clean, fresh state. Internally the method .reset() will
+be called on **class EnvironmentInformation**.
+
+This allows you to show only one component, or a few components,
+for example. The following example demonstrates this.
+
+Say that you wish to show **only** **python** and **php**, thus
+two programs only. Then you can use the following flag to achieve
+this, in this order:
+
+    envi --clear --python --php
+
+The order is important because --clear will clear at the moment
+it occurs in **ARGV**, which holds the commandline-arguments
+issued on the commandline by the user.
+
+## Which packages will be checked by default?
+
+The following provides a list of packages that are presently,
+in **October of 2019**, tracked.
+
+In the past I did manually copy/paste the following listing, but
+since as of 15th of October 2019, the list is **autogenerated** via
+a macro.
+
+This listing can be seen in the **file**:
+
+    environment_information/constants/array_tracked_components.rb
+
+These are the following programs:
+
+ADD_ENVIRONMENT_INFORMATION_PROPERLY_FORMATTED_ARRAY
+
+You can also display these programs dynamically, such as through the
+following **API**:
+
+    require 'environment_information'
+
+    pp EnvironmentInformation.tracked_programs?
+
+Note that since as of **March 2019**, environment_information will also attempt
+to find out the installed version for **gmp**, **mpfr** and **mpc**. This
+may fail, though, and will be silently ignored in these cases (at least
+for the time being).
+
+You can use the following method to display a list of all programs
+that are registered, from the commandline:
+
+    envi --registered-components?
+
+This will show every registered (and thus, available) component of this
+project.
+
+As of **February 2020**, this project tracks at the least 105 different
+programs. More entries will be added in the future, but the primary
+focus will be on a **Linux from Scratch** / **Beyond Linux from Scratch**
+setup, so expect those programs that are installed first, to be added
+next, too.
+
+## Querying the components that will be shown
+
+You can query the components that will be shown, by issuing one of
+the following commands:
+
+    envi --show-components?
+    envi --show-components
+
+Note that this works exclusively, meaning that if you use this
+commandline switch, then you will ONLY get a query of the
+components that are available.
+
+## Replaying the information
+
+Normally showing all information when issuing **envi --RALL** can take
+quite some time; on my computer system 18 seconds, before the rewrite
+in February 2020.
+
+The reason as to why it takes that long is mostly because many different
+files have to be queried; their --version flag has to be called or
+their .pc file has to be checked, but most importantly querying data
+from the **RBT project** currently takes way too long. This is not an
+ideal situation, as nobody wants to wait.
+
+Waiting 18 seconds is simply too long, though, but until that part in 
+RBT is improved, I have added a **--replay** functionality for **class
+EnvironmentInformation** (via the commandline).
+
+What this functionality does is to take an available (existing) .yml
+file that holds the information from the last invocation run, and then
+proceeds to display this information on the commandline to the user.
+This will evidently be much faster, since the information has already
+been stored before in a prior run.
+
+This change required that the environment information project will
+also generate a **.yml file** by default.
+
+Note that this functionality is not yet complete; I will extend this
+at a later time (written this part here as of **December 2019**).
+
+You can disable saving into this .yml file via:
+
+    envi --no-yaml-file
+
+To invoke the replay functionality, do:
+
+    envi --replay
+
+## Avoid the creation of local files
+
+By default, the main class in this project may generate a few local
+files. This may not always be wanted, or possible (e. g. in a 
+read-only filesystem), so an option has to exist that disables
+this functionality.
+
+That option is called **--no-save** and can be used like this:
+
+    envi --lfs --no-save
+
+## Using another prefix
+
+By default, the environment_information project will assume that
+the main prefix is / or /usr, respectively. In other words, it
+will assume that, for example, the binary called "bison" will
+reside at /usr/bin/bison. To be more correct, it will make use
+of the PATH environment variable, but for most users this will
+list /usr/bin/ first.
+
+That way "bison --version" should work and be the same as
+"/usr/bin/bison --version".
+
+For pkg-config .pc files, the main target will usually then
+be at /usr/lib/pkgconfig/.
+
+Note that the above is not always a correct assumption. For
+example, the **GoboLinux approach** uses the **/Programs/**
+hierarchy instead (but it also keeps legacy symlinks, so in
+fact GoboLinux works just like any other linux distribution too).
+
+On my home setup, I tend to use /home/Programs/ since some
+time - mostly because I tend to relocate /home/ in general
+or may keep it on a separate partition.
+
+For these latter use cases we require another way to quickly
+list all versions of different programs. On 14.01.2020
+support for this has been (partially) added.
+
+Invoke this like so:
+
+    envi --work-on-programs-directory-only
+
+Note that this would use /home/Programs/ right now, which
+is hardcoded - and thus not flexible.
+
+I am aware of this limitation, so expect more code changes
+in the future to extend this functionality.
+
+One key idea for this is to set up /home/Programs/Toolchain/
+and have that one work reliably to cross-compile different
+architectures, libc libraries and so forth. But for now,
+this subsection is a stub.
+
+## Rationale as to why some programs may work and some may not
+
+Querying the specific version installed on a given computer
+system can be tricky. If a **.pc file** is available (**pkg-config**)
+then querying the version is quite trivial. If a **binary** is
+available then often **--version** or **-V** will work. But
+sometimes there is no binary, and no .pc file either. So what
+to do in such a case?
+
+This is not simple to answer, since it may depend on the
+program at hand.
+
+It may be possible to infer the proper version from the
+library at hand e. g. **/usr/lib/foobar.so.4.8.2**. Here
+we could assume that the version will be 4.8.2, but this
+is not necessarily guaranteed to work, either.
+
+In the past, before the rewrite of this project in **February 2020**,
+the environment_information project had used code that would
+check for such conditions - for example, for **readline**,
+and look for specific .so files under **/usr/lib/** or 
+elsewhere. 
+
+But the resulting code that had to be written for this, was not
+very elegant, and takes about 10-20 lines of code for checking
+this, including fall-backs, for each program that does not
+conform to --version or a .pc file. I am no longer sure whether
+it is worth to add that code, since it also may have to be
+maintained, and is not always perfect nor does it always work,
+depending on the computer system at hand. So, past this point,
+**environment_information** is not doing its best to query the
+version for all programs - it will try pkg-config and
+--version or -V in most cases, and if that fails then
+the environment_information project will assume that the
+program at hand is not installed.
+
+This may be a **false negative**, but to me it appears
+to be better in the long run, in regards to maintainability
+of the whole project. After all one reason for the rewrite
+in 2020 was to simplify the whole project, and this objective
+has been achieved - all the commands are now stored in yaml
+files, and that is so much simpler to handle than the
+corresponding ruby methods that were used before that.
+
+## Adding new entries to EnvironmentInformation
+
+New entries can be added into the following yaml file:
+
+**query_to_use_for_the_individual_components.yml**
+
+The two most commonly used variants there are version,
+for **bin/foo --version* invocations, and pkgconfig,
+for querying pkg-config .pc files. However had, many
+programs make use of different invocation variants,
+don't come with a .pc file, and have no binaries.
+Querying the correct version of such files is difficult
+since there is no standard. This is a reason why the
+code has to handle these cases.
+
+But in principle, adding a new entry is as simple as
+adding a new line into that .yml file (and registering
+that component in a second .yml file).
+
+## The toplevel main hash
+
+EnvironmentInformation tries to store the information that
+it has collected into a **hash**, which can be accessed like
+this quickly:
+
+    EnvironmentInformation.hash?
+
+By default this hash is empty, so you have to fill it up
+first, if you want to do so, via the following method:
+
+    EnvironmentInformation.initialize
+
+    hash = EnvironmentInformation.hash? # ← and here you can query it
+
+The hash can then be used as basis for reporting at a later time,
+or replaying that information via the **--replay** commandline 
+switch to the executable.
+
+## Dependencies of the EnvironmentInformation project
+
+The sole dependency for the **environment_information gem**
+is on the **colours** gem.
+
+Up until the beginning of March 2020, the EnvironmentInformation
+project also depended on the **opn gem**. However had, I
+noticed that in a restricted environment installation of
+gems can be difficult, so I made opn **optional**. If you have
+it installed then EnvironmentInformation will still try to
+make use of the **Opn namespace**; and if it is not installed
+then EnvironmentInformation will simply **skip** Opn completely.
+
+## Rationale behind the different queries
+
+As was already explained, different programs require different
+ways to determine which version is installed. Some projects
+would allow more than one way, such as the --version flag,
+but also querying .pc files. Ruby, for example, supports both
+--version, and comes with a .pc file (if you compiled it from
+source, at the least).
+
+So, which way to choose?
+
+In my opinion, .pc files are better than --version, for
+at the least two reasons:
+
+- The resulting code to handle this is much simpler. .pc
+files are quite uniform, whereas the output of --version
+is very dissimilar between different programs.
+
+- Another reason is that invoking the binary, just to 
+do a --version, is actually more expensive (CPU-wise)
+than it is to query a simple text file, which is 
+essentially what .pc files are. So this is another reason
+in favour of .pc files.
+
+For these reasons, and a few smaller ones, the EnvironmentInformation
+project will try to prefer .pc files whenever that is possible.
+We may retain code that can handle --version calls, though,
+if they need a special way to query.
+
+## Querying all registered pkg-config entries
+
+To show all registered pkg-config entries (with .pc files)
+do this:
+
+    envi --pkgconfig
+
+If you want to obtain an Array of all outdated programs
+on the target computer system, try this method:
+
+    EnvironmentInformation.return_array_of_outdated_programs
+
+You need to have initialized the main hash once, before
+being able to make use of that method.
+
+ADD_CONTACT_INFORMATION