roebe 0.5.147

data/doc/README.gen

@@ -0,0 +1,2942 @@
+ADD_DEFAULT_HEADER
+
+## Introducing the Roebe project
+
+<img src="https://i.imgur.com/DvoF3tH.png" style="margin-left: 1em">
+
+(This image was partially autogenerated using cfdg rules.
+See the project here: https://www.contextfreeart.org/gallery/ )
+
+This project here, the <b>roebe</b> gem, is a fairly chaotic project
+that bundles together code that I may **use on a daily basis**,
+when working on a computer.
+
+It is, thus, primarily **a toolset-project** in the sense that it
+contains code that I can use for everyday tasks. I used to 
+have these .rb files spread out separately, in different directories,
+until I realized that I may need these files on other computer
+systems as well - for example, in an office/work situation, or in
+a university campus, on site. One day I thus decided to bundle
+these different .rb files together into a new project, with the
+toplevel namespace being simply **Roebe**, primarily to give these
+different classses a unified "namespace" (a <b>module</b> in ruby).
+
+Do not expect that the project will have some additional meta-goal
+other than that; it really is just a somewhat random collection of
+different scripts, some of them being more useful than others.
+Most of these ruby files are probably totally useless to other
+people, too.
+
+Some classes deal with opening local files via an editor, or
+opening local URLs via the browser; or deleting empty files
+or directories; symlinking content to other directories, and
+so forth.
+
+Additionally, the Roebe project may serve as **an entry point
+to other gems**, thus tapping into the larger ruby gem
+ecosystem as a whole. This is an important **side-goal**
+for this object, as it is, to word this differently, my
+main "jumping point" for ruby these days. If I need
+specialized functionality, I tend to write some ruby
+code, put it into the roebe project, and then move
+from there.
+
+## Layout and Structure of the roebe project
+
+The **roebe-project** is fairly large. Most code can be found within
+the **classes/** subdirectory and the **toplevel_methods/**
+subdirectory.
+
+Following that, a few classes will be described **below this section** -
+but keep in mind that this is not a "complete" documentation of
+all the available classes. Only some of them will be described in
+this file here (**README.md**).
+
+**Before running any of the code, I recommend to you to have a
+look at the source code of the corresponding .rb file - that way
+you may be able to judge whether the functionality is desired
+by you or whether it may need any modifications.**
+
+Keep in mind that the functionality defaults to my own use case,
+which **may easily differ from your use case**. Some of these
+classes have not been updated in years, so again: have a look
+at the source code before running **any** of these classes, in
+particular for larger classes or classes that remove files or
+directories (you can grep for **delete** and **remove** to 
+find these).
+
+Presently the **roebe-project** has only a **very few external
+dependencies** - but in theory, all external dependencies could be
+removed altogether. I like to make use of some external code,
+though, which is why most .rb files within this project require 
+external .rb files via a **begin/rescue LoadError** clause. If 
+you find a .rb file not doing so, consider this to be a bug - 
+you can report this and I will fix it then.  
+
+The most important external dependency is on the **colours**
+gem, since I make use of colours a **LOT** on the commandline.
+
+## Licence of the project
+
+The **main licence** of the **roebe project** used to be **GPLv2.0** (no
+later option; exactly GPLv2.0) up until **April 2021**.
+
+The **roebe project** also allowed the user to use BSD/MIT licence
+at their own discretion, so it was essentially a "choose whichever
+licence you prefer", at the least in regards to these two licences.
+
+See this list on Wikipedia for the BSD/MIT licences:
+
+https://en.wikipedia.org/wiki/BSD_licenses
+
+In **April 2021** the licence for the roebe project was switched
+to the **MIT licence**.
+
+I do not have any issue with the GPL as such; it is a fine licence
+in and by itself.
+
+However had, the **roebe** project is really just a collection of
+different scripts. It is not necessary to have it GPL-licenced -
+people can just take it and re-use how they want to. It's no
+problem. For core libraries I may choose the GPL, but for the
+**roebe project** it really is not necessary.
+
+The **primary point** of this project is to allow people to use
+the code in any way, shape or form, as far as the project itself
+is concerned. The whole project is really just me randomly putting
+stuff together, lots of which I use on a daily basis, so the
+licence should not get into the way in this regard.
+
+Other projects that I use tend to default to GPLv2, and a very
+few the LGPL variant, in particular when C/C++ code is used. But
+for trivial code, IMO, a less restrictive licence is better
+suited.
+
+## class Roebe::Upcaser
+
+class **Roebe::Upcaser** will upcase all files in a given
+directory (the **first argument** to this class).
+
+The default input to this class comes from the **working directory**
+(aka **Dir.pwd** in ruby parlance), so the simplest way to invoke
+this class by navigating to the desired directory at hand, and then
+invoke this class. Only do so when you are sure to want to 
+**upcase all files in the given directory**, though.
+
+You can also invoke this from the commandline via:
+
+    roebe --upcase_all_files
+
+This will default to the current working directory, so 
+make sure that you cd into the correct directory
+<b>prior</b> to invoking this class.
+
+Since as of September 2018, a .yml file will be stored at
+**/Depot/Temp/Roebe/** denoting a hash of the old files to
+the new files (a mapping). That way you can use ruby to
+"restore" the original files again - just load that
+Hash, .invert it and iterate over it. We will only store
+if we are **on roebe**, though - meaning if a certain
+environment variable is set to 1 (called **IS_ROEBE**).
+
+There are also complementary classes that do similar
+operations. For example, another class downcases all
+extension names - so if you have **.MP3** files, that
+other class can change the extension to **.mp3** instead.
+
+## class Roebe::ReplaceSpaceWithUnderscore
+
+This class can replace a ' ' character with a '_' underscore
+character, in a filename. The filename will be changed too.
+
+So for example, if your local, existing file is called
+"foo bar.md", then this class will turn it into a file
+called "foo_bar.md".
+
+Note that the class actually can replace any character
+and also rename incorrectly formed german umlauts, so
+the name of the class is a slight misnomer. For the time
+being, though (**January 2018**), the name of the class will
+stay how it is.
+
+The reason why this class was originally written was because
+some applications struggle with filenames that include a
+space character. I noticed this when using bash. An alternative
+is to use "" quotes to pad the filename, but I found that
+simply removing all annoying characters is much, much simpler
+in the long run - hence why this class was created, and then
+aliased onto "ething" on my system. ("ething" is "everything"
+and "everything" was an alias to call that class with a 
+certain parameter via the commandline.)
+
+## class Roebe::ConvertEncodingOfThisFile
+
+<b>class Roebe::ConvertEncodingOfThisFile</b> can be used
+to convert the magic comment of the Encoding in a .rb file.
+
+By default it will convert ISO encoding into UTF encoding.
+
+## class Roebe::InteractiveFileCreator
+
+This class can be used to create a file "interactively", that is,
+by just asking a user about the parameters with which to
+create the corresponding files.
+
+This can also be invoked from the commandline, via:
+
+    roebe --interactive
+    roebe --interactive-file-creator
+
+## class Roebe::IsoToUsb
+
+This class can be used to "burn" (more accurately, copy) an .iso
+file to a USB device.
+
+<b>Warning</b>:
+
+The class currently makes a hardcoded assumption. At a later time,
+I may add a **--help option** and more options, but for now, the
+hardcoded approach is to be used, which means that in many
+situations <b>it will not work for you</b>.
+
+I do not recommend anyone to use this before actually looking
+at the code either.
+
+## Batch-install my gems
+
+To batch-install all my gems, this can be done from the commandline:
+
+    Roebe.install_my_gems
+
+It will use <b>setup.rb</b> for now, but this may change in the future.
+
+## Tales from the crypt
+
+I have a local file with my favourite tales-from-the-crypt episode.
+
+I can then download the episodes via:
+
+    tales_from_the_crypt --download
+    tales_from_the_crypt --batch-download
+
+where <b>tales_from_the_crypt</b> is an alias to the respective
+class at hand (<b>roebe/classes/tales_from_the_crypt.rb</b>).
+
+You can also use your own yaml file for this or your own Array.
+
+The yaml file should be simple - I use this schema:
+
+    S06E14:
+     url: https://www.youtube.com/watch?v=O_PtahKvdx0
+     name: 99 & 44/100 Pure Horror
+
+If you want to see where the video-files will be downloaded into,
+invoke the class with the **--directory?** switch:
+
+    tales --directory?
+
+For more options, use the commandline switch **--help**.
+
+The primary use case, though, was to actually **generate a
+playlist**. See the MultimediaParadise project for how I would
+then go on to use this (https://rubygems.org/gems/multimedia_paradise).
+
+## SetAlias
+
+**class SetAlias** allows you - and me - to set certain aliases in
+bash, sort of.
+
+This can also be used to set "exam-aliases", to the numbers 1, 2,
+3, 4 and so forth. The reason I used numbers here is because they
+are so simple to use - I just hit <b>1</b> on the keyboard, then
+hit enter, and that alias is run. Often I used this for **exam
+questions**, e. g. to ask a specific question, wait a bit, then
+reveal the answer to that question. But the use cases are more
+general, e. g. whatever "1" is being aliased to at that moment
+in time.
+
+If you pass the argument <b>exam_topics.md</b> to class SetAlias
+then it will try to read a file called that way, and if found,
+assigns each line in that file towards the numbers 1, 2, 3 and
+so forth. This allows me to quickly change the main aliases in
+use per given (upcoming) exam - but it can also be used for
+non-exam related aliases of course. I just needed this functionality
+so that I can store exam-themes in such a file, across many
+different exams.
+
+## class Roebe::AvailableClasses
+
+This class can count how many classes are registered in any given
+project. It does not work that reliably but it does its basic job
+somewhat ok.
+
+## class Roebe::UmlautConverter
+
+If you ever need to quickly replace all german umlauts in a file with
+non-umlauts, such as ä becoming ae, then you could use this class.
+
+Usage example:
+
+    Roebe::UmlautConverter.new('existing_path_to_the_target_file_goes_in_here')
+
+## Opening files
+
+The subdirectory **roebe/open/** contains code that helps with
+open-related activities - in other words, opening files.
+
+For example, say that you wish to open some .pdf files. You may
+invoke open, which then uses the application that opens .pdf
+files. It will also keep track of all .pdf files that were
+opened this way into a small .yml file, if **is_on_roebe?**
+is set to true. 
+
+## Generating a .gemspec file
+
+**class Roebe::GenerateGemspec** can generate a .gemspec file, a
+template that you can fill in.
+
+I use it usually when I create a new gem. It resides with the
+subdirectory **roebe/classes/generate_gemspec/**.
+
+## Random PS1 variable
+
+**class Roebe::TerminalPS1** can generate a random PS1 prompt,
+that is, the colour. This is tailored mostly to my own use case.
+
+The prompt I use right now is:
+
+    export PS1=$CHOCOLATE'$(pwd)/'$CLOSING_TAG$WHIT
+
+where $CHOCOLATE is the HTML colour **chocolate**. The '$(pwd)/'
+part refers to the current working directory.
+
+## class Roebe::IPaste
+
+**class Roebe::IPaste** can be used to paste the content of the
+xorg-buffer onto the commandline, display it and execute it.
+
+This has been necessary due to another class on the commandline
+called **sco**. This class obtained configure options from a
+.yml file and I needed to paste/invoke it on the commandline,
+so I created that class eventually. Now I just type "ipaste"
+on the commandline, hit enter and the content of the xorg
+buffer is executed onto the terminal. Very convenient!
+
+## class Roebe::FragmentMaker
+
+**class Roebe::FragmentMaker** can be used to create a "fragment"
+that can be used in case/when menu structures.
+
+Give it an input such as:
+
+    --foo-bar
+
+and this class will generate a String that includes this:
+
+    when /^-?-?foo(-|_| )?bar/i
+
+This can then be used to be "inserted" into a case/when menu,
+hence the term **fragment** for this.
+
+I needed this for building commandline-applications, since
+I want to be flexible when it comes to user input.
+
+## Roebe.downcase_all_entries_in_the_current_directory
+
+<b>Roebe.downcase_all_entries_in_the_current_directory</b> can be
+used to downcase all entries (files, directories,
+symlinks etc...) that are given to that method.
+
+By default the content of Dir.pwd, aka the current working
+directory, will be used for input.
+
+Be sure to invoke this **only** when you really, really want that
+functionality!
+
+You can also invoke this from the commandline via a switch, like
+so:
+
+   roebe --downcase-all-entries
+
+## Roebe.generate_locales
+
+If you wish to generate some locales on Linux, you can invoke the
+method **Roebe.generate_locales()**.
+
+## Roebe.generate_protocols
+
+The method **Roebe.generate_protocols()** will generate a file
+called **/etc/protocols**. This file is useful on *nix systems,
+in order to determine some of the core IP addresses.
+
+You should **backup the old file there**, before invoking the
+above method, though.
+
+## Prepending and Appending Strings to files
+
+I sometimes have to prepend or append a string to all files
+in a certain directory - normally the working directory.
+
+For example, I may prepend the string **DONE_** to .pdf files
+that I have finished reading; or the string **_2018W** to
+denote the current year (or another year) in said .pdf file.
+
+Since I wanted to be able to do this on the commandline
+I added two classes to the Roebe namespace in November 2018:
+
+(1) AppendThis
+(2) PrependThis
+
+The main recommended API is the following one:
+
+    Roebe::PrependThis.to('DONE_',  files: :in_the_current_directory)
+    Roebe::AppendThis.to('_2018WS', files: :in_the_current_directory)
+
+(You can first do "include Roebe"; then you do not have to preface the
+class via **Roebe::** anymore.)
+
+The first argument is the String that is to be prepended or appended to the
+files. The second argument is a Symbol, essentially - a shortcut to tell
+these two classes that we will default to the current working directory.
+
+You can also feed in your own array of files, via the setter-method
+**set_modify_these_files()**.
+
+Of course, batch-renaming can easily be done in plain ruby through
+FileUtils.mv(), but I wanted a simple commandline variant as well
+that is at the least a little bit documented, rather than use
+"throwaway" code for this.
+
+## Updating the pciids file
+
+On linux the pciids lists some hardware manufacturers that, for example,
+build certain wlan devices. Sometimes the wlan device may not be 
+recognized by the linux kernel, so the program "update-pciids" can
+be called to download a remote dataset with the various IDs listed.
+That file is a shell script.
+
+Roebe has support for a somewhat similar but reduced functionality
+of the update-pciids functionality. Simply issue the following
+command for this:
+ 
+    roebe --update-pciids
+
+## Radio stations
+
+If you want to get the URL to some radio stations, do:
+
+    roebe --radio-stations
+
+If you only want to know where that .yml file resides,
+do:
+
+    roebe --radio?
+
+Note that this functionality depends on the
+**MultimediaParadise project**, so it will only work if
+you have that project ( gem install multimedia_paradise )
+installed.
+
+I needed this so that I can feed some URLs to **rhythmbox**,
+in order to easily listen to some radio stations.
+
+## Roebe::CreateDesktopFile
+
+class **Roebe::CreateDesktopFile** can be used to create .desktop files.
+These files can be used for auto-starting programs on desktop
+systems such as the mate-desktop or **xfce**.
+
+You can also use this toplevel method if you would like to:
+
+    Roebe.create_desktop_file_for()
+    Roebe.create_desktop_file()
+
+## Disable colour support
+
+If you do not want or need to use the colours-related code,
+then you can disable this at any time via:
+
+    Roebe.disable_colours
+
+You can also require the **roebe-project** without colours
+support, via:
+
+    require 'roebe/no_colours'
+
+## Comparing two files for differences via Roebe::CompareTheseTwoFiles
+
+class **Roebe::CompareTheseTwoFiles** can be used to compare two
+different files quickly. It is a fairly trivial class and will
+only report the first difference found, then exit. (This behaviour
+may change at a later time, but for now this is how it is - 
+January 2019).
+
+Usage example:
+
+    Roebe::CompareTheseTwoFiles.new('foobar1.md', 'foobar2.md')
+    Roebe::CompareTheseTwoFiles.new(:default)
+
+## Unicode support in the roebe project
+
+You can print unicode-symbols, if they have been registered in the roebe
+project, via **bin/print_this_unicode_symbol**.
+
+Example:
+
+    print_this_unicode_symbol snowman
+    print_this_unicode_symbol checkmark
+
+This also works via HTML colours.
+
+Example:
+
+    print_this_unicode_symbol snowman --slateblue
+    print_this_unicode_symbol black_knight --orange
+    print_this_unicode_symbol white_knight*33 --tomato
+
+## Unicode emojis
+
+Some programs, such as ibus, require emojis. Since I was tired
+of manual download, I added this method:
+
+    Roebe.download_emojis
+
+You can invoke it from the commandline as well:
+
+    roebe --download-emoji
+
+Note that this will download into the current working directory,
+so you may have to navigate to the proper directory prior to
+invoking this method; or move the .txt files to an appropriate
+location, such as **/usr/share/unicode/emoji**.
+
+## MenuGenerator (class Roebe::Menu::Generator)
+
+Some menus, such as a fluxbox start menu or a file for
+tabble can be generated - but this presently works only
+on my home setup. I may have to distribute these menu
+files too, but this requires of me to clean them up; I 
+will probably do this at some distant time in the future,
+though.
+
+To try to use it anyway (won't work for the time being):
+
+    require 'roebe/requires/require_menu_generator.rb'
+
+    Roebe::Menu::Generator('fluxbox')
+
+## Downloading OpenSSL certificates (certdata.txt)
+
+To simply download the OpenSSL certificates used by the LFS project,
+aka **certdata.txt**, into the current working directory, issue
+the following command from the commandline:
+
+    roebe --download-certificates
+    roebe --certification # <- or this simpler variant
+
+I needed this because I did not want to have to manually look
+up the URL to this file, and then **wget** download it.
+
+## Installing the rcfiles to a target directory
+
+Usage example:
+
+    roebe --populate-this-directory-with-rcfiles=$CHROOT_TARGET/AUTOGENERATED
+
+## Entering chroot
+
+Since as of November 2019, the roebe project supports some chroot commands.
+
+Right now the use case is limited to LFS builds; in the future this may
+be expanded.
+
+To invoke this, try:
+
+    roebe --chroot
+    roebe --enter-chroot
+
+But keep in mind that this assumes a LFS chroot right now, so it is quite
+useless for most people.
+
+## The hack font and the cascadia font
+
+If you wish to quickly install the font called **Hack** then this might
+work for you:
+
+    roebe --install-the-hack-font
+    roebe --install-hack-font
+    roebe --install-hack
+
+This depends on the namespace **Extracter**, which is made available through
+the **extracter gem** ( **gem install extracter** ).
+
+The use case for this was that I wanted to quickly install the hack font
+on different computer systems.
+
+In December 2019, support for the cascadia font has been added as well.
+
+To install it, do:
+
+    roebe --install-the-cascadia-font
+    roebe --install-cascadia-font
+    roebe --install-cascadia
+    roebe --cascadia
+
+## Download the usb.ids file
+
+Via:
+
+    roebe --usb.ids
+    roebe --install-usb-ids # or use this variant here
+
+you can quickly download the file **usb.ids**. This is important for
+usbutils. I was too lazy to look up the URL, so it was simply added
+to the Roebe project instead.
+
+## Comparing two directories
+
+I sometimes need to compare the content of two directories.
+
+It is possible to compare these via normal \*nix tools, but I wanted
+colour support output as well, so I quickly wrote a class that does
+so, on **02.01.2020**. A bin/ executable interface exists as well,
+called **bin/compare_these_two_directories**.
+
+Invocation example:
+
+    compare_these_two_directories /directory_for_audio1/ /directory_for_audio2/
+    compare_these_two_directories /dir1/ /dir2/
+
+Do note that the order matters, as only the different files
+will be reported based on the **first input argument**. If
+you need the reverse, you'd have to swap the two positions,
+like so:
+
+    compare_these_two_directories /directory_for_audio2/ /directory_for_audio1/
+    compare_these_two_directories /dir2/ /dir1/
+
+## Showing the available users on linux
+
+Do the following:
+
+    require 'roebe/classes/show_available_users.rb'
+
+    Roebe.show_available_users
+
+    # or
+
+    Roebe::ShowAvailableUsers.new
+
+## class SimpleExtractor
+
+This class can be used to quickly extract an archive, such as
+**foobar-1.0.tar.xz**.
+
+Commandline invocation goes via the bin/ file like this:
+
+    simple_extractor foobar-1.0.tar.xz
+
+It can also be used to extract a (local) .gem file.
+
+Either use this:
+
+    gem unpack *.gem
+    gem unpack foobar-1.0.gem
+
+Or, if **gem** itself does not work (such as if you lack support
+for openssl, which exactly happened to me in a restricted
+environment, aka on another computer system), try this:
+
+    require 'roebe/classes/extract_gem_file.rb'
+    Roebe::ExtractGemFile.new(i)
+
+or just:
+
+    simple_extractor *.gem
+    simple_extractor foobar-1.0.gem
+
+Note that this depends on **bin/simple_extractor**, which
+is part of the roebe project, but if you would like to
+just extract any .zip file via **bin/roebe** instead, you
+can do so via this way:
+
+    roebe --extract Variablen.zip
+
+## class Roebe::Run
+
+class <b>Roebe::Run</b> can be used to "run" a file, that is,
+execute it after doing some "pre-processing".
+
+The **main use case** is to compile a .c file or a .cpp file,
+but also a .java file.
+
+For example, say that you have a file called <b>foobar.c</b>.
+
+You may wish to compile it via **gcc**, including flags, but you
+are too lazy to specify them as-is.
+
+So, you insert a special "macro" into that very **.c file**.
+
+Example:
+
+    // run foobar.c SAVE_AS_IS
+
+SAVE_AS_IS is a macro to use "-o foobar" automatically, thus specifying
+the name of the created file. It will automatically be named whatever
+the real name of the .c file at hand is; foobar.c is just an example
+in this case of course.
+
+You can then "run" this file via:
+
+    run foobar.c
+
+(This requires that you have aliased "run" to the ruby file
+<b>run.rb</b>, of course. This is the case on my home setup.)
+
+The compilation will then be equivalent to the following variant
+with gcc:
+
+    gcc foobar.c -o foobar
+
+Additionally, the compiled program at ./foobar will also
+be **executed** aka **run** - hence the name. I just wanted
+to combine "compile and then run" via one command, rather
+than use two separate commands. I am that lazy!
+
+There may be more flags/macros that can be used, but for now, only
+the above is documented. This functionality may be expanded at a
+later time - see the menu-interface for all known macros.
+
+For **.java** files, this class will first run "javac NameOfTheFile.java"
+before running "java NameOfTheFile".
+
+Since as of March 2020, the project will automatically add
+-lm if the .c source code contains the math-library.
+
+## GoogleUrlCleaner
+
+In **April 2020** a new class was added to the Roebe project,
+called **Roebe::GoogleUrlCleaner**.
+
+This class will "clean up" URLs from Google.
+
+For example:
+
+    require 'roebe/classes/google_url_cleaner.rb'
+    Roebe.google_url_cleaner('https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&uact=8&ved=2ahUKEwjcnLmkleHoAhUL7KYKHYg0DwcQFjAAegQIAhAB&url=https%3A%2F%2Fwww.wko.at%2Fservice%2Ffactsheet-corona-kurzarbeit.pdf&usg=AOvVaw3549osY6ZGT_DwFViHgLtB') # =>'https://www.wko.at/service/factsheet-corona-kurzarbeit.pdf'
+
+    Roebe.google_url_cleaner('https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=2&cad=rja&uact=8&ved=2ahUKEwjZte3EleHoAhU-wcQBHa6eAY8QFjABegQIAhAB&url=https%3A%2F%2Fwww.virologie.meduniwien.ac.at%2Ffileadmin%2Fvirologie%2Ffiles%2FEpidemiologie%2F2012%2F1212s.pdf&usg=AOvVaw1DfKV-mPD0uDNlijYHfkvX'') # => 'https://www.virologie.meduniwien.ac.at/fileadmin/virologie/files/Epidemiologie/2012/1212s.pdf'
+
+    Roebe.google_url_cleaner('https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&ved=0CDIQFjAA&url=http%3A%2F%2Fwww.fda.gov%2Fohrms%2Fdockets%2Fac%2F05%2Fslides%2F2005-4144s1_05_Mendelson-HF-NHD%2520Pane.ppt&ei=NOFBUYKHBM-64APKnYGQAw&usg=AFQjCNGka328-0Jym7wOYtJ8pdgGJjLv6Q&sig2=Iq2vS_O3AfCioprk-j_q2w') # => 'http://www.fda.gov/ohrms/dockets/ac/05/slides/2005-4144s1_05_Mendelson-HF-NHD%20Pane.ppt'
+
+This class will sanitize a Google URL and return the real URL.
+
+I needed this functionality because I need to have the direct
+URL sometimes, e. g. when using **wget**. And I do not want
+to depend on google if I do not have to.
+
+Do note that the class may not be complete; some cases may
+not be properly escaped yet. If found, new entries will be
+added to the file called **test/testing_google_url_cleaner.rb**.
+
+## Regexes in Ruby
+
+This section is just a short summary of what I consider useful.
+
+    /[[:alnum:]]/  - Alphabetic and numeric character
+    /[[:alpha:]]/  - Alphabetic character
+    /[[:blank:]]/  - Space or tab
+    /[[:cntrl:]]/  - Control character
+    /[[:digit:]]/  - Digit
+    /[[:graph:]]/  - Non-blank character (excludes spaces, control
+                     characters, and similar)
+    /[[:lower:]]/  - Lowercase alphabetical character
+    /[[:print:]]/  - Like [:graph:], but includes the space character
+    /[[:punct:]]/  - Punctuation character
+    /[[:space:]]/  - Whitespace character
+    /[[:upper:]]/  - Uppercase alphabetical
+    /[[:xdigit:]]/ - Digit allowed in a hexadecimal number 
+
+How can these be used?
+
+Consider the following example, a String stored in the variable
+called x:
+
+    x = "123"
+    x =~ /([[:digit:]]{1,2})/
+    puts $1 # => "12"
+
+As you can see this would be similar to this:
+
+    x =~ /(\d{1,2})/
+
+Obviously the second variant is much shorter. So why use the
+longer variant? That is a good question.
+
+## class Roebe::GenerateNanoConfig and the editor nano
+
+class <b>Roebe::GenerateNanoConfig</b> can be used to 
+generate a configuration file for the editor nano.
+
+You can also display the content that is to be generated
+on the commandline, via:
+
+    generate_nano_config --show-nano-config
+
+This requires that generate_nano_config is aliased to
+the .rb file that holds class <b>Roebe::GenerateNanoConfig</b>.
+
+See also:
+
+    roebe --help
+
+Since as of **July 26th 2019** (26.07.2019) the roebe gem also
+comes with my custom nano-rc files included by default. Nano
+is not related to ruby per se, but I use nano a lot to quickly
+modify local files, so I found it more useful to bundle the
+nano-rc files into the roebe project as well by default.
+
+## VimParadise
+
+In the past there was a separate gem, called **vim_paradise**.
+
+That gem was able to create a .vimrc file, from scratch.
+    
+The idea for **VimParadise** was quite simple: I wanted some
+ruby-code to auto-generate my vimrc settings.
+
+I kept on tweaking my vimrc over the years, and kept on
+making things worse and worse in doing so.
+
+One day I decided it is time to have ruby help me generate
+a vimrc file, hence the VimParadise project was created.
+
+In May 2020 the project was removed as a standalone gem,
+and instead integrated into the **roebe** gem here.
+
+A bin executable exists, called:
+
+    vim_paradise
+
+For useful VIM resources, have a look at the following
+webpages:
+
+http://vim.wikia.com/wiki/Vim_Tips_Wiki
+http://hans.fugal.net/vim/vimrc_hans
+http://vimdoc.sourceforge.net/htmldoc/
+
+## Roebe.browser
+
+This toplevel method is supposedly able to "handle" different
+browsers. Internally it delegates towards **class
+Roebe::Browser**.
+
+In the past, I used to use firefox but lateron switched to
+**palemoon** in **2018**, due to Mozilla's general arrogance
+and refusal to listen to users - which makes it quite 
+pointless to keep on using firefox.
+
+I used to open tabs by default in firefox only, but after
+I switched to palemoon, I needed a general way to open
+tabs via **any** browser - thus the toplevel method
+ <b>Roebe.browser</b> was added.
+
+Which browser is the default is now handled by a .yml
+file, since as of **June 2020**.
+
+You can define which browser is used on your system
+via:
+
+    browser.rb --browser=/usr/bin/firefox
+
+(Where browser.rb is an alias to the actual
+browser.rb file that can be found at
+**roebe/browser/browser.rb**.)
+
+The path to the .yml file on your system can be
+determined via:
+
+    browser.rb file?
+
+## Code related to the KDE project
+
+The **roebe project** has a few classes that are related to the KDE
+project - in particular **KDE konsole**, since that is the main
+terminal I am using most of the time.
+
+The **KDE konsole** is able to display text through various means or
+enhancements if you so will, be it **bold**, ***underline***,
+_italic_ or colours (in RGB format).
+
+For example, say that you wish to display some text in a bold manner,
+in the middle of a sentence, then you could use escape sequences
+such as in the following example:
+
+    echo -e "Normal text \e[1mBold text\e[0m Normal text again"
+
+The **roebe project** comes with a commandline-script called
+**bin/konsole_title**, which can be used to rename the title 
+of a KDE konsole tab. I have aliased this to **rti**, for
+simplicity, on my computer systems.
+
+Thus, when I wish to **rename a tab in the konsole**, I can
+simply do the following:
+
+    rti Hello world!
+
+I use this in particular to automatically rename a KDE konsole tab
+through different scripts - which is very convenient.
+
+**konsole** understands a lot of special commands. For example, if
+you wish to delete the icon that is on the left hand side of a 
+typical konsole tab, you can use this code (e. g. in **bash**):
+
+    echo -ne "\033]32;\007"
+
+Since that can be quite useful, this is also doable through the
+**konsole_title** script, by issuing any of the following
+instructions:
+
+    rti --clear-icons
+    rti --no-icon
+
+You can also show icons that are stored in a "standard" search path.
+
+These icons for use in the KDE konsole tab may typically be found
+in the **16x16 directory**, such as the following one for **oxygen**:
+
+    /usr/share/icons/oxygen/16x16/status/dialog-warning.png
+
+    /usr/share/icons/oxygen/16x16/actions/
+    /usr/share/icons/oxygen/16x16/animations/
+    /usr/share/icons/oxygen/16x16/apps/
+    /usr/share/icons/oxygen/16x16/categories/
+    /usr/share/icons/oxygen/16x16/devices/
+    /usr/share/icons/oxygen/16x16/emblems/
+    /usr/share/icons/oxygen/16x16/emotes/
+    /usr/share/icons/oxygen/16x16/mimetypes/
+    /usr/share/icons/oxygen/16x16/places/
+    /usr/share/icons/oxygen/16x16/special/
+    /usr/share/icons/oxygen/16x16/status/
+
+Have a look there to find out which names will available. Keep in
+mind that these icons will reside in different subdirectories,
+e. g. **status/** or **emotes/**. Support for these icons depend
+on, for example, the oxygen theme, which could be found upstream
+at **https://download.kde.org/stable/plasma/5.15.1/oxygen-5.15.1.tar.xz**
+or a similar URL.
+
+The following **examples** show how to use these dialog warnings
+from **bash** or **zsh** directly, without depending on ruby:
+
+    echo -e "\033]32;dialog-warning\007"
+    echo -e "\033]32;emblem-favorite\007"
+    echo -e "\033]32;emblem-mounted\007"
+    echo -e "\033]32;emblem-important\007"
+    echo -e "\033]32;waiting\007"
+
+Note that you can combine this with regular text, such as in the
+following **Hello world!** example prefaced with the
+**waiting-icon**:
+
+    echo -e "\033]32;waiting\007\e]30;Hello world!\007"
+
+The **roebe gem** supports this too, through **konsole_title**;
+at the least in some **shortcut manner** for some of these
+entries:
+
+    rti --dialog-warning
+    rti --warning
+    rti --emblem-warning
+    rti --emblem-mounted
+    rti --emblem-important
+    rti --waiting
+    rti --face-angel
+    rti --face-embarassed
+    rti --face-kiss
+    rti --face-laugh
+    rti --face-plain
+    rti --face-raspberry
+    rti --face-sad
+    rti --face-smile-big
+    rti --face-smile
+    rti --face-surprise
+    rti --face-uncertain
+    rti --face-wink
+
+There are a LOT more options supported by **konsole_title** - the
+**README** here only lists a few of these options.
+
+For a full listing, have a look at the file called **menu.rb**
+of the respective class.
+
+Take note that you can also use **custom icons** that you have on
+your harddisc:
+
+    echo -e "\033]32;/home/x/DATA/IMG/foobar.png\007"
+
+And keep in mind that these icons are only small, e. g. 16x16,
+so it is not trivial to see what this icon is made up of.
+
+You can also set an image to be used via the commandline:
+
+    rti --image=/path/to/the/image.png
+    rti --use-this-image=/path/to/the/image.png
+
+You can also omit the -- part, aka just use the file path directly:
+
+    rti /path/to/the/image.png
+
+You can also use a random icon (but this requires a prior registration
+of that icon in a CONSTANT Array of that class):
+
+    rti --random-icon
+
+You can also display the default icon, which is the KDE Konsole icon
+(terminal).
+
+    rti --terminal
+
+It may typically be found within the oxygen theme, at a location
+such as:
+
+    /usr/share/icons/oxygen/16x16/apps/utilities-terminal.png
+
+## class Roebe::DownloadFromThisUrl
+
+<b>class Roebe::DownloadFromThisUrl</b> can be used to download **content
+from remote websites**. Simply pass in the URL to the website from where
+you wish to download data from.
+
+In pure ruby code this would look like this:
+
+    require 'roebe/classes/download_from_this_url.rb'
+    Roebe::DownloadFromThisUrl.new(URL_GOES_IN_HERE)
+    Roebe::DownloadFromThisUrl.new('https://archive.xfce.org/xfce/4.16pre1/src/')
+
+I aliased this file towards download_from_this_url, so I can then
+do this on the commandline:
+
+    download_from_this_url https://archive.xfce.org/xfce/4.16pre1/src/
+
+A **filter** may be used to denote which files are to be downloaded. As
+of July 2018, the filter I use is mostly to download only .pdf and .txt
+files. In September 2020, support for .tar.gz, .tar.bz2 and .tar.xz
+was added as well. For now this is a hardcoded array - in the future I 
+may add options to specify omitting a filter from the commandline and 
+so forth; but for the time being, it will remain as it is since I 
+mostly wrote it only in a day to be able to batch-download some 
+remote files that I needed to finish a given task.
+
+In September 2020, the code was slightly adapted.
+
+To disable the use of a filter, use **--no-filter**, like so:
+
+   download_from_this_url https://archive.xfce.org/xfce/4.16pre1/src/ --no-filter 
+
+Note that in the long run, the class may have to be rewritten, in
+order to support different behaviour. But again, I wrote it mostly
+quickly to finish a job, and then move on.
+
+## class Roebe::BurnISO
+
+This class can be used to burn an .iso file onto a DVD, if
+**growisofs** is available.
+
+Usage example:
+
+    require 'roebe/classes/burn_iso/burn_iso.rb'
+
+    Roebe::BurnISO.new('foobar.iso')
+
+## class Roebe::GrubConfigGenerator
+
+Since as of **November 2020**, class Roebe::GrubConfigGenerator
+can be used to generate a new grub configuration file, typically 
+called **grub.cfg**.
+
+I needed this because I got tired of manually having to
+specify stuff for grub2 to work.
+
+Usage example from ruby:
+
+    require 'roebe/classes/grub/grub_config_generator.rb'
+
+    Roebe::GrubConfigGenerator.new(ARGV)
+
+## class Roebe::Identical
+
+If you want to compare two strings to one another, how
+**identical** they are to one another, then class
+**Roebe::Identical** may be of help here.
+
+A usage example follows:
+
+    require 'roebe/classes/identical.rb'
+
+    Roebe::Identical.new("string1", "string2")
+
+This would return a number such as 86, which is the
+**percentage of the identity** at hand. In this example,
+only one character was different (the "1" versus 
+"2", respectively).
+
+Alternatively, you can just use the <b>module-level method</b>
+<b>Roebe.identical()</b>:
+
+    Roebe.identical("string1", "string2")
+
+Since as of November 2020, you can use this on the
+commandline as well. Example:
+
+    roebe --compare-strings=string1,string2
+
+## The .Xresources file
+
+This is not about ruby, but simply because I need some useful
+shells when I work on linux, before I can write ruby scripts.
+
+To enable tabs in rxvt-unicode use:
+
+    URxvt.perl-ext-common: tabbed
+
+Don't forget to have compiled perl support via --enable-perl prior
+to that. I forgot that in **2021** and could not figure out why
+the guides on the www did not work. :)
+
+To start a new tab:
+
+    Shift+Down
+
+To close the active tab:
+
+    Ctrl+d 
+
+Specify the colours of tabs via:
+
+    URxvt.tabbed.tabbar-fg: 2
+    URxvt.tabbed.tabbar-bg: 0
+    URxvt.tabbed.tab-fg:    3
+    URxvt.tabbed.tab-bg:    0
+
+This would make the tab colour green.
+
+urxvt-tabbedex can be used to rename tabs. 
+
+To be able to resize the fonts on the fly,
+add:
+
+    URxvt.perl-ext-common: resize-font
+
+Pretty looking font:
+
+    URxvt.font:     xft:bitstream vera sans mono:size=18:antialias=true
+    URxvt.boldFont: xft:bitstream vera sans mono:bold:size=18:antialias=true
+
+    URxvt*color0:  #000000 // black
+    URxvt*color1:  #B40000 // red
+    URxvt*color2:  #00AA00 // green
+    URxvt*color3:  #AAAA00 // yellow
+    URxvt*color4:  #5555AA // blue
+    URxvt*color5:  #AA00AA // magenta
+    URxvt*color6:  #00AAAA // cyan
+    URxvt*color7:  #AAAAAA // white
+    URxvt*color8:  #555555 // black (now and below: bright)
+    URxvt*color9:  #FF0000 // red
+    URxvt*color10: #00FF00 // green
+    URxvt*color11: #FFFF00 // yellow
+    URxvt*color12: #6464FF // blue
+    URxvt*color13: #FF00FF // magenta
+    URxvt*color14: #00FFFF // cyan
+    URxvt*color15: #FFFFFF // white
+
+## The www-stack and bundled documentation about linux (in german)
+
+In **November 2020** I decided to slowly put all my local knowledge
+base in regards about linux into the roebe-project.
+
+This may not be very useful for other people, as most of that 
+documentation is written in german; but some linux commands may
+still be useful to know.
+
+The primary reason why this is done is, though, because I sometimes
+needed this information on another computer system, in order to fix
+a given problem - in particular when ruby is **not YET** available
+on that computer. When ruby is available then I can use ruby to
+(auto)solve many problems.
+
+There are secondary reasons as to why I decided to include the
+documentation there, though. One of that secondary reason is that
+some of that documentation is almost 20 years old by now, so this
+gives me an opportunity to improve and polish on the information
+content. In some ways this is a bit like a "wiki", just that I am
+the only one editing that "wiki" right now. :P
+
+Let's see what happens with this approach in the future.
+
+Note that, unfortunately, the images I use here for the www-stack
+are **NOT** included in this gem. There are two reasons for this:
+
+a) the smaller one is that a few of these images may be copyrighted,
+so I avoid any possible problems by simply not bundling them.
+
+b) the much bigger issue, though, is convenience, or lack of
+convenience. If all images would be bundled, the size of the
+gem would be above 50 MB, which is just way too much. If you
+need images, well, think about it appropriately - for example,
+a page about statistics may include some images that show
+statistical data being visually represented. Just google for
+this and you find adequate images for that; you could then
+just use these and nobody would notice a huge difference
+really. :D
+
+## Ruby awesome bits, oddities and ugly bits - including the safe navigation operator (and a bit of Crystal code)
+
+This **subsection** may collect a few ruby snippets that may be **odd** -
+or **awesome**; and also some that may be **ugly**.
+
+Consider the following code in the ruby **2.5.1** days:
+
+    #!/usr/bin/ruby -w
+    # Encoding: UTF-8
+    # frozen_string_literal: true
+    # =========================================================================== #
+    def foobar(
+        i = ' hello world'
+      )"15.10.2018"
+      puts i
+    end
+
+    foobar
+
+Notice the weird "15.10.2018" part? That is actually ignored. But only in a line
+that has a ')' and ends a method, obviously. If you put that same string right
+next to the <b>end</b> keyword then a syntax error will be the outcome.
+
+I found that strange because the ruby parser treats strings differently depending
+on the context at hand.
+
+On second thought, I think this is actually valid behaviour, since it is just
+a string literal that is not used. 
+
+Another example that I have found interesting is **RSpec**.
+
+Take code such as the following one:
+
+    expect(Dir.exist?('doc')).to be true
+
+That surprised me. I am not entirely sure what the above entails to, but I
+think this is actually:
+
+    expect(Dir.exist?('doc')).to(be(true))
+
+That means that ruby's flexibility sort of allows you to just **omit**
+the (), with the end result that an interesting **DSL** is created. It
+is not my own personal preference, but I think it is still interesting
+nonetheless. You can not do this in python because () are required
+rather than optional.
+
+This subsection is just a bit documentation about the **safe navigation
+operator** in Ruby.
+
+Code will typically look like this:
+
+    object&.method
+
+I personally do not like the & there and actively avoid the
+safe navigation operator. A reason is that I find it to be
+very ugly.
+
+Having said that, though, I have, in 2018, found an interesting
+example here:
+
+    https://github.com/ruby/ruby/commit/91fc0a91037c08d56a43e852318982c9035e1c99
+
+The old code was:
+
+    f.close if f && !f.closed?
+
+The new code is:
+
+    f&.close
+
+This was interesting to me because the safe navigation code is
+much shorter than the old code. Not that I find the "if f"
+and "&&" and "!f.closed?" parts to be very elegant, either - but I
+think this may actually be a case where the safe navigation code,
+while really ugly, led to a better code layout. Still won't convince
+me to use it, but if we compare situations then we ought to compare
+all advantages and disadvantages rather than just a few select
+examples. We should keep both situations in mind.
+
+Interestingly enough, Crystal appears to have copied the &.
+operator:
+
+    class Object
+      def has_instance_var?(name) : Bool
+        {{ @type.instance_vars.map &.name.stringify }}.includes? name
+      end
+    end
+
+It looks very strange to my eyes, the **&.name.stringify** part. Can't
+say that I think this is awesome, either in ruby or crystal, really.
+
+However had, on second thought, the above code in crystal may perhaps
+be similar to &: in ruby instead.
+
+For example:
+
+    %w( 1 2 3 ).map(&:to_s) # => ["1", "2", "3"]
+
+I have no idea why crystal uses a '.' after the & in this case,
+though. And what the hell is **.stringify**, anyway? Does this
+mean to want to turn something into a String? Why is it named
+"stringify"? Who came up with this?
+
+In September 2018 I have found another example for &, a very
+ugly one:
+
+https://github.com/ruby/ruby/blob/trunk/test/ruby/test_thread.rb#L191
+
+The code is as follows:
+
+    t1&.kill&.join
+
+It's quite disgusting combining the use of & twice really. It is
+not just twice as bad as a single &; it actually is about three
+times as bad.
+
+In October 2019, ruby added the <b>...</b> as an experimental
+feature.
+
+Code may look like this:
+
+    def foo(...)
+      bar(...)
+    end
+
+Now I should say that I think the functionality itself is fine. But
+seriously? ... ? That's like someone having a mental lapse here.
+
+I don't like the syntax at all - and, to be brutally honest, in the
+last 3-5 years, ruby has added too much horrible syntax. I can't see
+how adding new syntax for the sake of it OR adding it when the feature
+in itself will be of limited used, is a good thing.
+
+In some ways this is irrelevant because I'll defend my code base 
+against these insanities - but it's getting increasingly annoying
+to see how ruby is morphed about willy-nilly randomly. I have no
+idea what is going on there.
+
+Unfortunately switching from ruby is not an option either, because
+the other languages suck even more. That is a strange dilemma
+here ... :P
+
+The only good thing is that I can avoid crap syntax. I do not think
+I would use ruby if there would be a force to change how I have used
+it for +15 years into a crap syntax though. One has to be attentive
+of what crap syntax the future may bring here.
+
+Note that this is really about the syntax, NOT the feature. The
+feature is ok, IMO; it is similar to "alias" or "alias_method",
+just with a bit more fine-tuned control.
+
+Ruby allows you to make use of keyword arguments. The syntax can
+be a bit confusing, though.
+
+For example:
+
+    def movie(title:, lang: lang = 'English')
+
+This makes use of keyword arguments as well as specify default
+arguments. When I first saw this this was a bit confusing
+since lang is repeated, thus appearing twice.
+
+Remember that this means that :title is mandatory.
+
+If you invoke it like this:
+
+    movie lang: 'german'
+
+Then a **missing keyword: :title (ArgumentError)** error will
+be shown.
+
+## class Roebe::UnicodeSnowman
+
+This class will show a unicode-snowman on the commandline.
+
+Keep in mind that you can colourize unicode-output on the commandline as
+well, via the RGB functionality of e. g. the <b>colours</b> gem. This
+allows you to colourize the snowman - or any Unicode token, anyway.
+
+If you want to **display the snowman on the commandline**, you can do so
+via:
+
+    roebe --snowman
+
+## Regex cheat sheet
+
+This subsection just mentions the regex rules in use, as a reminder.
+
+    ^ and $ match the beginning and end of a line.
+    \A matches the beginning of a string, \z and \Z match the end of a string.
+    \b and \B match word boundaries and nonword boundaries.
+    | vertical bar matches either the regular expression that precedes it or the regular expression that follows it.
+
+## Useful knowledge bits about ruby:
+
+- <b>class_eval</b> and <b>instance_eval</b> both set self for the duration of the
+block.
+
+## Deprecations within the roebe gem
+
+Over the years a lot of code was re-written or deleted. The more important
+changes may be noticed in this subsection.
+
+On 30.08.2021 the old class called **Roebe::FstabAppender** was removed,
+and subsequently replaced with class **Roebe::GenerateFstabFile**. The
+latter uses better code and makes use of a yaml file for my default
+fstab-content. This should also make it easier for other people to
+auto-generate a **fstab** file. Simply change the entries in the yaml
+file, then run the class, and a new **fstab** file will be generated.
+
+The UUID entry currently is hardoded, though, so replace that as well.
+Eventually I may auto-generate the UUID entry as well, but for now
+I only wanted to remove the old code from **Roebe::FstabAppender**
+really.
+
+## class Roebe::SymlinkFilesFromThatDirectoryToTheCurrentDirectory.new
+
+First, before explaining what this class do, let's see how to use
+it:
+
+    require 'roebe/classes/symlink_files_from_that_directory_to_the_current_directory/symlink_files_from_that_directory_to_the_current_directory.rb'
+    Roebe::SymlinkFilesFromThatDirectoryToTheCurrentDirectory.new(ARGV)
+    Roebe::SymlinkFilesFromThatDirectoryToTheCurrentDirectory.new('/home/Programs/Pcre2/Current/lib/pkgconfig/')
+
+The last example is how I use it most of the time. Or, to be more specific,
+I use the bin/ representative of it, with an alias called **sfiles** to
+that class.
+
+So, what does this class do? It will symlink all files from the specified
+target directory into the current working directory. I needed this behaviour
+because the project called RBT (ruby build tools) has a few bugs right
+now (in October 2021). I do not know when I manage to fix these bugs, so
+I needed a quick work around - hence this class was created.
+
+The class was already written many years ago, but the code was annoying
+to read and deal with and I had no idea what was going on, so I rewrote
+it in October 2021 finally.
+
+## Building a modified LFS/BLFS
+
+Over the past 10 years or so, I have become increasingly displeased with
+the corporatification of Linux. Systemd is a good example, but it is not
+the only one. It's not solely confined to corporate-hackers taking over,
+but a concomittant rise in complexity. Things that used to be super-easy
+are now a LOT more complex. I will give an example.
+
+Back in the oldschool days, you compiled the fat mono-repo for xfree
+(whatever the name for the old xorg-server was), then you compiled 
+qt3 and kde3. That was fairly trivial. Nowadays, though, you need
+a LOT more additional stuff: xorg became modular so like 100-200
+packages are necessary. You need mesa, which in turn needs python3
+and LLVM - all of which increasingly become larger and larger. Then
+you need qt5, which is HUGE. And then you have to compile the 
+KDE5 stack which has about 200-400 packages (depending on what
+applications you need, but even the minimal variant is soooooo
+much bigger than KDE3). And these are just a few examples - the
+same happened to the whole "Linux stack".
+
+I would not be so upset if these things were to work properly, 
+but you keep on having more and more problems, or you suddenly
+somehow end up with a dependency on systemd. So this is all viral:
+it leaks in garbage and complexity into your system.
+
+As I am getting tired of this, and I don't want to adjust to 
+systemd and the other crapware, I decided to transition into
+a modified LFS/BLFS variant. This subsection here shall keep
+track of useful information pertaining to this, and possibly
+code (in ruby) that may be of help here. Of course the RBT
+project may handle most of these things, but the roebe-gem
+contains a few useful classes in this regard, so I wanted to
+document any findings here, rather than keep this for RBT
+only.
+
+So, what should be kept in mind for a modern computer system?
+
+Normally there should be a first partition, say, 256 MB
+for an EFI system such as this variant:
+
+    /dev/sda1       2048     526335     524288  256M EFI System
+
+(To be continued at a later time ...)
+
+## custom_methods.rb
+
+The file **custom_methods.rb** was actually the reason why the
+roebe gem was eventually created. I stored tons of ruby code
+in that file, many years ago.
+
+Things slowly changed as time passed by, yet custom_methods.rb
+still serves as "the main hub" - aka the main entry point to
+all my other ruby code and gems. Thus, a lot of ad-hoc methods
+are stored in that file.
+
+This subsection here may include a few details about this 
+file, but not everything will be documented here; only the
+more relevant entries may be documented.
+
+The method .json_to_hash() can be used to load a local file,
+which is assumed to be a json file, and return a Hash in 
+ruby.
+
+API usage goes as follows:
+
+    hash = json_to_hash('/home/Temp/magic_the_gathering/card_collection.json')
+    pp hash; ''  
+
+## Imgur
+
+This subsection just shows a bit of information in the event
+we wish to upload images to imgur.
+
+The client-id is <b>Client-ID 70ff50b8dfc3a53</b>.
+
+To upload an image to Imgur you could adapt this method:
+
+    ENDPOINTS = {
+      image:   '/3/image/',
+      gallery: '/3/gallery/'
+    }
+    API_PUBLIC_KEY = 'Client-ID 70ff50b8dfc3a53'
+    API_URI = URI.parse('https://api.imgur.com')
+    request = Net::HTTP::Post.new(API_URI.request_uri + ENDPOINTS[:image])
+    request.set_form_data(params)
+    request.add_field('Authorization', API_PUBLIC_KEY)
+
+See also the class called **UploadToImgur** that is distributed
+via the roebe gem since as of **October 2021**. It contains 
+a slightly better implementation to the above "raw points".
+
+Since as of <b>October 2022</b> class UploadToImgur can also
+download a remote image, which is first downloaded, and then
+uploaded to imgur automatically.
+
+## class Roebe::LeftHyphenInThisFile
+
+class **Roebe::LeftHyphenInThisFile** can be used to put **-** hyphens
+on the left hand side of a file. It will generate a new file by default
+rather than overwrite the existing file.
+
+You may ask "But why add a class for something that is as simple as
+using **.map {}**? Yes, that is a valid question, but I needed this
+to turn a .txt file into a .yml file, for an Array. And YAML wants
+arrays via leading **-**. Since I was constantly creating new 
+yaml files that way, and had to add leading **-** manually, I got
+tired of it, and simply added that class in **November 2021**. 
+
+## class Roebe::RemoveLine
+
+This class can be used to remove one line from a file.
+
+Usage example:
+
+    remove_line 5 foobar.md # this removes line number 5 from the file called foobar.md
+
+Presently it can only remove one line, so it is not very flexible.
+At some point in the future it may be expanded in its general
+usefulness. For now, it's just kept as simple as possible really.
+
+## class Roebe::Modright
+
+This class can be used to automatically change the permissions of
+files and directories to a preset default. The default values are
+stored within that class - look at the two constants in this
+regard on top of the .rb file.
+
+Why was this class created? Sometimes some directories or files
+may have permissions that the user may not have wanted, so the
+main idea for this class is that it can restore the "default"
+permission for files and directories.
+
+## Roebe::GUI::Gtk::WlanInformationCenter
+
+This ruby-gtk3 specific class shall help users on linux
+to set up their wlan-devices. It originated from the
+older class Roebe::GUI::Gtk::WlanInterface which was
+too cumbersome to use in general. With this new class,
+however, even new linux users should be more comfortable
+in setting up their wlan-devices. A tabbed interface
+will be used.
+
+## Roebe::AddNewlineAfter
+
+This class will simply add a newline after the specified token.
+
+If you want to change the default token then use the method
+**.use_this_token =**.
+
+Why was this class created? I sometimes have to look at .html
+files that are compacted. Since it was annoying to split it
+up, I wanted a script that does this for me.
+
+## class Roebe::GoodNight
+
+**class Roebe::GoodNight** simply combines class Roebe::At
+as well as playing some video files or audio files; by default
+using simpsons movies from my local play list. You may have
+to adjust this to your use case if you want to re-use this
+class.
+
+## module Documentation
+
+Since as of <b>17.04.2019</b> I am slowly integrating all my
+<b>local documentation</b> in ruby into the **Roebe** project.
+
+This will take months or years at the least, though. Remember
+that I gathered ruby-specific knowledge tidbits in the last
+20 years; it's spread all over the place on my local
+filesystem.
+
+Unfortunately that documentation in particular is primarily only
+available in the german language, so not many other people may
+benefit from it. I am working to translate some of this into
+english, but this takes time.
+
+**sinatra** is presently required to view the documentation.
+
+If you wish to start that sinatra interface, you can do the
+following from the commandline:
+
+    roebe --serve-documentation
+
+To require the documentation manually, you can issue:
+
+    require 'roebe/documentation/app.rb'
+
+Note that the gtk-specific part currently (2022) does
+not work: I plan to move this into the **gtk_paradise**
+gem.
+
+Since as of **March 2022** ruby-on-rails specific information is
+stored in the directory **doc/ruby_on_rails_tutorial/**. This is
+currently a .cgi file and requires the gem called **cyberweb**.
+In the future this may become more flexible, but for now it is
+stored therein.
+
+Note that since as of <b>July 2022</b> module Documentation
+is mildly deprecated. It will be more likely that future
+documentation will simply reside under doc/ instead.
+
+## class Roebe::DateSort
+
+This class, residing at <b>roebe/classes/date_sort.rb</b>, will
+sort files based on their filenames. As part of the filenames
+the date should be "embedded" into, e. g. something like "22.02.2022".
+
+I aliased this class towards **date_sort** and use it in
+pipes, such as:
+
+    ls | date_sort
+
+## The Roebe::Shell component
+
+**Roebe::Shell** can be used as some kind of substitute for IRB or
+shells such as <b>bash</b>, <b>zsh</b> or <b>fish</b>. The primary
+use case for <b>Roebe::Shell</b> is **interactively**, that is to
+have the user type in commands, and the shell will attempt to
+**make sense** of these instructions.
+
+**Roebe::Shell** was based on the older **DiamondShell** project, which
+was abandoned in **2020**. Some parts of the code from the DiamondShell
+project continues to exist in **class Roebe::Shell**, albeit a lot
+of it was heavily modified or even removed.
+
+You can start the shell via the above **Roebe::Shell.new** call,
+or this simpler toplevel variant:
+
+    Roebe.shell
+
+What is a **shell**, actually?
+
+A shell is essentially a program used to execute other programs - for 
+instance, you can start your editor from the commandline by making
+use of a shell. A shell is usually interactive: it **requires user
+input**, be it from a human being, a computer/robot or from some
+script.
+
+There are many different shells - UNIX/Linux systems may have csh,
+bash, zsh, fish. Windows may have the old <b>cmd.exe</b> or the newer
+<b>powershell</b>. And more recently, say since 2016, you may also use
+bash on Windows in an easy manner - apparently Microsoft is learning
+something new these days (e. g. WSL1 or WSL2). 
+
+The **Roebe::Shell** component of the **roebe** project tries to learn
+from all of the above shells and how these are used, and combine what
+seems useful into the <b>Roebe::Shell</b> namespace. I always loved
+the RPROMPT feature of zsh, for instance - unfortunately, this is
+on my TODO list, so it is not added yet.
+
+Since as of **September 2020**, Roebe::Shell makes use of class
+Roebe::UserInput for obtaining (and working with) user input.
+I grew tired of having to write the logic into class Roebe::Shell
+when I instead wanted to focus on dealing with the user input
+itself, so that I can abstract the details away.
+
+If you need to obtain the configuration settings for a Roebe::Shell,
+in Hash format, then issue the following command from a running 
+instance of the Roebe::Shell:
+
+    config_as_hash
+
+The following examples will showcase what the Roebe::Shell can do,
+but keep in mind that these are just examples; there may be many
+more entries to use which are not documented here for lack of space.
+
+If you need to generate a random string, use:
+
+    randomstring 5
+
+The number 5 ensures that the length will be 5 characters. This
+feature may be useful to test something.
+
+If the shell-configuration enables colour-support then you can
+use RGB colours, if you use it via KDE konsole. Example for
+this:
+
+    darkkhaki hello world!
+    royalblue this is a test in royalblue
+
+Presently the whole string is specified in that colour, but in
+the future we may add support for arbitry colouring of the
+text.
+
+To quickly show all directories in the current working directory,
+try:
+
+    show_directories
+
+To show the current $PATH in use for the running Roebe::Shell
+instance, try any of the following:
+
+    show_path_in_use
+    showpathinuse
+
+Note that in <b>April 2022</b> the Roebe::Shell project was
+again rewritten from scratch. The primary reason as to why
+this was done was to enable <b>lazy loading</b> from the
+get go for add-ons; a secondary reason for the rewrite was
+proper support for windows. I needed a better alternative
+to (vanilla) <b>cmd.exe</b>, but without the overhead
+that comes with <b>powershell</b>.
+
+If you want to see which components (add-ons) have been
+lazy-loaded so far, then issue either one of the following
+commands inside of a running instance of the Roebe::Shell:
+
+    status?
+    components?
+
+Keep in mind that in particular larger gems may take
+a few seconds before they are fully loaded. At the
+time of writing this in <b>May 2022</b> I myself
+use 36 different gems and add-ons for the
+<b>Roebe::shell</b>:
+
+### Goals for the Roebe::Shell project
+
+The Roebe::Shell project, as part of the Roebe project, shall be
+a replacement for **irb** but also for **bash** in the long run
+(this is a long-term, distant goal, one day).
+
+Perhaps in the distant future it may also offer features such as
+those available in zsh, fish or pry. We may also make use of **mruby**
+instead and compile in the required tidbits - should make it much
+faster than before. At the least in theory.
+
+And a GUI component in ruby-gnome, similar to cuiterm; this can be
+seen in the gtk_paradise project, but it is not quite complete 
+yet.
+
+Keep in mind - it is much easier to speak about goals rather than go
+and really achieve these goals. When it comes to code, the number one
+factor simply is **time** that will be invested into a given project.
+And time is a limited/finite resource.
+
+### Usage of the Roebe::Shell, in Ruby Code
+
+    require 'roebe/shell'
+
+    Roebe::Shell.run # To startup the Roebe-Shell
+    
+    # Alternatively, you can also use Roebe::Shell[] as starter.
+
+### Features of the Roebe::Shell
+
+There are many features that the <b>Roebe::Shell</b> aims to achieve and
+implement.
+
+One goal is to function as a replacement to **bash** and
+also **irb** eventually. It is still a long way to go.
+
+### Usage inside of a running Roebe::Shell instance:
+
+If you manage to start the Roebe::Shell, which should be
+possible by issuing "**dia**" (residing in **bin/roebe** of
+this gem, but I aliased it to **dia** because that was
+its original name from several years ago) you can then
+issue the help command to show the common functionality
+available:
+
+    help
+
+To see the current version of the Roebe::Shell, do:
+
+    version
+
+To **generate all keys**, do:
+
+    generate keys
+
+To **remove comments** from all **.ogg files** in a given directory,
+we can do:
+
+    remove_comments *ogg
+
+To stat some files do:
+
+    stat test.txt # The simplest variant: you simply pass the name of the file at hand.
+    stat 1 2 3    # This will stat the files at position 1, 2 or 3.
+    stat 11,12    # This variant is also possible, if you would like to use it.
+
+If you want to create several new files via one line then you
+can use the following:
+
+    touch {temp1,temp2,temp3,temp4}
+
+This would create the four files called temp1, temp2, temp3 and
+temp4. The behaviour is similar to UNIX/Linux shells such as
+<b>bash</b> or <b>zsh</b>.
+
+You can cd into a directory by issuing i.e.:
+
+    cd /tmp
+    cd 1 # Positional arguments are possible as well. This would cd into the first directory.
+
+You can also **cd** into an archive - this means that we will
+first extract the archive, then cd into that directory.
+
+Specific example for that:
+
+    cd htop-1.0.2.tar.xz
+
+To **upload** a file, or several files, do:
+
+    upload foo.txt
+    upload *
+    upload 1,2,3
+    upload 1-3
+
+To **convert** formats into one another, you can use the
+**convert()** functionality, such as:
+
+    convert foo.png foo.pdf
+    convert bar.mp3 bar.ogg
+
+To show the **padding in use**, do either:
+
+    padding?
+    show padding
+
+You can see the input **history** by doing this:
+
+    history?
+
+If you don't like this, you can **disable** it via:
+
+    disable history
+
+In general, if you wish to **disable** something, you do:
+
+    disable ENTRY_HERE
+
+To start transmission in the background:
+
+    transmission URL_HERE
+
+To **sort all files** in the current directory by size, do:
+
+    sort_by size
+
+To see the available **configuration**, issue this command:
+
+    configuration?
+
+You can also **fetch documentation** of Ruby Stdlib or Corelib.
+
+Do this:
+
+    docu? foobar.rb
+    docu? Array#sort
+    docu? Array.push
+
+If you wish to display a celsius to fahrenheit table, do:
+
+    celsius
+
+All of these should work. The first way will fetch docu from
+a .rb file, but right now it will only parse the header - the
+leading comment, that is, in a .rb file. The other variants
+make use of Ri to fetch docu.
+
+You can also **view the source** of a **method** or the **documentation**
+to a **method**.
+
+Do this:
+
+    show-docu-of? yel
+    show-method-of? yel
+    $ String.size
+
+Video and audio files can be played if you use mplayer or
+mpv. On my home system, for instance, I can input the
+following:
+
+    play_video :1
+
+The :1 means to use the first video from the location to where I
+keep all video files. If the video exists there then it will
+be played. I use this shortcut to avoid having to type the
+full path or navigate to the directory where my local video
+files are stored. I even shorten this to:
+
+    pvideo :1
+
+Quite convenient to work with the Roebe::Shell that way! \o/
+
+To create a directory, use something like the following:
+
+    mkdir /Depot/j
+    mkdir /Depot/jj /Depot/jjj # You can provide more than one argument here.
+    create_directory /Depot/Temp
+    cdir /tmp/test # And you can use different aliases too; "cdir" stands short for "create_directory".      
+
+To run animated ASCII components, if you have the ascii_paradise
+gem installed, you can issue:
+
+    ascii1
+    ascii2
+    ascii55
+    # or if you prefer, a tiny bit longer
+    ascii 1
+    ascii 2
+    ascii 55
+
+Note that this does not work very well on windows cmd.exe as of
+<b>May 2022</b>. I may have to look at the reason for that at
+a later moment in time.
+
+If you want to see which components were "lazy loaded" so far
+then simply use:
+
+    status
+
+To change the title of a cmd.exe window, do this:
+
+    windows_title cats    # The title is now "cats".
+    windows_title foo bar # The title is now "foo bar". 
+
+To find out the current user's home directory you can simply 
+input:
+
+    Dir.home # on windows this will yield a result such as C:\Users\debug
+
+By default Roebe::Shell tries to use the **Readline** module. This
+is not always desired. If you want to toggle between regular
+$stdin and readline-mode, then do either of the following:
+
+    toggle-user-input
+    toggle user-input
+    toggle userinput
+
+Working on windows can be a bit inconvenient, but many UNIX/Linux
+tools are available on windows as well. For instance, the
+editor <b>nano</b> works on windows. You can invoke it from
+the Roebe::Shell via:
+
+    nano /Depot/j/foobar.txt # Pass the path to the file to nano. 
+
+Of course this will only work if you have installed the
+nano-executable on windows too. Use google to find out
+where to best obtain the nano-executable - I found it
+from a StackOverflow link in <b>May 2022</b> - and it works! \o/
+
+To do a silent startup (less verbose) you can do this:
+
+    dia --silent-start # or an alias such as --silent-startup and various more.
+
+Normally on startup the method startup() is invoked, but
+this is not always wanted, such as when you want the
+start-up of the Roebe::Shell to be faster, or to load
+less stuff. In this case, to disable that for the
+current run, start a new instance via:
+
+    dia --no-startup
+
+Various other commandline options are available. For instance, you
+can toggle whether you are on a roebe-system from the commandline
+via:
+
+    dia --is-on-roebe
+    dia --is-not-on-roebe
+
+The first enables this; the second disables this. I needed this
+on windows in particular.
+
+### Assignments within the Roebe::Shell
+
+The <b>Roebe::Shell</b> allows the user to assign to a main file.
+
+In order to do so, the user can assign to the main file like this:
+
+    asssign foo.txt
+
+Now, in several command actions, like copying, you can omit typing
+the name when this is done.
+
+Example for this:
+
+    copy to here
+
+The above command would copy the main file to the current
+location, aka Dir.pwd (current working directory).
+
+The Roebe::Shell will do this automatically for at the very
+least these actions:
+
+    copy a file
+    create a new file
+    when we play an audio file
+    when we open a file in an editor
+    whenever we stat a file
+    whenever we match to a local URL
+    whenever we open a file in the browser
+    whenever we append to a file
+    whenever we use jp2a
+    whenever we play a video file
+    whenever we trigger an action
+    whenever we create an iso
+    whenever we read a file
+
+### Editing via the Roebe::Shell and editor support
+
+The <b>Roebe::Shell</b> needs to allow the user to deal with
+existing local files as well as creating new files. This
+is, for the purpose of this subsection called <b>editing</b>.
+
+To find out which editor is the current main editor in the
+roebe-shell, do this:
+
+    editor?
+
+You can switch to another editor by using <b>seted</b> such as
+via:
+
+    seted bluefish
+
+This setting is persistent, and will be stored in the file
+<b class="orange">editor.yml</b>.
+
+Also note that since as of <b>September 2011</b>, if you try to
+open a directory, the Roebe::Shell will now open the content
+of the directory. (Before September 2011, the Roebe::Shell
+used to display an <i>error message</i> instead.)
+
+You can also open a local file based on the class name, if the
+file can be found.
+
+For instance:
+
+    bl BirthdayNotifications:
+    bl BirthdayNotifications
+
+The above will try to find a file called birthday_notifications.rb.
+
+If it can be found then we will open it in the editor.
+
+Note that as of <b>31.07.2015</b> you can also open a file based on the
+name of a method defined, if this method is part of the
+Roebe::Shell Project.
+
+Example:
+
+    bl show_completable_commands
+
+This would open the file show.rb because the above method is
+defined in that file.
+
+Some editors, such as vim, allow you to jump to a specific line
+position, such as by doing <b>vim foo.txt +55</b>. We attempt to
+somewhat simulate this behaviour, in the event that you supply
+a "<b>:</b>" character, and numbers after that.
+
+For instance:
+
+    edit foobar.rb:55
+
+We would assume this to mean "edit the file foobar.rb", and
+"jump to position 55". Currently this works only via vim though.
+
+You can also use the traditional vim syntax directly:
+
+    vim $DIA/configuration/configuration.rb +371
+
+Do note that we will also expand aliases. So if you try to open
+an alias in your editor, we will expand towards the real file
+that is used.
+  
+### Available components of the Roebe::Shell
+
+Sometimes you may want to find out whether all add-ons are
+available (and work) on a given computer system, from within
+a running roebe-shell.
+
+You can use the following commands to find out whether
+something is missing or not:
+
+    missing?
+    available_components?
+
+### The environment used by the Roebe::Shell and how to modify it
+
+To retrieve the value of an environment variable, do something
+like this:
+
+    e $AUDIO
+    echo $AUDIO
+
+Note that if you input just $AUDIO then we will cd into that
+variable if it is a directory. Either way the Roebe::Shell will
+first report the value of this environment variable, before
+doing a cd-operation. The cd-operation (change directory)
+will only be done if such a directory exists.
+
+The key lies in using $ to denote the variable in question, and 
+<b>e</b> is used to echo the content.
+
+If the variable was not found or defined, we will display a 
+little helpful note to the user.
+
+Example:
+
+    e $A_VARIABLE_THAT_REALLY_DOES_NOT_EXIST
+
+Also note that if you do something like:
+
+    e $L*
+
+Then we will try to feedback all environment variables starting
+with L.
+
+To feedback all known environment variables, do this:
+
+    environment?
+
+You can also sync towards the environment variables.
+
+What this means is the following:
+
+Consider that you have defined an environment variable
+called $EDITOR.
+
+You can sync towards this by issuing:
+
+    sync_to_environment
+    sync_to_env
+
+This will update the configuration settings, such as by modifying
+the file called <b>editor.yml</b> which keeps stored which
+editor we will be using.
+
+### Logging & History for the Roebe::Shell component
+
+By default, most commands are logged to provide a **history**.
+
+These will be stored in the yaml file **last_commands.yml**.
+
+If you don't want history support, you can do:
+
+    disable history
+    save config # If you wish to make this persistent.
+
+To **re-enable history**, do:
+
+    enable history
+
+There are a lots of enable and disable functionalities available.
+
+Try:
+
+    enable HELP
+    disable HELP
+
+You can also use **--help** rather than **HELP**, or just use the
+**?** character such as in:
+
+    enable ?
+
+**?** is assumed to mean "help" here.
+
+**?** also plays an important role when obtaining extended documentation
+about the commands available in the help menu. For instance, say you
+want to understand what **touch** does.
+
+In this case, you can do this here:
+
+    ?title
+    ?scp
+    ?touch
+
+The **leading ?** means that the <b>Roebe::Shell</b> will assume that the
+user has a question about this built-in method. (touch is like the
+UNIX touch command; we will use it to create a file. You can also
+use the alias create_file instead if you want to - there is more
+than one way to do things in ruby. Pick the one you prefer.)
+
+If a command requires more documentation, send an issue request
+to add it. (Mostly it follows UNIX/Linux conventions, so touch
+is used to create a new file, and so forth.)
+
+This will redirect the content of foo.txt into a file called
+"this_file".
+
+You can benchmark (and thus time) how long it takes to
+load up the components stored via "lazy loading, by issuing
+the following:
+
+    dia --benchmark
+
+This currently isn't working 100% correctly, due to various
+reasons; one being that the current way how the Roebe::Shell
+loads add-ons via <b>Thread.new {}</b> isn't perfect.
+However had, minor issues aside, <b>dia --benchmark</b> still
+yields some important information. I could use it in 
+<b>May 2022</b> to notice some slow-loading add-ons, some
+of which were mine, which I could then go on and improve
+upon. 
+
+### The Roebe::Shell environment
+
+Initially on startup a copy will be made from <b>Roebe.env?</b>.
+
+This can lateron be modified by the user and it is valid for
+the current run.
+
+### Configuration - how to configure the Roebe::Shell
+
+The configuration is kept in the directory **configuration/** 
+within the project, and consists of **individual .yml files**.
+
+The convention for these yaml files is simple - the name of the yaml
+file in question will become a **value** on the **configuration object**,
+which you can then modify.
+
+For instance, **debug.yml** can be **true** or **false**, and will also
+be available in the ivariable **@config.debug**.
+
+### Tab completion in the Roebe::Shell - typing a command, then pressing the TAB key
+
+You can tab-complete if you run the Roebe::Shell with Readline support.
+(If readline is not installed, then we will obtain user input via 
+the traditional $stdin.gets.chomp way)
+
+Simply start to type something such as "ext" then hit the tab key,
+and it may give you some choices as to which part to tab complete
+to.
+
+Another example would be:
+
+    @configuration.<TAB>
+
+Also, the main case when menu of the <b>Roebe::Shell</b> is also
+available for tab-completion.
+
+<b>Autocompletion</b> means that if you press the TAB key, you will
+be able to choose from a selection.
+
+Before explaining this further, give it a try. Start a new
+instance of <b>Roebe::Shell</b>, and then do this:
+
+    extract|TAB|
+
+The <b>|TAB|</b> notation here means "<b>press the tab key
+here</b>". So first you write extract, and then you press
+the tab key.
+
+You will get a selection between <b>extract_audio</b> and
+<b>extract_video</b> and possibly <b>extract_it</b> as well.
+
+Press v and then TAB again. You will have selected video.
+
+The file that handles autocompletion is readline.rb, which
+you can find in the base/ subdirectory.
+
+Note note that we allow you to autocomplete to the list
+of available instance variables.
+
+For instance:
+
+    @al<TAB>
+
+Would list which instance variables with a name starting
+with @al exist.
+
+Additionally, all entries found in $PATH will also be completed.
+
+As of <b>August 2014</b>, we will also add support for some
+completions of the Ruby stdlib.
+
+Since as of <b>September 2015</b>, the roebe-shell will also
+tab-complete on leading <b>@configuration.</b> entries. This
+way you can cycle through the available configuration options
+more quickly.
+
+Next follows an image screenshot for these options:
+
+<img src="https://i.imgur.com/QxwHGR7.png" style="margin: 1em">
+
+### Encoding used by the Roebe::Shell
+
+You can specify another encoding to be used for the Roebe::Shell, 
+either in a yaml file, or through ruby code like this method call:
+
+    Roebe::Shell.set_encoding
+    Roebe::Shell.set_encoding :binary # to set to the binary encoding ASCII 8-bit.
+
+Of course you can also pass in the full name of the Encoding that
+you want to use, as a String.
+
+For instance:
+
+    Roebe::Shell.set_encoding 'UTF-8'
+
+### Roebe::Shell Commandline
+
+You can display the commandline options via:
+
+    dia --help
+
+For instance, if you do not want to read in the default yaml config
+then you can start the <b>Roebe::Shell</b> via:
+
+    dia --norc
+
+### Registering errors and registering information via the Roebe::Shell
+
+This short subsection just mentions a few methods that may (or should)
+be called when errors occur.
+
+If a gem is missing then this should be properly registered via:
+
+    Roebe::Shell.register_this_missing_gem
+
+That way we could automatically install these missing gems, or
+at the least inform the user about this properly.
+
+### The PID file of the Roebe::Shell component
+
+We will store the PID in a file, typically called **pid.yml**. On an
+exit-event, that is when we will exit from a <b>Roebe::Shell</b> instance,
+we will delete that PID again from that file. That way we can have
+multiple Roebe::Shell instances running and we can keep track of
+which ones are running.
+
+### Lazy loading by the Roebe::Shell
+
+Upon startup of the **Roebe::Shell** many components will be
+loaded in the background, via Thread.new {}.
+
+The main idea behind this is that the user should be able to
+type instructions the very moment the shell has started. 
+Waiting is no fun, so this should not reduce usability of
+the shell. This is also called <b>lazy loading</b>.
+
+Unfortunately this currently does not work perfectly well.
+Sometimes race conditions may happen and warnings are 
+shown. For the time being (**May 2022**) this will persist.
+In the future it is planned to remove this constraint and
+make loading of add-ons trivial, simple and effective.
+
+### Browsers and the Roebe::Shell
+
+If you designate a browser then you can easily open pages in that
+browser. There is even code that can try to auto-detect which
+browser may be the main browser on a system. This currently only
+works when a file called browser.yml exists, which points to the
+browser at hand. If it does, and if "is_roebe?" returns true,
+and if no file could be found at that particular location, then
+the auto-detection code will try to find another location where
+the browser may be installed. But this is not failsafe, it may
+not work.
+
+### Future work related to Roebe::Shell
+
+As you may have noticed, the project is mostly on stand-by mode,
+largely due to time constraints. While I am still adding and
+improving things every now and then, I would not call the project
+very active really.
+
+I have had lots of ideas to do but either lack of time or lack
+of knowledge present a block to these ideas.
+
+At any rate, just for anyone who may be curious, what kind of
+ideas and changes may be necessary, in order to make this
+project more complete and more useful as well?
+
+An incomplete list would include:
+
+- We need a full replacement for IRB.
+
+- We need the ability to synchronize between different 
+<b>Roebe::Shell</b>, including local ones and remote ones.
+
+- RPROMPT from zsh (optional, not mandatory)
+
+- Friendly help for newcomers (all those help options must be 
+controllable though, so that advanced users can disable these
+at their own discretion - see the fish shell that really 
+tries hard to be a newbie-friendly shell).
+
+### show-method in the Roebe::Shell
+
+Since as of September 2015, the character <b>$</b> can be used
+to show the source code to a method.
+
+Aliases can be used such as:
+
+    show-method
+    show-source
+
+This allows one to view the source code of a method.
+
+Usage example:
+
+    show-method trigger_actions
+
+### The home directory of the Roebe::Shell
+
+It is useful to be able to use a designated home directory
+as far as the Roebe::Shell is concerned.
+
+You can also designate a new (different) home directory for
+the Roebe::Shell.
+
+In other words, this will be the new directory where we will
+save files to, and so on.'
+
+The syntax to designate a new home directory, as can be
+seen if you use --help from the commandline, is as
+follows:
+
+    roebeshell --home-dir=/opt 
+
+### Requiring files and projects in the Roebe::Shell
+
+You can require files and projects in the Roebe::Shell via:
+
+    require 'sinatra'
+    require 'thor'
+
+If all works fine then no output will be generated by the
+running Roebe::Shell.
+
+If the project has not been installed then this will not
+work, and the user is notified about it, such as via:
+
+    require 'THIS_GEM_DOES_NOT_EXIST'
+
+Leading to:
+
+<img src="https://i.imgur.com/DrdWVYc.png" style="margin: 1em">
+
+This functionality allows the user to use the Roebe::Shell
+a bit like <b>IRB</b> - not exactly identical, but somewhat
+similar.
+
+From within a running instance of the roebe-shell, you can use
+any of the following commands:
+
+    add_require NAME_OF_GEM
+    add_require roebe
+    addrequire  foo
+    addreq      foo
+
+This would add the gem require to the file called:
+
+    FILE_ADDITIONAL_REQUIRE_FILES
+
+This can be found in the file <b>roebe/shell/shell/shell.rb</b>.
+
+### Handling the PATH variable from within a running instance of the Roebe::Shell
+
+The Roebe::Shell will try to use the 
+<span class="color: yellow; background-color: black; padding: 4px">
+$PATH environment</span> variable, if it was set.
+
+All binaries known there will be used for both the completion, and
+as known-executables. This is similar to how other shells handle
+the $PATH variable.
+
+### Random stuff via the Roebe::Shell
+
+The file at core/random.rb allows you to do some 
+random things.
+
+For instance, to play a random video you can issue:
+
+    random video
+
+### Redirect output via the Roebe::Shell
+
+You can redirect the content of a file into another file, similar
+to bash and zsh.
+
+Consider the following syntax examples:
+
+    cat foo.txt >> this_file
+    cat foo.rb >> bla.txt
+
+Since as of November 2015, output can be redirected
+into a file, in <b>append-mode</b>.
+
+The above examples will properly append the content of the respective
+files (foo.txt or foo.rb) into the files given as example above.
+
+### The Environment used by the Roebe::Shell
+
+In ruby, the constant variable **ENV** keeps information about the
+environment - at the least variables, such as **PATH**. (More
+about PATH in another subsection of this document here.)
+
+The Roebe::Shell also keeps a reference copy towards ENV, through @env
+defined on the top-level namespace. This can be accessed through
+<b>Roebe::Shell.env?</b>.
+
+To display the ENV variable you can do the following from within
+a running instance of the <b>Roebe::Shell</b>:
+
+    ENV
+    display_environment
+
+### PATH used by the Roebe::Shell
+
+The ENV['PATH'] variable determines which path is used for ruby,
+in particular for system() and similar calls.
+
+There are various ways how to manipulate the PATH variable from
+within <b>Roebe::Shell</b>.
+
+Say that you want to add the PATH variable /System/Index/bin/;
+then you can issue the following command:
+
+    pathgen.add /System/Index/bin/
+
+### Beautiful URL and how it relates to Roebe::Shell
+
+There is another ruby project called **beautiful_url**. This project,
+essentially, maps an input argument (a String), into a longer
+String - normally a remote URL.
+
+This can also be called from the <b>Roebe::Shell</b>. For example:
+
+    beautiful_url Einführung in die Kohlenhydratchemie
+
+would display the remote URL of the lecture called **Einführung
+in die Kohlenhydratchemie**, aka this as a result:
+
+    https://ufind.univie.ac.at/de/course.html?lv=270143&semester=2018S
+
+This can then be opened in the browser from within the 
+<b>Roebe::Shell</b> too:
+
+    open_in_browser
+    openinbrowser
+
+### Date format used by the Roebe::Shell
+
+If you input a date format such as dd.mm.yyyy then the <b>Roebe::Shell</b>
+will display which weekday this refers to.
+
+### Compiling via the sql-based compiler class
+
+Since as of <b>August 2022</b> it is possible to make use of
+the SQL-based compiler class that is part of the rbt gem.
+
+Invocation example from within the roebe-shell:
+
+    sqler kinit
+    sqler kio
+    sqler make # and so forth
+
+This was added for convenience reasons mostly, so that
+we have simple support for this on windows as well,
+when working with vanilla <b>cmd.exe</b>.
+
+### class Roebe::UserInput and the Roebe::Shell
+
+class <b>Roebe::UserInput</b> was removed in <b>May 2022</b>. It was
+only used in the Roebe::Shell. When the latter was rewritten in
+<b>May 2022</b>, the need for a separate class Roebe::UserInput
+was no longer given. I originally assumed that other projects
+may benefit from this class, but I realised that not a single
+other project ever made use of that code - so, better to get
+rid of "dead" code instead.
+
+### The gtk-shell interface
+
+There is a GUI for the shell, in <b>ruby-gtk3</b>. It is not
+the prettiest thing in the world, but I wanted to be able to
+use a GUI for the shell.
+
+The following picture (taken on <b>IceWM</b>) shows how this
+may look (in <b>August 2022</b>):
+
+<img src="https://i.imgur.com/Vb0pySJ.png" style="margin: 1em; border: 2px solid black">
+
+This may not be extremely pretty, but for now getting the
+functionality to work without any bugs is the most important
+objective. At a later this may be improved upon, visually
+as well.
+
+Note that the main functionality for this is implemented via a module.
+That way it also works for <b>libui</b> as-is - and perhaps for a
+www-interface (via the web, such as sinatra) too, one day.
+
+I have also tested the <b>libui-shell</b> in <b>August 2022</b> on
+windows and it works. It is presently not extremely sophisticated,
+but I think I can enhance it slowly over the coming months. For
+instance, to evaluate the content of the user input entry 
+continually whenever it has been changed. In the middle of
+<b>August 2022</b> a small modification was made: if you input
+the '#' (comment) character then this will be treated as an
+instruction to have hit the enter-key. This is a hackish 
+workaround for the fact that we currently can not get 
+key-events in libui, but I think it works ok-ish and is
+more convenient to use than click on a separate button via
+the mouse pointer.
+
+## class Roebe::Configuration::Configuration
+
+This class used to be a separate project (a standalone gem), but
+was integrated into the Roebe namespace as of <b>August 2020</b>.
+
+The main class here, called **Configuration**, is able to act as
+a hash-like configuration class, similar to open struct. It must
+be able to properly interpret $ variables as shell-variables on
+top of it, via the project called **ConvertGlobalEnv**.
+
+Currently, every key-value pair that exists as part of
+our Configuration object must be **a standalone yaml file**.
+
+If such a file can not be found, but a value exists in
+our hash, the default behaviour is to create this file
+automatically. This is another difference to **OpenStruct**:
+I really wanted to use a configuration scheme based 
+<b>solely</b> on yaml files, so this was one reason
+why the Configuration namespace was written/added.
+
+We must keep in mind that internal variables and methods
+defined on the base class Configuration could conflict
+with user-defined methods, so we have to be very 
+careful when setting values in <b>class Configuration</b>.
+
+Do note that class Configuration depends in principle
+on at the least one additional gem:
+
+    convert_global_env # install like so: gem install convert_global_env
+
+However had, in May 2022 this dependency is no longer
+mandatory. You could also use the gem called
+<b>rcfiles</b> instead; it should be a bit faster
+and it works better on windows, as windows has
+problems with ENV (or at the least I had problems
+with cmd.exe in this regard - thus rcfiles also
+offers a hardcoded solution to this problem. Having
+hardcoded values is not as elegant, but better to
+be ugly than to not work at all).
+
+## Support for GraalVM
+
+<b>GraalVM</b> is pretty awesome. In 2022 I am experimenting a LOT
+with it; if you have not tried using <b>GraalVM</b> yet - or may
+not have had a use case for Java - I recommend to give GraalVM
+a try.
+
+I am re-writing some ruby classes found in the roebe gem into Java -
+not all of them, mind you, but some just for testing purposes.
+
+These can then be compiled as <b>static native binary</b>, at the
+least <b>on linux</b>.
+
+The commandline flags for this feature go like that:
+
+    roebe --graalvm1
+    roebe --graalvm7 # for instance, refers to the file "Schlafe.java"
+    roebe --graalvm16
+
+This will take a specific .java file in the main directory
+and then use GraalVM's native-image to compile them. This
+will only work if you have graalvm installed, as well as
+native-image (and ideally upx as well).
+
+You can also turn all these .java files into executables
+(on linux) via:
+
+    roebe --allgraal
+
+This will take quite some time, though. On my home system it takes
+about 30 minutes; the more .java files are added the longer this
+will take, so this is really only used by me on a new computer
+installation.
+
+## GUIs: Graphical User Interfaces
+
+The <b>roebe</b> gem comes with a few GUI bindings. These are mostly just
+small things, for demo-purposes. For reasons of simplicity I consider
+www-specific code to be a GUI as well, such as any interface through
+the sinatra gem.
+
+Traditionally I have been using ruby-gtk, but since as of 2021 I am also
+using **libui**. Expect more libui-centric widgets to be added over the
+coming years.
+
+To keep track which widgets were ported already the following small table
+may be useful but it may become outdated eventually:
+
+    (1) show_ten_aliases.rb          # Just show the next ten exam topics; evidently only useful on my home system really
+    (2) wlan_interface.rb            # This is about 80% complete; the combo-box is missing so far and the middle-buttons.
+    (3) interactive_caesar_cipher.rb # This is mostly complete; could need some minor improvements but for now it's fine.
+    (4) show_aliases                 # This is mostly complete, about 98%. Perhaps a few minor tweaks but for now it's fine.
+
+Since as of **September 2021 I** am experimenting with the project called
+**simple_widgets**. The idea behind this project is to make it
+possible to use different GUI toolkits. As to whether this will be used
+for the whole code base remains to be seen.
+
+For now the first widget has been ported onto SimpleWidgets. Invoke this
+from the commandline via:
+
+    roebe --caesar-gtk    # for the gtk variant
+    roebe --caesar-libui  # for the libui variant
+
+You need ruby-gtk3 and ruby-libui for this, so install these first.
+
+We there use the same code base, but can support both ruby-gtk as
+well as ruby-libui at the same time. \o/
+
+Since as of <b>August 2022</b> the ruby-gtk2 bindings have been
+mildly deprecated. They may remain as part of the roebe gem,
+but it is unlikely that any new ruby-gtk2 code is added. ruby-gtk3
+is better than ruby-gtk2 at this point in time.
+
+## class Roebe::DirectoryContent (deprecated since as of 2021)
+
+This class can display the content of a directory. I needed this
+class because I had to obtain information about the local 
+filesystem, and then display this on the commandline, via the
+WWW and via a GUI. So I required a unified interface.
+
+An older project existed, called show_directory, which was
+separate and underdocumented. So in September 2020, DirectoryContent
+was created. The goal is to be extremely well-documented.
+
+Requiring this class is simple:
+
+    require 'roebe/classes/directory_content/directory_content.rb'
+
+Using it is simple as well:
+
+    Roebe::DirectoryContent.new # Without any arguments it will default to the cwd.
+    Roebe::DirectoryContent.new(ARGV)
+    Roebe::DirectoryContent.new('/tmp/')
+
+Internally the instance variable @work_on_this_directory will keep
+track of the directory that is the target for this class.
+
+All findings from a given directory will be stored in a Hash, aptly
+named **@hash**.
+
+Since as of <b>June 2021</b> this is again different. Use the gem called
+**directory_paradise** instead. The above documentation has to be
+changed, but the internal code has not yet - stay tuned, and keep in
+mind to transition into **directory_paradise** instead. The code
+in directory_paradise should be easier to maintain, too.
+
+## class Roebe::ExtractDocumentation
+
+class Roebe::ExtractDocumentation can be used to quickly show
+the comments for a given method in ruby.
+
+Usage example:
+
+    require 'roebe/classes/extract_documentation.rb'
+    _ = Roebe::ExtractDocumentation.new(['file_here.rb', 'method_name_there']); _.report_result
+    _ = Roebe::ExtractDocumentation.new(['foobar.rb', 'run']); _.report_result
+
+Or via aliases on the commandline:
+
+    edoc $RUBY_ROEBE/classes/wikipedia.rb run
+
+Last argument is the name of the method you want to find out
+its documentation.
+
+## class Roebe::ReportHowManyClassesExistForThisDirectory
+
+This class can report how many ruby classes are in a
+given directory.
+
+Example output:
+
+    A total of 391 classes were discovered in the directory /home/x/programming/ruby/src/rbt/
+
+This does not work too terribly well, but if you just
+want to get a quick overview then this should work
+somewhat fine.
+
+## class Roebe::ModifyShebangHeader
+
+This class can be used to modify the shebang entry of 
+one (or several) .rb files.
+
+On windows the shebang I use is c:/ruby/bin/ruby. When I
+set a .rb file to use this shebang line then apache-served
+.cgi scripts work, so it shows that this does indeed
+work.
+
+To enable the assumption of a windows-shebang like this
+pass the options --is-on-windows to this class.
+
+<b>Be careful when using this class - it will not 
+keep any backups, so make sure that you backed up
+your data prior to running this class.</b>
+
+## class Roebe::StartProgram
+
+You can use class <b>Roebe::StartProgram</b> to start any program:
+
+    require 'roebe/classes/start_program.rb'
+    Roebe::StartProgram.new
+    Roebe::StartProgram.new :firefox
+
+This class was created because some programs, such as chrome,
+require additional commandline arguments. As I was tired to
+have this spread out into different aliases, I thought it
+may be better to bundle this into one class.
+
+## Support for jruby and Java
+
+I have only fairly recently (<b>December 2021</b>) started to use jruby
+more seriously, mostly due to windows support and the swing GUI 
+toolkit for java. On Linux I can use gtk just fine; and we have
+browsers, for cross-GUIs - but I wanted to be able to offer
+<b>native windows-support</b>. So jruby seemed like an interesting
+aspect in this regard.
+
+Right now there is not much to show.
+
+The only change I did was to add commandline support for
+one GUI so far:
+
+    roebe --jcipher
+    roebe --jruby1
+
+It is not complete either; the ruby-gtk3 variant works better.
+But I consider this more as a proof-of-concept. Who knows,
+in the future this part may be extended, to have more jruby
+support.
+
+Since as of <b>July 2022</b> I am also planning to port <b>some</b> of
+the roebe classes into Java. Probably not every class will be ported
+to Java, but I wanted to make at the least some of these classes
+available in Java as well.
+
+The following table mentions some of the porting efforts so far:
+
+ class name in Ruby        |  class name in Java             | % ported (estimate)
+---------------------------|---------------------------------|--------------------
+ Roebe::TakeScreenshot     |   TakeScreenshot.java           |   80%
+ Roebe::ShowPrimeNumbers   |   ShowPrimeNumbers.java         |   10%
+ Roebe::Translate          |   Translate.java                |   80%
+ Roebe::ToSquashfs         |   ToSquashfs.java               |   70%
+ Roebe::Schlafe            |   Schlafe.java                  |  100%
+
+## class Roebe::DoInstall
+
+<b>class Roebe::DoInstall</b> is used to primarily combine:
+
+    ./configure --prefix=/usr
+    make
+    make install
+
+Into one class.
+
+On my home system I aliased this to "doit", so I just cd to a
+directory and then invoke "doit".
+
+Example:
+
+    cd /home/x/Temp/rbt/php-8.2.0
+    doit
+
+This will compile php for me, for instance, without me having
+to type the above three separate commands.
+
+This works not only for GNU configure but also for cmake,
+meson/ninja and python <b>setup.py</b> files.
+
+Additionally since as of December 2022 a few configure options
+are available, such as <b>--use-configure</b>. What is this
+configure option doing?
+
+Take the above example again, where php is compiled.
+
+If I do:
+
+    doit --use-configure
+
+rather than:
+
+    doit
+
+then the default configure options for PHP, stored in the
+rbt gem, will be used.
+
+The output would then be this:
+
+    ./configure --prefix=/usr --enable-bcmath --enable-calendar --enable-cli --enable-dba=shared --enable-force-redirect --disable-libzip
+
+So I don't even have to remember any configure options
+per se. I just pass that flag onto the class via
+the commandline.
+
+Various shorter aliases exist for <b>--use-configure</b>
+such as <b>--coptions</b>.
+
+## Counting words
+
+You can use <b>bin/word_count</b> to count the number of
+words in a string/sentence/document on the commandline.
+
+## Roebe::JavaRunner
+
+This small ad-hoc class can be used to quickly pass some
+java-code (as argument), put it into a .java file and
+then run/compile that file automatically.
+
+I needed this class so that I can quickly test some java
+code, perhaps even autogenerate more java code in general.
+Via <b>Roebe::JavaRunner</b> I can quickly compile any
+java-code, as-is.
+
+ADD_CONTACT_INFORMATION