studium 0.14.16

data/README.md

@@ -0,0 +1,2987 @@
+[![forthebadge](https://forthebadge.com/images/badges/built-with-love.svg)](https://www.gobolinux.org/)
+[![forthebadge](https://forthebadge.com/images/badges/made-with-ruby.svg)](https://www.ruby-lang.org/en/)
+[![Gem Version](https://badge.fury.io/rb/studium.svg)](https://badge.fury.io/rb/studium)
+
+This gem was <b>last updated</b> on the <span style="color: darkblue; font-weight: bold">19.03.2023</span> (dd.mm.yyyy notation), at <span style="color: steelblue; font-weight: bold">00:32:18</span> o'clock.
+
+<img src="https://i.imgur.com/9HrOT5B.png" style="border: 1px solid black">
+<img src="https://i.imgur.com/tbKS413.png" style="margin-left: 0.3em">
+<img src="https://i.imgur.com/vwo4UuK.jpg" style="border: 2px solid black">
+<img src="https://i.imgur.com/Jcf9yoh.jpg" style="border: 3px solid black">
+<img src="https://i.imgur.com/SSIPq4l.jpg" style="border: 3px solid black">
+<img src="https://i.imgur.com/YG8V0hE.png" style="border: 3px solid black">
+
+## Introduction to the studium-gem
+
+Welcome to the legendary <span style="color: darkgreen; font-weight: bold">
+Studium</span> project! This project makes our brains go <b>epic-mode</b>
+(via oldschool training, though).
+
+This is the documentation that refers to the 0.12.x release series. This
+release series was started in **July 2022** and obsoleted the older 
+0.11.x release series that was started in <b>May 2022</b>.
+
+The primary focus of the 0.11.x series was a clean-up - old code that
+was no longer in use was removed. The primary focus of the 0.12.x
+series, though, is to extend the project while doing clean-up work.
+For instance, the java-bindings were started, and the ruby-libui
+bindings were improved on windows in particular. In fact: libui
+has been one big reason why the 0.12.x series was started. I really
+wanted to solve the libui GUI situation finally, so that we can
+use this project on windows as well.
+
+On **rubygems.org** the 0.11.x release series will be made
+available for a few more months. Consider updating to the
+0.12.x release series when possible, though.
+
+## Major and minor Goals and Objectives for the studium-gem
+
+This subsection will attempt to detail what the point of
+this project is. It will be a fairly long paragraph.
+
+The **Studium project**, first and foremost, attempts to help
+with **study-** and **exam-related topics** in general.
+
+What is meant with this?
+
+Well - consider the possibility that you wish to prepare for some 
+upcoming exam, going to occur in a few weeks from today. Perhaps you
+did build up some "flash card" mnemonics to remember questions and
+associated answers to these questions more easily. You want to
+train your theoretical knowledge in regards to these exam
+questions. Let's pick one exam topic, say: **general
+chemistry**. Ok, so ... this will be about chemistry-related
+knowledge.
+
+You will probably learn more about atoms, the electrons that can
+be found in these atoms, the chemical reactions that the outer
+electrons may undergo in the course of a chemical reaction.
+
+From this point of view, the **studium** gem is somewhat similar to
+other projects, such as **Studyflix** or **StuDocu** - these projects
+may also try to be of help in exam-related situations.
+
+The **primary** purpose of the studium gem is to distribute the code
+(in ruby, and to some extent in java), the associated dataset (mostly
+text files, in particular yaml files) and also **interconnect** the
+various ruby files that are distributed with this project under the
+same "umbrella-project", for a unified approach and a unified use
+case.
+
+The original goal for the **Studium project**, that is **why** it 
+was started, was to bundle together **knowledge** from different
+topics - be these topics related to **ruby**, **informatics**,
+**biology**, **chemistry**, **biotechnology**, **molecular
+biology**, **virology** or **physics**, as an **exam trainer**
+mostly.
+
+The objective here in this regard, as a trainer-for-upcoming-exams,
+was to improve the grades of the student at hand, and to be able
+to pass more exams within a given time span, thus making the time
+spent **more "efficient"** or worthwhile in this regard. (Evidently
+the user still has to invest time into learning on his or her own,
+so the studium-gem can only play a **supportive** role in this
+regard; it can not replace one's own impetus for wanting to learn
+more.)
+
+Since then, this original use case has been **extended** quite a
+lot, including online-related aspects (make the dataset available
+via a web-interface, such as through sinatra), or via **GUI
+bindings** (primarily via **ruby-gtk**, but also via **libui**).
+
+The **Studium** gem is made up of several different classes, that
+could potentially be of **help** to the user. The main toplevel
+"namespace" for the **studium** gem, in ruby, is simply <b>"module
+Studium"</b>.
+
+Note that not all the code may be needed for all use cases, so it
+is recommended to focus only on those parts that may be relevant
+for the user at hand, and simply ignore the other parts that seem
+of no use. People are different, so they may need different parts
+more so than others.
+
+As a by-product of ruby being OOP-centric in nature, lots of
+different classes may typically reside in the same
+project; the studium project is no exception to that rule.
+In the event that you are curious about these classes, feel 
+free to have a look at the right hand side of this gem's
+homepage, the **Table of Contents**. The direct URL for
+this is as follows:
+
+https://www.rubydoc.info/gems/studium/ 
+
+Furthermore, some classes are described in more detail in that
+file here (**README.md**), or respectively doc/README.gen, which
+is the template from which the **README.md** file is
+autogenerated upon publishing a new version of this gem. However
+had, do not expect a full explanation for all classes here; only
+some classes will be discussed in more detail.
+
+Note that there are **a LOT** of different classes and it is rather
+unlikely that you will need all of them, so don't focus on all 
+classes with the assumption that they will all be equally useful.
+Some of these classes have only **a very limited scope** and
+use case, and thus are not too overly useful. Other classes are
+more important, though, and the page here **attempts to focus
+primarily on these more useful classes**, or rather, the
+**functionality** that these classes ultimately provide. It is
+hoped that this functionality may be of benefit to other people
+as well.
+
+But not every feature is described there; it would make the
+listing way too long.
+
+The **major** focus of the studium gem lies in regards to
+"flashcards", mnemo-cards, anki-cards - aka entries that have
+a registered **question**, and an **associated answer** to
+that question. (anki-cards are a bit different in that they
+focus on a **GUI** and allow such fancy things like embedding
+pictures; the studium project here also has this as a minor
+goal, but this comes **only** via GUI bindings, not the
+commandline variant, obviously. It is of a lower priority,
+though.)
+
+These exam-related questions can be asked on the commandline,
+via a **delay** - usually a three seconds delay, but this
+can be toggled and changed by the end user on the commandline.
+
+First, the question will appear on the commandline, and then,
+after that specified **delay** has passed, the answer will be
+revealed (and shown) on the commandline. This way the user can
+improve his/her knowledge on a daily basis. In fact: although
+I have not been studying at a university in many years, I
+still use this project almost daily to expand my own local
+knowledgebase.
+
+You can query the current **set delay** via:
+
+    studium --delay?
+
+Note that, in order for the question-answer "exam trainer" to work, you
+need to have written down these questions and answers somewhere. By
+default, I have bundled the dataset that I personally use, but this
+will probably be very useless to most other people, so I recommend 
+to keep your own entries. (Many of my own entries are in german rather
+than english, so ... feel free to re-use any of these questions as
+you like to, if you find them useful. As of **March 2019**,
+there are over **32.500** question-answers registered in the studium
+project, in various different topics).
+
+The **format** for question-answers is very simple:
+
+  - **One question** and **one answer** per given line. For example:
+
+'- How does Rails call a "footer" on every page? "Partials".'
+
+The above would constitute a question-answer exam entry.
+
+The first part there constitutes the question; and the part after the
+first '?' character is the answer. The '?' token is not mandatory though;
+you can also substitute with 'A:' (which stands short for "Answer") and
+not make use of '?' at all.
+
+Note that any words enclosed in double quotes "" will be colourized differently
+when displayed on the commandline. The reason for this is mostly so that it
+provides a stronger visual cue as to what may be more important in the given
+question/answer at hand. I found this helpful for memorizing when having these
+questions asked on the commandline; for some reason my brain reacts more
+strongly to colours. Probably does so for other people too, but again - if
+you dislike anything there, you can (and should) always use your own
+exam-dataset here.
+
+## Namespaces in the project
+
+The main namespace for this gem is simply called **Studium**, which is
+german for **studies**. The gem could be renamed to **Studies** but
+considering the fact that the original use case was for universities
+in central europe, and many of the lectures stored in the main yaml
+file are for lectures in german, I think it would make sense to retain
+that name; you can always "alias" it like so, anyway:
+
+    Studies = Studium
+
+The **exam-relevant part** resides under the **Studium::Exams** namespace.
+So when you see that latter namespace, you know that it has to be code
+that is specific to exams.
+
+There are also some auxiliary classes, such as a primitive
+"statistical analyzer" of some sort, to rate the performance
+per day (from day to day, in regards to exam-questions that
+were answered).
+
+## Showing helpful information on the commandline
+
+A **general overview on the commandline**, as to what the main
+functionality is, can be obtained through this entry point,
+aka **--help**:
+
+    studium --help
+
+This will query **bin/studium**.
+
+## Constants and toplevel-variables used in the Studium project
+
+The Studium project makes use of lots of constants, in the ruby
+code. This subsection mentions a few noteworthy ones - in particular
+those that may be useful to know in some later situations when you
+wish to "globally" change an aspect of the project.
+
+The constant called MAKE_USE_OF_UNICODE_SYMBOLS_WHENEVER_POSSIBLE
+refers to unicode symbols. Elements such as the right-facing arrow,
+aka →. This can be useful as a visual cue.
+
+If you wish to make use of more unicode symbols than retaining this
+constant to true is good. This is the default value too (true).
+
+A toplevel query method exists as well - see:
+
+    Studium.shall_we_make_use_of_unicode_symbols?
+
+The old constant called ARRAY_EXCLUDE_THESE was removed for the 0.10.x
+series. The old content was [ '[]','[skip]','[done]','X' ] but I
+decided that a trailing [] is ideal. The trailing [] marks the
+exam question at hand as "answered and thus solved". Back then I
+experimented with different, simple ways to mark an exam question
+as solved, but I came to the conclusion that a trailing " []"
+is probably the best way to indicate that. A trailing "X" alone
+can lead to confusion, when the answer itself has some upcased
+characters near the end and such. A unicode symbol could be used,
+but not every keyboard makes it easy to use that, so trailing
+[] seems better. The other variants, such as [skip] or [done]
+seem too long.  
+
+To query **where** the last exam question will be stored, use
+this method:
+
+    Studium.file_last_question_asked? # => "/root/Studium/last_question_asked.md"
+
+This could be used if you forgot which question was the last one
+that was asked; or to automatically solve this question, via 
+other scripts in the **studium gem**.
+
+There is a very important file, called **lecture_information.yml**.
+
+Since that file is so important for the Studium project, a toplevel
+instance variable keeps track of the path to this file (the **location**
+to that file):
+
+    @file_lecture_information = nil # nil here means "not yet initialized to any value"
+
+On my home system and home setup, I also keep all exam-files stored in a
+specific location, which is revealed via:
+
+    Studium.file_exams? # => "/home/x/studium/YAML/exams.yml"
+
+The path to this can be modified via:
+
+    Studium.set_file_exams()
+    Studium.set_file_exams(insert_path_here)
+
+The Studium gem defaults to the UTF-8 encoding. As we require a bit
+of flexibility here (some users may want to use another encoding),
+the toplevel variable called **@use_this_encoding** stores which
+encoding is to be used for all code and data within the studium
+gem.
+
+To query the current encoding in use, try this method:
+
+    Studium.encoding?
+
+## Exam dataset
+
+The **individual exam topics**, such as for **genetics** or **physics**
+are stored in the subdirectory called <b>exam_topics/</b>.
+
+I distribute the dataset for the topics that I have an interest in
+with this gem, which explains why the gem is quite large. This dataset
+will probably not be very useful for other people - after all you 
+may not necessarily share my own interest in different topics - but 
+if you want to use this project (such as for a base-system, and then
+modify and adapt it to your needs) then you are very much encouraged
+to build up your own dataset, anyway.
+
+The primary reason as to why I have distributed my own dataset with
+this gem is to simply show how it can be done; it is just more
+convenient that way in the event that other people want to use the
+project and adapt it to their own needs. It makes it easier for
+people to figure out how to work with the project, by adding new
+questions. And, of course, since I use the gem almost on a daily
+basis, I polish the existing set of exam questions, so there is
+some **quality control** ongoing here as well.
+
+The **format** for these exams must be a **simple** one, that is - **one
+question and one answer per registered line**. I currently encourage
+you to use not more than **1000 question-answer entries per such a file**,
+as it becomes unwieldy otherwise, but if you want to, you can ignore
+this limitation as well. I just personally found it useful to have.
+
+Whenever I have more than 1000 questions, I tend to **create a new
+file** with "advanced" exam-questions, or simply split things up
+in several different files. I did so for the metabolic pathways,
+for instance, such as for glycolysis, the citric acid cycle,
+and so forth. This started with a single file for **biochemistry**. Since
+then I split it up into several sub-topics, such as **metabolism**,
+**advanced biochemistry** and **aminoacids**, so the total question-answers
+for biochemistry is close to about 4000 as of now. (It may be even more
+than that if you also include molecular techniques and genetics into the
+field of **biochemistry**, which some university lectures may do. But I
+found it easier to use separate topics here, such as **genetics**,
+**genomics** and **gene technology** instead.) 
+
+If you want to **query** which exam-topic is the current default (the
+<b>current studyset</b>), then you can use the following invocation
+on the commandline:
+
+    studium --current-studyset?
+
+**How to best prepare for exams?**
+
+This probably depends on the type of person you are, how your brain works,
+how you memorize content. I can not give a general recommendation as to
+how that should be for everyone - you need to determine this on your 
+own, for your particular case at hand.
+
+But - what I believe may work very well for many different people, are
+so called "flash-cards", that is: you have the question on one side,
+and then the answer or answers on the other side of that card
+(flip card). For looking at the answer you simply flip around the
+card.
+
+In my opinion, such mnemo cards or flash cards, are **quite effective**
+and may also work for you. This was the primary goal for the studium
+project too; it was built around that central concept for the most
+part, at the least in regards to **exam questions**.
+
+Note that the python-software **anki** (anki cards) uses a somewhat
+related concept, although it is more sophisticated, e. g. you can
+embed images into the dataset, and so forth.
+
+## Flashcards (deprecated and removed)
+
+Since as of **March 2018**, the studium project also supports
+flashcards formally.
+
+Flashcards are **mnemonic-cards**, where a question may be on the
+front of a paper, and the answer to that question is on the backside.
+
+Obviously computers can simulate this more easily without wasting
+paper - but some people may prefer oldschool paper for memorizing
+content.
+
+At any rate, if you wish to add a new question-answer, then you
+can use this commandline invocation:
+
+    flashcards add
+
+You can also add a new question via the bin/studium file:
+
+    studium --add-a-new-question
+
+Internally this will call class <b>AddExamQuestion</b>. As of
+October 2020 I am not sure whether the namespace Flashcards
+will be retained, though. We may have to look how useful these
+flashcards are; at a later time it may be decided what to do
+with that, but it could be removed as well.
+
+In March 2022 support for flashcards in the above described
+manner has been removed. Exam-question cards are similar to
+flashcards, so the functionality is not completely gone - 
+but it is gone in the sense of "flashcard-centric design".
+
+## The main dataset (Studium.main_dataset?)
+
+The file called **lecture_information.yml** is the most important
+yaml-file in this project. It stores all lectures that are tracked
+by the studium-gem.
+
+Loading a big yaml file can take some time. Having to do so again
+and again may really slow down a project; it also makes little
+sense to want to do so, because you already had to load it up
+before, so why do it again?
+
+Due to this situation, it seemed to make sense to allow a way to
+store the dataset in an instance variable on the toplevel
+namespace.
+
+    require 'studium/toplevel_methods/main_dataset.rb'
+    dataset = ::Studium.main_dataset? # ← Store it in a variable if you would like to.
+
+## lecture_information.yml
+
+The file <b>lecture_information.yml</b> is extremely important and rather
+central to the studium gem, so this subsection will detail the rationale
+for this file and what information can be found in that file.
+
+The file **lecture_information.yml** is distributed as part of the **studium
+gem**, in the <b>yaml/</b> **subdirectory** specifically. You can have a
+look at it if you don't quite know the structure; perhaps use the editor
+nano or vim or emacs for a quick look.
+
+In order to obtain the **full path to this file**, via the commandline,
+the following command can be used (**commandline instruction**):
+
+    studium --path-to-file-lecture-information
+
+Essentially, lectures of universities can be **registered** in that file.
+
+The basic **format** of that file is quite simple:
+
+- The first line of every lecture-related entry, within enclosed "" quotes,
+constitutes the **name** of the lecture. <b>Make sure that the name is
+exactly, 1:1, the official name of the lecture at hand.</b> Make sure
+that the name really is the name of the lecture, too - awkward errors
+may otherwise be the consequence. From experience I can tell that the
+more accurate the dataset is in that yaml file, the better.
+
+Then, **additionally**, you must **prepend* the LV ID as the first entry
+in that particular line.
+
+Complete example for this follows:
+
+<b>"301617 Strukturbiologie I":</b>
+
+So - first comes the particular **LV ID** entry and then comes the
+**name of the lecture**.
+
+This is the **main entry** for that lecture in the **.yml** file.
+
+Then, you can denote the content of the lecture at hand, via a
+Hash. You can use !ruby/symbol to use a symbol; it is a yaml file
+after all, with all pros and cons that come with it.
+
+The **three main entries** are presently:
+
+    !ruby/symbol ects: 3.0
+    !ruby/symbol university: BOKU
+    !ruby/symbol language: german
+
+More information can be added to describe the particular lecture
+at hand. See the file
+**studium/doc/documentation_for_the_file_lecture_information.md**
+for more information pertaining to this.
+
+Why is this information about the available lectures so important?
+
+The information stored in the file **lecture_information.yml** is
+important because it allows us to automatically calculate the ECTS
+points in a given curriculum, and also keep track whether a
+particular exam has already been passed successfully. (The latter
+part has to be adjusted to your own exam-dataset of course;
+it makes no sense for others to re-use my own dataset, as 
+that is specific to my use case. Obviously different people
+will have totally other use cases.)
+
+Some **helper classes** exist to sanitize or check the validity
+of the information contained in that file. For example,
+<b>class Studium::AutopurgeThisLectureDate</b> can be used to
+purge outdated lva-entries from the file, allowing you to
+more easily stay up-to-date with ongoing lectures.
+
+(Obviously, for all of this to work, you need to have a
+file that keeps track of these different lectures in the
+first place.)
+
+You can also check the validity of the file lecture_information.yml,
+from the commandline, through 
+<b>class Studium::CheckTheLectureInformationFile</b>. This
+is described in the subsection <b>checks and sanitizing
+information</b>, in this document.
+
+Note that you can also directly load the dataset from this file
+via the following method:
+
+    Studium.lecture_information
+
+## class Studium::FinishedExamsAtThisUniversity
+
+class Studium::FinishedExamsAtThisUniversity can be used to show
+which exams at a university have been passed successfully.
+
+    require 'studium/utility_scripts/finished_exams_at_this_university.rb'
+    Studium::FinishedExamsAtThisUniversity.new(ARGV)
+    Studium::FinishedExamsAtThisUniversity.new('uniwien')
+    Studium::FinishedExamsAtThisUniversity.new('tu')
+
+Note that there are a few other classes that have a similar
+functionality. It just seemed useful to also have an additional
+class that is dedicated to that particular task.
+
+## Regex-search for exams
+
+You can search for passed exams via a "pseudo-regex", aka // 
+in a string:
+
+    studium /Partial name of exam goes in here/
+    studium /Elektronen/
+    studium /Bioinf/
+
+Let's look at the last example, on the commandline. This will
+send the first argument <b>"/Bioinf/"</b> to the ruby code that
+handles the commandline. ARGV is an Array that will hold the
+arguments given to a ruby .rb file as Strings, so we have a
+pseudo-regex there - a String object that starts and ends with
+the character '/'. We assume this String to be a regex, which
+conveniently allows us to query for the name of passed exams.
+
+This may be helpful if you want to find all exams that you have
+passed successfully (and registered somewhere) but do not quite
+remember the full name of the exam. Or, as in the last example,
+to show all exams passed with a title that includes "Bioinf"
+(meaning **Bioinformatics** or **Bioinformatik**).
+
+Of course this should be tailored to your exams, not mine or
+anyone else's exams. :)
+
+You can also see the passed exams that belong to a given theme.
+
+So for example, to show all exams that fit to the theme
+"chemistry", you can use this call to output these exams:
+
+    studium --passed-exams=chemistry
+
+## Flashcards / Mnemo-cards
+
+The core of the studium project is to simulate the behaviour of
+mnemo-cards, memo-cards or flashcards (we will assume these names
+to be all <b>synonymous</b> to one another).
+
+The project can thus ask the user a **random exam question**.
+
+Then, if the correct answer to that exam question has been given,
+this question can be marked as "solved" - the code for the
+latter solved action resides in the file called **solved.rb**.
+It can be used from the commandline, or simply use 
+**bin/solved** which provides this functionality.
+
+Any exam question that has been marked as "solved" will no longer
+be within the total pool of questions that the computer will ask
+the user.
+
+In other words, we can toggle on/off on a per question basis, via
+a <b>trailing []</b> to a line in that file.
+
+This allows you to systematically work through an exam dataset for
+a given topic at hand.
+
+Currently there is a cap in effect - 1000 questions to the same topic,
+not more than that. This was mostly because I found it better to split
+up the topics, e. g. "basic chemistry", and then "advanced chemistry",
+and so on and so forth.
+
+The exam dataset that I use myself is distributed with the studium
+gem, but it is probably not very useful to other users. I recommend
+that you maintain your own exam dataset - this will be much better
+suited to your own needs, so me providing my own exam dataset is
+mostly meant to serve as a "starter" for other people to do the
+same.
+
+## class Studium::AutoStud
+
+The class AutoStud can automatically modify the cd_aliases yaml
+file. cd_aliases are part of another project and bundle together
+my cd-aliases, that is - aliases that help me navigate through
+my local filesystem quickly. I make heavy use of aliases in 
+general.
+
+If there is a file called exams.yml, then we can put numbers,
+so called "tag-identifiers", into these. So for example, we
+may have the entry '# === (13)' there. This means that 
+pwdstud13 is an alias to this directory, which will correspond
+to an exam entry. These entries should be sorted in a way so
+that entry 1 means the next upcoming exam, entry 2 the one 
+after that, and so forth and so on.
+
+In the past, before 20.01.2018, I manually did most of the
+work there - first, by modifying exams.yml, and then by
+navigating towards the target directory, and then invoking
+"newstud NUMBER" here, such as newstud 13. This was tedious
+and somewhat error-prone, but mostly unnecessary. I then 
+created class AutoStud, which allowed me to navigate to
+the directory at hand, and just take the name of the working
+directory to determine the number. But even that was too
+cumbersome, so I added a range specifier, such as:
+
+    autostud 1-15
+
+This will, similar to a Range in ruby, work through from 1
+to 15, and invoke class NewStud. This class is the one 
+that will modify the cd-aliases file.
+
+Even the range specifier was unnecessary since I added:
+
+    autostud --max
+
+This will automatically guess what is the max entry and use
+that.
+
+If the above subsection is a bit confusing, don't worry, it
+really is simple once you understand it. It essentially
+serves two purposes:
+
+    (a) to be able to show which exames are upcoming, via
+        say, <b>d25</b> (see bin/d25 for that)
+    (b) to just quickly navigate to these directories
+        for upcoming exams
+
+I can then e. g. do "to4" to navigate to exam number 4
+and look at the directory as to what material has been
+collected for this exam.
+
+Obviously this works for the exam dataset on my system -
+you may have to maintain your own exams.yml file. I am
+willing to make improvements to this part, both in 
+regards to code, but also in regards to the <b>documentation</b>.
+
+## Determine which curricula are used for which lecture
+
+One of the most important files for this project, file
+<b>lecture_information.yml</b>, also contains the assigned
+curricula for a given lecture at hand.
+
+The class <b>Studium::DetermineCurricula</b> can then be used
+to automatically output, on the commandline, in which curricula
+a certain lecture is listed. This allows us to batch-calculate
+the curricula used in an individual curriculum - e. g. if you
+design such a curriculum, the class may help you to
+automatically output from which other curricula certain lectures
+were used/re-used. This constitutes the <b>"statistics"</b>
+part of that class.
+
+## class Studium::ForeignLanguagePercentage
+
+class <b>Studium::ForeignLanguagePercentage</b> can be used
+to show which lectures are in a given language, such as
+the english language.
+
+This requires that the entry called "!ruby/symbol language: english"
+in the file <b>lecture_information.yml</b> has been set.
+
+## class Studium::ShowLecturesOnTheCommandline
+
+This class will show lectures that are part of the given
+curriculum on the commandline. Additionally, a .html file
+can be autogenerated (and will be opened in the browser,
+if a certain constant has been set to true).
+
+If a lecture has already been passed, then the remote URL
+will not be shown. This behaviour can be overruled from
+the commandline like so:
+
+    show_lectures_on_the_commandline --show-all-URLs --tuwienbiotech
+
+This will show all remote URLs, even for lectures that were
+already solved.
+
+Do note that you can also design any arbitrary "curriculum"
+on your own, and then load this dataset up.
+
+Say that you have stored this into the file called **foo.md**.
+
+To load this up, you can do:
+
+    studium --use-this-curriculum=foo.md
+
+Remember to use only registered lectures (in the file
+**lecture_information.yml**), and only one lecture per
+line in that .md file (or any other text file).
+
+## class Studium::ShowLectures
+
+<b>class Studium::ShowLectures</b> will show lectures according
+to a particular <b>theme</b>. For example, say that you want to
+see all lectures that have something to do with
+<b>"analytical chemistry"</b>.
+
+You could then invoke this class and pass in a commandline option
+such as the following one:
+ 
+    --analytical_chemistry
+
+I have aliased the <b>show_lectures.rb file</b>, to the alias called
+<b>show_lectures</b>, and then I can do this from the commandline:
+
+    show_lectures --analytical_chemistry
+
+(Actually, I even have this aliased, to "tanalytical" - the <b>t</b> stands
+for "theme". I use this for all the themes, e. g. "tgenetics" for all themes
+belonging to the theme genetics, "tinformatics" for all themes belonging
+to the theme informatics, and so forth.)
+
+This class will also show a split between bachelor and master lectures.
+Bachelor lectures are shown first, then we will show the lectures belonging
+to a master curriculum.
+
+This class thus allows us to quickly find out which lectures belong to a
+certain theme. It can then help when you wish to create an individual
+curriculum based on one or several <b>certain themes</b> - or when you
+simply want to see which lectures are available belonging to a particular
+theme. (I used it to see which exams I may do next, to fulfil a certain
+theme criteria.)
+
+Note that this class acts on information, which must have been added prior
+to the file <b>lecture_information</b>, which is also distributed with
+this project. Always keep that file up to date - a lot of code in this
+project depends on that file.
+
+Since as of <b>10.03.2018</b>, you can also pass in the options --timetable
+or --upcoming. This will then autogenerate a .html file listening the coming
+exams. That functionality depends on class <b>ShowLecturesOnTheCommandline</b>.
+
+## class Studium::Exams::Cycle
+
+The class <b>Studium::Exams::Cycle</b> can be used to
+cycle through the yaml file that holds which exams may
+be upcoming.
+
+Since as of <b>March 2018</b>, the yaml file is distributed with the studium
+gem and can be found in the respective yaml directory, such as at:
+
+    studium/yaml/current_exams.yml
+
+Obviously if you wish to make use of it, you will have to modify that
+file to fit your own preferences rather than mine. This also depends
+on the exam topics that you want to be exercising next.
+
+The way how the class operates is really simple:
+
+- After having asked one question from the current main 
+topic, the class will move towards the next topic at
+hand, and so forth. When it reaches the "end", it will
+resume at the beginning, so in other words this is a
+cyclic array and the class operates via a "cyclic modus
+operandi" - which thus explains he name of this class:
+<b>Cycle</b>.
+
+If you want to find out where the main .yml file resides,
+you can do so via:
+
+    Studium::Exams::Cycle.main_file?
+
+If you want to display which entries are part of the current exam-cluster,
+you can do so from the commandline via:
+
+    studium --collage?
+
+## class Studium::ShowOutdatedLvaDates
+
+<b>class Studium::ShowOutdatedLvaDates</b> can be used
+to show which lectures (lva aka "lehrveranstaltung")
+have outdated lva_dates entries.
+
+That way the outdated entries can be updated (or removed).
+
+This then allows other classes in the project to more
+reliably show only lectures that are up-to-date.
+
+You can also query this from the commandline via the <b>bin/studium</b>
+executable, by issuing:
+
+    studium --outdated
+
+## class Studium::ShowLecturesOnThisDay
+
+This class will show all lectures that occur on a given day. The format
+for that day must be in dd.mm.yyyy format such as <b>18.06.2018</b>. (In
+the future this requirement may change and allow for other formats, such
+as yyyy.mm.dd; but for now, this is the only supported time format.)
+
+The class will then proceed to check the file <b>lecture_information.yml</b>
+for matching entries. If found, they will be retained and lateron displayed,
+via the <b>.report</b> method.
+
+You can either invoke the clas directly - it resides at 
+<b>studium/utility_scripts/show_lectures_on_this_day.rb</b> - 
+or you can invoke this functionality from the commandline.
+
+The syntax for the commandline invocation can be in two formats.
+
+    studium --lectures-on-this-day=05.05.2018
+    studium 07.05.2018
+
+The latter is significantly shorter and is recommended. It is the
+current default action for input in the form dd.mm.yyyy. Do note
+that this may, however had, also change in the future - but for
+now (<b>March 2018</b>), this is the documented default behaviour for
+input like the above. Use the more explicit one with the --
+flags, since that one will be supported forever.
+
+## class Studium::NExamsInTheseTopics
+
+class <b>Studium::NExamsInTheseTopics</b> can report how many exam
+topics are registered in the given input-topics at hand, and how many
+of these were solved.
+
+Several topics are combined together.
+
+For example, for basic **biochemistry**, you can pass the argument
+<b>meta_biochemistry</b> to this class, as a **String**.
+
+class **Studium::NExamsInTheseTopics** will then output how many
+questions were registered in that topic in total, and how many of
+these questions were already solved.
+
+For the "meta-topic" meta_biochemistry, we group together many
+biochemistry-related topics - basic biochemistry, advanced
+biochemistry, structural biology, proteomics, metabolism,
+enzymes, glycolysis and so forth.
+
+I created this class so that I can have a look at combined topics.
+Otherwise it is quite similar to the statistics shown when a single
+question is asked on the commandline, through <b>class AskExamQuestion</b>
+(full name is: <b>Studium::Exams::AskExamQuestion</b>).
+
+Since as of <b>August 2018</b>, you can also use this as exam-trainer,
+by providing the number of the sub-topic at hand.
+
+So for example, if the main topic is meta-genetics, and you pass in
+the argument 3, then the entry at the 3rd place will be used as means
+to ask a question.
+                 
+Examples:
+
+    metagen 2
+    metagen 5
+
+Where "metagen" is my alias to:
+
+    n_exams_in_this_topic meta_genetics
+
+By default, lines that end via "[]" are ignored, but you can also
+ask a question from ALL available questions, even if they end
+with a "[]" token.
+
+Commandline example:
+
+    ask_exam_questions amg1 --all-questions
+
+This would ask a random question from the **amg1-dataset**.
+
+## Studium.pristine
+
+The toplevel-method made available through <b>Studium.pristine</b> can
+be used to create a new <b>lecture_information</b> file, from scratch.
+
+The one that is, by default, bundled with the studium-gem is/was tailored
+to my own needs and use case. So if you want to use the file, it may be
+better to generate it once, and then modify that newly generated file on
+your own. (Don't forget to keep a backup of it available as well, in case
+it is deleted or overwritten accidentally.)
+
+Note that you can invoke **Studium.pristine()** via the commandline as
+well, via:
+
+    studium --pristine
+    studium --new-lecture-information
+
+You can then copy this file into the default location, where the file
+<b>lecture_information.yml</b> is normally stored, via:
+
+    studium --merge
+
+## Commandline examples of the studium gem
+
+This subsection shows some commandline examples, in a succinct
+manner.
+
+Display **bachelor curricula**, via the syntax --bachelor=NAME_HERE
+
+    studium --bachelor=vektorx
+    studium --bachelor=genetics
+
+Display **master curricula**, via the syntax --master=NAME_HERE
+
+    studium --master=vektorx
+    studium --master=immunobio
+
+Note that in both cases, the curriculum has to be registered.
+
+If you wish to see which exams have been passed, that is,
+completed successfully, then use this invocation style:
+
+    studium --passed-exams?
+    studium --passed-exams
+
+If you want to show how many ECTS points have been completed
+in the registered curricula, do either of the following:
+
+    studium --passed-ects?
+    studium --passed-ects
+
+To show how many question-answers I added per year, on my
+own exam dataset, this can be used:
+
+    studium --questions-per-year
+
+## Studium.return_div_timetable_of_upcoming_exams
+
+This module-method can show the upcoming exams, as a html table.
+
+This allows you to look at the upcoming exams in a <b>browser</b>.
+
+The priority of the given lecture must be among these values:
+
+    1, 2, 3, 4, 5
+
+Thus, a priority value of higher than 5 will <b>not</b> be
+shown/considered. 
+
+## Aliases
+
+The studium-gem uses several aliases. These exist mostly for
+convenience.
+
+For example, bin/studium has an entry point called <b>--master-curricula</b>.
+This variant also works via <b>--master</b> alone. The latter option
+is not explicitely mentioned since it is just an alias. If you think
+that a specific alias is missing, let me know and I will add it (as
+long as it does not conflict with any other entry point.)
+
+## Return all passed exams
+
+If you need to obtain a list (an <b>Array</b>) of all exams passed,
+you can use any of the following two methods:
+
+    Studium.all_passed_exams
+    Studium.return_all_passed_exams
+
+On the commandline, you can invoke this via:
+
+    studium --passed-exams
+    studium --all-passed-exams
+    studium --return-all-passed-exams
+
+Note that this will <b>only</b> honour exams that have been
+registered in the file <b>lecture_information.yml</b>.
+
+To show how many ECTS you have passed in all curricula,
+use this method:
+
+    Studium.show_passed_credits_per_curriculum
+
+## curricula.yml and registered curricula
+
+The file <b>curricula.yml</b> collects the <b>id-numbers</b> of different
+bachelor/master curricula, from <b>different universities</b>, in
+<b>Austria</b>. It can be found under the <b>yaml/</b> subdirectory.
+
+In theory this file could be extended to also include EU-wide curricula
+listed, but I only limited it to my own potential use cases or that of
+(former) colleagues.
+
+If other people want to add different curricula numbers, subdirectories
+may have to be created for each country - but for now, since nobody else
+may need more curricula, the current structure will remain as it is.
+
+Do also note that within the <b>yaml/ subdirectory</b>, there is another
+directory called <b>curricula/</b>. The latter directory includes
+several curricula with the respective lectures that belong to
+this particular curriculum. These files are used to keep track of
+which lectures are part of these curricula and whether you have already
+successfully passed these or whether you have not.
+
+## Improving this project
+
+If other people would like to make use of this this project, I am open
+for suggestions on how to make it more flexible.
+
+Otherwise, I will just keep it here as it is, as I do (or rather, did)
+require it in a few of my other projects. And if nobody else uses it
+then this is also fine because I used to be the number one user here
+anyway - the project had to solve existing problems, and it did so
+fairly well. Extra work past this point (in the year **2018**) is
+mostly done just to polish existing functionality, and to add a
+tiny bit of new functionality every now and then, or to improve the
+documentation. :)
+
+I am also adding some code now and then for GUI and www-related use,
+as this interests me personally; but other than that, I consider the
+project mostly "done" in regards to time investment.
+
+## The method obtain_this_value_from_hash()
+
+This method resides in the file <b>studium/base/base.rb</b>.
+
+It was created in order to access the main Hash - that is, the
+Hash that is returned from the file <b>lecture_information.yml</b>.
+
+I had to access the various entries from said file and this was
+becoming a bit tedious. It became even more tedious because some
+keys are Strings and some keys are Symbols. Since I did not want
+to look up all the time whether I am dealing with Strings or 
+with Symbols, I transitioned into using that method instead.
+
+It is thus a bit similar to <b>HashWithIndifferentAccess</b>, except
+that it is just a simple method (and the main name is actually
+<b>obtain()</b>).
+
+## Download the exam dataset
+
+You can download the exam dataset by making use of this commandline
+option:
+
+    studium --download-exam-dataset
+    studium --download-dataset
+
+This will copy into the exam_topics/ subdirectory, so make sure
+that you want this BEFORE calling the above. If in doubt, backup
+your exam dataset and store it elsewhere on top of that (which
+may be a good idea in general).
+
+## class Studium::ShowLecturesOfThisCurriculumId
+
+**class Studium::ShowLecturesOfThisCurriculumId** can be used to output
+all lectures that **belong to a particular curriculum ID**. That way
+you can see which lectures could be done for a particular curriculum;
+and which lectures have already been passed in this curriculum, too.
+
+You can input either the curriculum ID to this class; or some
+shortcuts.
+
+The following input works on my home system, where 
+show_lectures_of_this_curriculum_id is alias to the .rb file that
+holds **class Studium::ShowLecturesOfThisCurriculumId** can be used to output:
+
+    show_lectures_of_this_curriculum_id 066875
+    show_lectures_of_this_curriculum_id Bioinformatik
+    show_lectures_of_this_curriculum_id MolBio
+    show_lectures_of_this_curriculum_id Landschaftsplanung
+
+## Description of lectures
+
+Some lectures are described in the file **lecture_information.yml**, but not
+all are. I have described only some which were of relevance to me. Most of
+these descriptions are in german, because the teaching language for most of
+these lectures is in german.
+
+If you ever want to add your own descriptions, you can do so, by populating
+the entry called:
+
+    !ruby/symbol description: |
+
+## KDE Konsole support
+
+In the past we could rename KDE Konsole tabs, but this behaviour is presently
+(November 2018) slightly buggy. I have thus disabled it.
+
+It may be re-enabled one day in the future, but via a configuration setting,
+so that users can disable/enable it. By default it will then be disabled. 
+
+## Studium::PassedEctsPerYear
+
+If you need to find out how many ECTS points have been passed per given
+year for a particular curriculum then you can use class
+**Studium::PassedEctsPerYear**.
+
+The input is the name of that curriculum. Obviously for this to work, the
+curriculum has had to be registered first.
+
+You can also invoke it from the commandline, via:
+
+    studium --passed-ects-per-year
+
+## Display the amount of ECTS points passed in Bachelor/Master lectures
+
+You can find out how many ECTS points were passed in Bachelor and
+Master lectures so far via:
+
+    studium --ects-bachelor-master
+
+## Using an environment variable to specify your replacement for lecture_information.yml
+
+Some people may wish to use the project but wish to use another .yml
+file, other than the default one called **lecture_information.yml**.
+This is normally done so that you can, for example, add your own exam
+dataset into this .yml file (and have it persistent, that is, stored
+somewhere else on your filesystem, rather than use the bundled
+variant that comes distributed with the **studium** gem itself).
+
+For people who require this, there exists an **environment variable**
+called **STUDIUM_FILE_LECTURE_INFORMATION**. Simply assign to this
+variable the full path to your dataset, which must be a .yml file
+in the same format.
+
+Example for bash:
+
+    STUDIUM_FILE_LECTURE_INFORMATION=/opt/foo/bar.yml
+
+## class Studium::ShowCompletedEctsInAllCurricula
+
+**class Studium::ShowCompletedEctsInAllCurricula** can be used
+to show the completed ECTS per curriculum, sorted by n ECTS (maximum
+amount of ECTS) first. This is really just an "overview" class that
+shall quickly tell you how many different curricula exist.
+
+A threshold value ("cut off") exists, which is set to 5.0 ECTS
+by default. Only if you have passed exams worth a total of at
+the least 5.0 ECTS will they be shown. This is set via a constant
+which can be toggled.
+
+## class Studium::ShowConflictingLvaLectures
+
+**class Studium::ShowConflictingLvaLectures** resides at the internal
+location <b>studium/utility_scripts/show_conflicting_lva_lectures.rb</b>,
+within the **studium** gem.
+
+The purpose of this class is to **show conflicting lva-lecture dates**.
+
+For example, say that you want to know whether there are any conflicts on
+the day **16.10.2018** (16th October in the year **2018**). Then you would
+simply pass that string into <b>class Studium::ShowConflictingLvaLectures</b>
+and that class will then display which exams and which lectures are on
+that date, **sorted by time**.
+
+Example:
+
+    conflict 16.10.2018
+
+(I use the alias called **conflict** to invoke that .rb file from the
+commandline.)
+
+The result, on the commandline, may look like this (for another
+day):
+
+<img src="https://i.imgur.com/4YI1Y2k.png" style="margin: 1em">
+
+You can pass in any number of dates in the **dd.mm.yyyy** format, and the
+class will iterate through all of them and report which lectures and
+exams happen on each respective day.
+
+You can use a range of dates too, if you pass in a **-** between two
+such dates.
+
+Example:
+
+    conflict 16.10.2018-20.10.2018
+
+This will be treated as if you would have given input from the
+16th, 17th, 18th, 19th and 20th. That can thus be used as a
+sort of "mini-calendar", on the commandline, in regards to
+important lectures/exams. (Remember that you will have to
+populate and maintain the dataset in the file called
+**lecture_information.yml** for this to work.)
+
+You can also use a few **abbreviations** for **class Studium::ShowConflictingLvaLectures**.
+
+For example, the capital letter **A** is a hardcoded entry that I may
+change to indicate which is the starting day of university in a given
+semster, such as **01.10.2018** or any such day. The capital letter B
+then refers to the day after that day, the capital letter C refers to
+the day after B, and so forth. The idea here is to use just a one-letter
+abbreviation rather than have to input **4 - 10** characters instead.
+
+As already stated in this subsection, the file **lecture_information.yml**
+needs to have these lectures/exams registered first, before <b>class
+Studium::ShowConflictingLvaLectures</b> is able to display them.
+
+Why was this class added? I needed that functionality to plan **exam-dates**
+ahead of time. That way I could display which exams may be upcoming
+and so forth - helped me in regards to **time management**.
+
+## Underline-support for exam questions
+
+You can use **ud**test**/ud** or **u**test**/u** to use underline-support
+in KDE konsole for question-answer combinations. (I can not use tags
+here in markdown, or so it seems, so assume that **ud** stands for the
+corresponding tag.)
+
+## Studium::ShowLecturers
+
+class **Studium::ShowLecturers** will show the lecturers of each lecture
+in a given curriculum, on the commandline/terminal.
+
+If an entry is missing the lectures then this will be reported on
+the commandline.
+
+The idea behind this class is mostly to allow you to quickly find out
+which lecturer holds which particular lecture (and when).
+
+It is not a too terribly useful class, though - mostly exists just
+for **sake of completeness**.
+
+## Registered URL entries to the (registered) lectures
+
+Since as of 15.04.2019 (<b>April 2019</b>) it is possible to 
+return the remote URL of a given registered lecture,
+through the **Studium** module.
+
+Let's first show an example for this, including the toplevel API:
+
+    Studium.return_remote_homepage_of_this_lecture "270016 Massenspektrometrie" # => "https://ufind.univie.ac.at/de/course.html?lv=270016&semester=2019S"
+    Studium.return_remote_homepage_of_this_lecture "Massenspektrometrie"        # => "https://ufind.univie.ac.at/de/course.html?lv=270016&semester=2019S"
+
+As you may be able to see, we take a shorter input string, aka the name
+of the lecture at hand, and then return the remote URL for that lecture.
+In particular the second example shows how you can use a partial input,
+and still obtain the current remote URL associated with that course.
+
+This requires that a key called <b>:homepage</b> registered
+exists for that particular lecture in the file
+**lecture_information.yml**.
+
+Right now only a very few lectures contain such an entry, but I
+will extend on this slowly, as time permits. The long term goal
+will be to provide a remote URL to **all** registered lectures.
+(This was already possible through the BeautifulUrl project,
+but I realized that it may be better to a) register this directly
+within the Studium project and b) to not depend on other projects
+if possible).
+
+## Encoding
+
+The default encoding for the **Studium** gem used to be 
+the **encoding ISO-8859-1**, aliased onto the constant
+called **ENCODING_ISO**. This setting (constant) can be found
+in the file **studium/encoding/encodings.rb**
+
+Since as of **May 2019** the default encoding is now **UTF-8**.
+
+In the event that you may wish to use another encoding, you
+can modify the yaml file called <b>default_encoding.yml</b>,
+at **studium/yaml/default_encoding.yml**. Simply add the name 
+of the constant there.
+
+The reason why I personally used **ISO-8859-1** as encoding is because
+german umlauts can be a hassle under UTF when combined with an
+old editor I used to use. I finally abandoned that editor in 2019
+and am now using another editor, so it was also possible to
+switch to UTF-8. Unicode/UTF has quite a massive
+<b>intrinsic complexity</b>, but it also has some useful things,
+such as emojis and unicode characters, which can be used on the
+terminal in a colourized manner. That was actually the primary
+reason why I switched into UTF-8, as odd as that may sound.
+
+The Studium project will continue to allow any other encoding
+though, as long as it is supported by ruby itself.
+
+For the time being, there also exists a commandline way to change
+the encoding in use for the Studium project.
+
+    studium --encoding=utf
+    studium --encoding=iso1
+
+If you are fine with UTF-8 then obviously you do not have to change
+anything.
+
+## Studium::SolvedEctsPerUniversity
+
+If you have solved ECTS credits at different universities, and
+registered this in the file **lecture_information.yml**, then
+this class will give a little summary on the commandline as to
+the number of ECTS points solved at different universities.
+
+## Logging activities done within the Studium project
+
+The **Studium project** will try, by default, to log a lot of
+information that may be useful in some cases. This is not a
+trivial task, because there are many different classes that
+make up this project.
+
+The paragraph here aims to explain some of the rationale behind
+the logging.
+
+class **Studium::Log::StoreLastQuestionAskedIntoFile** will store
+the last exam-question asked into a file, together with the time
+stamp. This can then be used to answer questions such as "have I
+already asked myself this question today?". So this may help
+for training purposes, e. g. when you wish to acquire some knowledge,
+and learn for new questions that way.
+
+## Studium.find_corresponding_exam_topic
+
+The toplevel method <b>Studium.find_corresponding_exam_topic</b> is
+mostly a convenience method. It will accept an input, ideally
+a **String**, and return back the **official, registered name
+of the particular exam topic at hand**.
+
+For example, 'genetik' as input to this method will become
+'allgemeine_genetik', which is also the locally existing
+name for the exam-file at hand.
+
+The idea behind that method is that we can take a shorter
+input, and still obtain the real filename. This is convenient
+because you can type just a few characters, and have the
+name of the exam-file returned. It allows us to be lazy here.
+
+This is especially useful on the commandline, but it is also
+useful to aggregate it together in different ruby files of
+this project, and present a "unified" API for this topic.
+
+Note that since as of 09.11.2019 (9th of November), the number of
+available exam-topics as part of this project are calculated
+automatically. Prior to that a constant was used that was
+hand-counted manually by me, which was too tedious and error-prone -
+so the new approach should work better for more exam topics in
+the future. 
+
+## Studium.find_corresponding_exam_title
+
+The method <b>Studium.find_corresponding_exam_title()</b> can be used
+to return the full, spelled out name of the exam topic at hand.
+
+Let's showcase two examples next - these may explain what this method
+does more succinctly so:
+
+    title = Studium.find_corresponding_exam_title('technische_grundlagen_der_informatik') # => "Technische Grundlagen der Informatik"
+    title = Studium.find_corresponding_exam_title('mphysio') # => "Mikrobielle Physiologie"
+
+As can be seen, a short input, such as **mphysio**, will be translated
+into **Mikrobielle Physiologie** properly. I needed this in order
+to show the exam topic at hand; showing **mphysio** was not as
+useful as showing **Mikrobielle Physiologie** instead (which,
+by the way, is german for **microbial physiology**, that is
+metabolic pathways used by microorganisms).
+
+## Studium::Exams::PushSolvedQuestionsOnTop
+
+**class Studium::Exams::PushSolvedQuestionsOnTop** has a very simple
+objective: it will move all lines ending with ' []' to the top of
+a given file, if at the least one ' []' is encountered in that
+file. Note that "top of the given file" specifically excludes
+comments, that is lines starting with **#** in that file, and the
+first line after that '#' comment, which is just a newline for 
+readability reasons usually.
+
+The idea behind this class is really just to be able to quickly
+reshuffle all solved questions towards the top of the file;
+the unsolved questions will then be at the bottom of the file.
+
+I needed this functionality because it allows me to quickly
+re-structure existing question-answers, into different 
+topics/themes.
+
+On my home system, I aliases it to <b>ontop</b> simply.
+
+## Display the upcoming exams, via the timetable
+
+You can show the list of <b>upcoming exams</b> via:
+
+    studium --timetable
+
+Note that this makes use of the information stored in the file called
+<b>lecture_information.yml</b>, which has to be maintained by someone.
+In this case, I am still maintaining the dataset stored in that
+file (in the year **2019**) - but this may not be the case at a later
+time, so ideally someone else should be able to maintain that file,
+or just anyone. I will add sufficient documentation to explain what
+has to be done, in order to maintain that single file.
+
+At any rate, the class that is responsible for interpreting the dataset
+stored in that .yml file, is **class Studium::Exams::UpcomingImportantExams**.
+
+This is the very same class that is invoked by issuing
+<b>studium --timetable</b>.
+
+The exam dates should ideally follow the **dd.mm.yyyy notation**,
+that is <b>day.month.year</b>.
+
+An example will be given next. Say that you have a course called
+<b>Physics for Engineers</b>. Two exams for this course are upcoming,
+which you may wish to **register** in the above-mentioned yaml
+file, like in such a way:
+
+    "Physics for Engineers":
+    - "02.02.2018"
+    - "02.03.2018"
+
+The above means that the next exam for the course "**Physics for
+Engineers**" will occur at the beginning of february; and then
+the next exam will be at the beginning of march, and so
+forth. You should sort this by date.
+
+In the .yml file, the exam-related entries are called
+<b>exams:</b> and should denote an **Array**.
+
+Once the exam has been registered like that,
+**class Studium::Exams::UpcomingImportantExams**
+will make use of the information. That's about it for
+that class. :)
+ 
+## Graphviz: generating module dependencies
+
+Since as of December 2019 it is possible to generate a module
+dependency image (as a .png file). This depends on the project
+called **ImageParadise**, and on the program called graphviz.
+
+The code works, but it is not really optimized or very flexible.
+Consider it more as a proof-of-concept for the time being -
+perhaps in the future this may be extended.
+
+(Note that most of the code for this can be found in the
+image_paradise gem; the studium gem only generates the
+Hash that is passed into image_paradise, and it is
+then the responsibility of image_paradise to generate
+the image file at hand.)
+
+## Evaluating the progress in different curricula
+
+You can evaluate your progress in different curricula via class
+<b>Studium::CurriculumComparer</b>. This class resides within the
+<b>statistics/</b> subdirectory of this gem.
+
+In order for this class to work properly, all your successfully completed
+lectures have to be registered in the file <b>lecture_information.yml</b>
+prior to using that class. (Thus, you need to use your own dataset,
+but this is the only sensible thing to do; it would not make a lot of
+sense for you to use my dataset, since that makes no sense for 
+**your** particular progress in your own studies. People will have
+to maintain their own dataset here.)
+
+The class will then output which curricula have the highest amount
+of successfully completed ECTS points, sorted first. That way you
+can assess how far you have gotten in this or that curriculum so
+far.
+
+## Deprecations within the Studium gem
+
+This subsection may eventually contain deprecations within the
+Studium gem itself.
+
+- class Studium::Exams::ShowExamThemes was deprecated on
+01.06.2020; most of its functionality was integrated into
+class Studium::Exams::ShowThemes. The new code is better
+than the old code, in my opinion. Less confusing.
+
+The file **participating_in_these_courses.yml** was removed.
+Users now have to designate whether they participate in a
+university course with the corresponding LV-entry in the
+file **lecture_information.yml**.
+
+The two constants **STORE_LAST_QUESTION_ASKED_WHERE** and
+**FILE_LAST_QUESTION_ASKED** were removed. Use the toplevel-method
+**Studium.file_last_question_asked?** instead if you want
+to find out where the last exam question is stored.
+
+## Sinatra interface
+
+The Studium project has a small sinatra interface, which can
+be started like this from the commandline:
+
+   studium --sinatra
+
+(If this fails, try to reload again. On my system I have
+tied this to open it in the browser the moment sinatra
+is started, and this takes perhaps two or there seconds.)
+
+Note that the sinatra-interface is fairly minimal, but it
+can be used to display different curricula. Expect this
+to be improved in the long run (past **June 2020**).
+
+## Determining the name of a curriculum
+
+If you have a use case for determining (and returning) the
+name of a curriculum, you can do this:
+
+    require 'studium/toplevel_methods/name_of_this_curriculum.rb'
+
+    Studium.name_of_this_curriculum
+    Studium.name_of_this_curriculum(:indi2)
+    Studium.name_of_this_curriculum(:tu_wien_chem) # => "Technische Chemie"
+
+## class Studium::Exams::UpcomingExams
+
+class Studium::Exams::UpcomingExams can report which exams are
+upcoming, via a HTML table.
+
+## class Studium::Calendar
+
+class **Studium::Calendar** attempts to display which courses are
+upcoming, so that you can plan ahead. It currently works only on
+the commandline, but in the future ruby-gtk bindings and a
+sinatra-web-interface may be added - we'll see.
+
+The main dataset for this class is derived from the file
+called **participating_in_these_courses.yml**. The key
+that is listed there will become the full name.
+
+The class was added in September 2020, so expect things
+to not work pefectly well for the time being - it will
+be improved upon at a later time.
+
+## Showing all STEOP lectures of a curriculum
+
+You can show all STEOP lectures that are in a curriculum.
+
+Issue something like the following on the commandline:
+
+    steop_lectures --curriculum1
+    steop_lectures --curriculum2 # number-input should work
+    steop_lectures --ktww
+    steop_lectures --lbt # Bachelor Biotech-Curriculum at the BOKU
+    steop_lectures --AW # as should abbreviations; AW is "Agrarwissenschaften"
+    steop_lectures_in_this_curriculum --ktww
+
+Where **steop_lectures** is an alias to where class
+**Studium::SteopLecturesInThisCurriculum** resides - usually
+in the file **studium/steop/steop_lectures_in_this_curriculum.rb**.
+
+If you want to show all steop-lectures in the current semester,
+consider using <b>Studium::SteopLvaDates.new</b>.
+
+## Semesterplaner - planning a given semester (half-year) at a university
+
+There is a class that may try to plan ahead for a given semester
+at a university. This class is not very flexible and such but
+the code could be improved.
+
+See:
+
+    require 'studium/utility_scripts/semesterplaner.rb'
+    Studium::Semesterplaner.new
+
+## Display exam statistics
+
+To show the exam statistics, try:
+
+    Studium.show_exam_statistics
+
+## class Studium::ShowLvaDatesOfThisLecture
+
+If you need to show the **LVA dates** of a given lecture at hand, on 
+the <b>commandline</b>, then you may want to use <b>class 
+Studium::ShowLvaDatesOfThisLecture</b>, defined in the file 
+<b>studium/utility_scripts/show_lva_dates_of_this_lecture.rb</b>.
+
+The usage for this class is quite simple - pass in the name of the
+lecture that you are interested in, such as "Primatologie".
+
+If you want to get the most accurate information, then you should 
+ideally also pass in the lecture ID; such as in the above example 
+with "Primatologie", the input string should be in the form of:
+
+    "300227 Primatologie"
+
+We call the "300227 Primatologie" variant as the <b>full
+input</b> and the variant with "Primatologie" alone as
+<b>partial input</b>. If only a partial input is provided,
+then the script will try to be <b>greedy</b> and find as
+many relevant entries as possible. This can be used as a
+feature too.
+
+For example, consider that <b>show_lva_dates_of_this_lecture</b>
+is an alias to the above .rb file, then the following
+commandline use:
+
+    show_lva_dates_of_this_lecture Geneti
+
+would show all lectures that have the tag "Geneti"
+included.
+
+Note that you do not necessarily need an alias such as 
+<b>show_lva_dates_of_this_lecture</b>; you can also invoke 
+it from the commandline, as the following example shows:
+
+    studium --show-lva-dates-of-this-lecture=Primatologie
+    studium --show-lva-dates-of-this-lecture="300227 Primatologie"
+
+To use it in ruby code, try something like this:
+
+    require 'studium/utility_scripts/show_lva_dates_of_this_lecture.rb'
+    result = Studium::ShowLvaDatesOfThisLecture.new("802300 Biological nanosciences and nanotechnology (in Eng.)")
+
+## Expanding time ranges
+
+Consider the situation where a student participates in a lecture
+requiring practical work time, such as by being active in a
+laboratory, with a time schedule requiring the students to
+begin early morning, and work until the late evening, over a
+time period of three weeks. (This is just an example to illustrate
+this subsection here; the *use case* is explained.)
+
+You may see that the school/university displays the specific dates
+online via something like:
+
+    15.10. - 2.11.2020,
+
+**Exactly** like this (this is actually a copy/pasted "real-world"
+example, including the trailing ',').
+
+What does the above mean? Well, it means that the course will
+**begin** at the 15th of october, in the year 2020 (this is
+the dd.mm.yyyy notation which is in general used in europe).
+
+The **-** in between means "up until" and the end date is
+specified to be at the second of november, in 2020.
+
+Since I needed to quickly convert such short, one-line
+dates of a given course into a specific time for use in a
+**calendar-like application**, I needed a class that can output 
+an Array of dates where this course will be held. So, class 
+<b>Studium::ExpandTimeRange</b> was created to tackle this
+problem.
+
+This class will accept such odd input as the last example, and
+then output an Array that can be used in a yaml file, of the specific
+dates, weekend-names associated with that day and the time. This 
+then allows me to quickly copy/paste this into the corresponding 
+yaml file. (I needed to have this expanded to every day because 
+I also visually have to look at that yaml file. For this, it
+does help to have every day listed as-is, rather than specify
+a range such as **02.11-04.12**.)
+
+Internally you can also use the following toplevel-method:
+
+    Studium.expand_time_range()
+    Studium.expander()
+
+Use whichever variant you prefer - the last method is quite short
+though, so you can use it like this:
+
+    Studium.expander('15.10. - 2.11.2018')
+
+This also works over the **commandline**, of course:
+
+    studium --expand-time-range="15.10. - 2.11.2018,"
+    studium --expander="15.10.-2.11.2018"
+
+## Querying whether a student is registered for a particular exam
+
+To query and thus determine whether you are registered for a
+particular exam, use this method:
+
+    Studium.registered_for_this_exam?
+    Studium.registered_for_this_exam? "892104 Physik (LBT)"
+
+Note that in order for this to work, the information has
+to be registered for that particular course, e. g. as
+**registered** - that is typically found right above the
+**exams** setting, if it exists.
+
+## class Studium::GenerateSpreadsheet
+
+The idea for class Studium::GenerateSpreadsheet was to 
+generate a spreadsheet (LibreOffice excel file) for
+individual curricula automatically. This works partially
+in the sense that the generated file is correct, but
+its visual looks are not necessarily ... awesome. If
+you need to use it, I recommend to use this only as
+a blueprint, and make enhancement to the generated 
+file manually.
+
+## Reporting all lectures that match to a specific lecture type
+
+If you need to find out all registered lectures that match
+a particular type, such as 'VO', or 'UE' or 'VO+SE', then you
+can use the following toplevel-method:
+
+    Studium.report_all_lectures_matching_this_lecture_type('VO+SE')
+
+The latter was the primary reason why this method has been
+added; I needed to find out all lecture types that are
+of combined VO + SE style ("VO" for "Vorlesung", "SE" 
+for "Seminar").
+
+## Report how many ECTS were solved per university
+
+This can be done via:
+
+    Studium::EctsPerUniversity.new
+
+Or via the **commandline**, through <b>bin/studium</b>:
+
+    studium --ects-per-university
+
+## Showing the weekly lectures
+
+In order to show the weekly lectures, you can use **class WeekParser**.
+
+## class Studium::UpcomingMandatoryPresenceCourses.new
+
+class Studium::UpcomingMandatoryPresenceCourses.new can be
+used to show the upcoming courses that require your physical
+presence. By default this class will "peek ahead" 40 days
+into the future; this can be modified via the method
+**.set_n_days_into_the_future()**.
+
+You can also invoke this on the commandline via:
+
+    studium --mandatory
+
+## Working with a curriculum
+
+From the ruby side, you can do this:
+
+    require 'studium'
+
+    this_curriculum = Studium::Curriculum.new(:bachelor_vektoren)
+
+## Studium.backup_this_exam_file
+
+The method **Studium.backup_this_exam_file()** may be used from
+various classes, but most importantly it is used by
+**class AskExamQuestion**. The idea here is to first back up
+the **old** exam question file, before making any changes. That
+way you can restore to the prior file, if you ever need to.
+
+## Marking all exam questions of a given topic to solved
+
+If you want to mark all questions of a particular topic to
+"solved" then you can try this:
+
+    qa agrarmarkt --ALL_SOLVED
+    qa agrarmarkt --all-solved
+
+This will solve all topics from agrarmarkt to **solved**.
+
+Internally this will ensure that each line has a trailing
+**[]**.
+
+## Colours
+
+The **colours** within the Studium project are handled in two main ways:
+
+     (1) By an external gem called colours
+
+     (2) Internally in most classes of this project via the @use_colours instance variable.
+
+In other words, if the toplevel instance variable **@use_colours** is set
+to **false** then the Studium project/namespace will not use colours at
+all. That way you can **disable colours** for the whole project. This may
+be useful if you use the project in sinatra or rails and so forth.
+
+In ruby code you could invoke the following method in order to achieve
+this:
+
+    Studium.disable_colours
+
+By default, on the **commandline**, for exam questions and exam answers
+to said question, colours can be defined by the user, through the file
+called <b>studium/yaml/custom_colours.yml</b>.
+
+That file has ***keys*** such as <b>colour_for_answers</b> and
+<b>colour_for_answers</b>, which denotes the colour to be used for
+when a question is asked and an answer to that question is revealed,
+on the commandline.
+
+Currently this defaults to <b>olivedrab</b> for exam-questions and
+<b>lightslategray</b> for exam-answers, but you can use any other
+colour code here if you would like to. These HTML names are the
+preferred variants; if you need a link to these names, you could
+use this one here https://www.w3schools.com/colors/colors_hex.asp.
+
+So, for example, that yaml file will have these entries:
+
+    colour_for_questions: olivedrab
+    colour_for_answers: lightslategray
+
+You can also change these colours through the commandline,
+as the next examples will demonstrate.
+
+Examples:
+
+    studium --use-this-colour-for-exam-answers=slateblue
+    studium --use-this-colour-for-exam-questions=grey
+
+Do note that you can "style" exam questions and exam
+answers in various ways. For example, if you use "" quotes,
+then another colour will be used (this is no longer the
+case as of October 2020, though; you need to use HTML
+names instead, or special tags such as &#60;one>).
+
+If you use a tag such as <u> and </u> (a html pseudo-tag, u meaning
+**underline**), then the word will be underlined. You can also
+add HTML colours, such as &#60;slateblue&#62; this will be in
+slateblue colour. The latter variant may become shorter in the
+future, such as &#60;slateblue &#62;foo</&#62; or something
+like that - but for now, you have to use the name of the HTML
+colour both in the opening and in the closing tag.
+
+## class Studium::Exams::ShowUpcomingExams
+
+The fairly useful **class ShowUpcomingExams** will display **the next n
+upcoming exams**, where n should be a number from 3-20, simply as that
+is more convenient to digest and read on the commandline. There are also
+files such as d10 or d20 in the **bin/** subdirectory of this gem, which
+defaults to e. g. 10 or 20 upcoming exams. That way you can, for example,
+type d100 and the next 100 upcoming exams are shown (I never had such
+a high number; the 100 here simply stands, sort of, for "show me all
+upcoming exams".)
+
+Don't forget to keep the "register:" entry in the lecture_information.yml
+file, to indicate which exams are upcoming. In the past a separate 
+file called **exams.yml** was used, but since some years this information
+is all unified and presented via the file called **lecture_information.yml**.
+
+If you want to designate another file or location, have a look
+at the file **file_constants.rb**. You can also invoke this
+method to set another file position:
+
+    Studium.set_file_exams()
+
+Simply pass the **location** of your exams-file, which must be
+a yaml file, into that method.
+
+If you simply need the dataset of upcoming exams, you can use
+the following API for this:
+
+    require 'studium'
+    dataset = Studium::ShowUpcomingExams.return_all_registered_upcoming_exams
+
+## GUI - Graphical User Interface
+
+The **studium gem** comes with a few GUI bindings, primarily based
+on those bindings available to ruby. Although using java is an
+option - and then using **swing** - at present no effort is made
+to add a GUI in java or jruby.
+
+The current focus in this project, in regards to graphical user
+interfaces (in the year **2021**) is on GTK, in particular via the
+ruby-gtk3 bindings, which in turn depend on gobject-introspection.
+
+Since as of <b>July 2022</b> the older ruby-gtk2 bindings were
+removed. The ruby-gtk3 bindings were of a much higher quality
+anyway and it is a waste of time to maintain ruby-gtk2 code.
+Note that my other project called <b>gtk_paradise</b> will
+continue to support ruby-gtk2 - I just don't think ruby-gtk2
+will be useful for the studium gem anymore past <b>July 2022</b>.
+
+Further GUI elements may be added in the future, such as
+more sinatra-specific code, more .cgi files, perhaps rails
+as well, and libui. The latter works on windows 
+out-of-the-box if you do "gem install libui", which
+is a huge plus.
+
+If you want to make use of the GTK bindings then you currently need
+the **gtk_paradise** gem, so make sure to install it first. Prior to that
+you will also need to have the necessary gtk-files, headers and what not.
+Your distribution (if you use Linux) may have packaged these for you,
+so research this a little how to obtain all necessary files. I myself
+tend to compile from source, so I don't really know the names of
+the packages different distributions use here.
+
+The **main GUI widget** for **asking exam questions** currently
+(at the least past **February 2021**) looks like this:
+
+<img src="https://i.imgur.com/LOmMhht.png" style="margin: 1em; margin-left: 3em"> 
+
+In **September 2021** this was enhanced a bit and should look slightly
+better now:
+
+<img src="https://i.imgur.com/zpgUCVR.png" style="margin: 1em; margin-left: 3em">
+
+(Don't mind the answer in the above screenshot being wrong; the lower
+input-field is just for giving an answer before hitting the reveal
+button to check whether you gave the correct answer. It's a training
+system, so of course wrong answers may be given. The above image is
+mostly about showcasing the **functionality** as such.)
+
+Note that a **.css** file covers most of the display settings, so users of
+the studium gem could, in principle, **adjust it to their liking via
+a CSS file**. I am willing to change the widget composition and
+functionality as-is, and offer ad-hoc loading of .css files if this
+is wanted, but most of the time I just use the commandline variant
+only, anyway.
+
+Since as of September 2021 a variation exists, called FastAskExamQuestion.
+The old GUI was becoming slow, for some awkward reason, so I simplified
+it, removed some features - it should now be more responsive. It may
+not be as convenient to use, but if you only want a simple GUI for
+exam-questions then consider making use of FastAskExamQuestion 
+rather than AskExamQuestion.
+
+It now looks like this:
+
+<img src="https://i.imgur.com/oPTItPy.png" style="margin: 1em; margin-left: 2em">
+
+It now has fewer features, but I think it looks better organized now, and most
+importantly it is faster. Perhaps the issue was unrelated to that widget; either
+way this new variant will probably retained in the long run.
+
+The current (August 2021) variant of libui looks like this:
+
+<img src="https://i.imgur.com/ZLsymdN.png" style="margin-left: 1em">
+
+Yes, that looks like crap and it is incomplete - but the big win is that this
+will also work on windows, out of the box, without any further ado. The idea
+here is that windows users can now work via a GUI tool past this point.
+**ruby-gtk3** works very well on Linux, but I could not get GTK to
+work on windows, despite the so-called 'official guide' for msys2. Thanks
+to libui it is no longer necessary to wait until I get gtk to work on
+windows - it now works **as-is**.
+
+You may still want to distribute - or use - an **.exe** file on
+windows. This is possible if you use the **ocra** gem.
+
+If you are on windows, then run **bin/studium** like this:
+
+    ruby studium --create-executable
+
+This should build an .exe file that can be started.
+
+(That .exe currently, in August 2021, does not work perfectly
+well. I have to fix some related ruby code first, but starting
+the libui-widget directly via **ruby** works fine - I tested
+that on windows too.)
+
+## The toplevel-method Studium.filter_away_invalid_questions
+
+The toplevel-method **Studium.filter_away_invalid_questions()**,
+defined in the file **studium/toplevel_methods/filter_away_invalid_questions.rb**,
+is used to filter away invalid questions.
+
+This essentially removes any empty lines or lines starting with the
+**#** character, which is assumed to be a comment.
+
+After this method has been invoked on a dataset, it is assumed
+that this dataset will contain only valid (legal) exam
+questions.
+
+You can tap into the following method to determine the path to
+the exam topics:
+
+    Studium.path_to_the_exam_topics?
+
+So you can then read in the exam-topic file, call
+the Studium.filter_away_invalid_questions() method,
+and then randomly select a remaining exam topic to
+ask.
+
+To obtain a random exam topic, use this API:
+
+    Studium.random_exam_topic? # => "epigenetik"
+    Studium.random_exam_topic? # => "abfall_als_ressource"
+    Studium.random_exam_topic? # => "embryologie_und_entwicklung"
+
+## Statistical information within the Studium project
+
+The Studium project also allows for a few **statistical information**
+in regards to the project, e. g. such as how many exams were passed
+in this or that period of time. You can also show the curricula used
+for any given individual curriculum at hand.
+
+The latter feature can be invoked such as is shown next:
+
+    studium --statistics
+
+This will tap into <b>class Studium::DetermineCurricula</b>.
+
+What about "how many exam questions can a human being solve
+per given day"? Well, this is a generic question really, and
+it will depend on the individual. Some people learn faster
+than others, for many reasons. The dataset I compiled for
+myself is not applicable to many other people - you'd need
+to do so consistently and study a whole cohort of people,
+in order to answer this question.
+
+But if we ignore the cohort-situation, just for me, personally,
+I found a few interesting facts. In November 2021 the maximum
+exam-questions answered for me were **10.729**. In
+February of 2020 I reset that counter to 0, for various
+reasons. Then I resumed answering exam questions. In November
+2021 I broke 10.000 again, so the number of 10.729 is not
+a fluke - it's a real number for at the least my own situation.
+So, answering 10.000 exam questions may take me about a year
+and a half, give or take. (Remember that I did not necessarily
+answer the same exam questions again, so I may be above
+11.000 right now, most likely.)
+
+So, if I estimate, in 18 months I answer 10.000 questions,
+and 18 months have roughly 18*30 540 days, then I can answer
+10_000 / 540.0 **18.5 exam questions per day**. Keep in mind
+that I did not answer exam questions on every day, and I wasn't
+really pushing this every day either, so this is more a relaxed
+approach. So a human being can very easily learn something
+new every day, with about 20 exam questions per day at minimum.
+(I consider myself average in this regard, so tons of people
+will have better numbers than these.)
+
+This statistic may be fairly useless for others to know, but I
+find it quite interesting nonetheless. Imagine if I would have started
+with this when I was a little kid - my current knowledge would
+be significantly larger than what I have available right now.
+Whether the time investment pays off in the long run is hard
+to say - after all you also learn something new anyway, even
+without exam questions. Think about mechanical repair knowledge,
+which you can not easily obtain just from reading text; you need
+the physical practice too. But specifically for exam-related topics,
+where only theoretical knowledge is to be considered, this is
+quite helpful, in my opinion.
+
+My next goal is to break 15.000 and then 20.000. Let's see
+how long this will take. :)
+
+## class Studium::Exams::ExamQuestion
+
+class **Studium::Exams::ExamQuestion** has been written in **January
+2022**. It replaced two older classes which formed the foundation of
+the "ask an exam-question" functionality.
+
+The primary reason why it was rewritten was because there were
+several bugs in regards to coloured output on the commandline,
+via **ANSI escape sequences**. These bugs were fixed during
+the rewrite. \o/
+
+The class, called from the commandline, may generate a question/answer
+output such as the following:
+
+<img src="https://i.imgur.com/6D7KBHe.png" style="margin: 1em;">
+
+This shows the question on top, and then the revealed answer
+below, via colours. The colours can be customized a little via
+a .yml file.
+
+## class Studium::Exams::Solved
+
+Since as of **January 2022**, class **Studium::Exams::Solved** will
+be more verbose if you call it from the commandline via:
+
+    solved --be-verbose
+
+I needed this because there were some bugs that had to be
+removed, and it seemed more convenient to let this class
+respond to some user-given commands.
+
+## Creating a SQL database
+
+The exam-questions that are distributed by the studium gem can be
+turned into a **.sql database** (**SQL**).
+
+A helper script exists to do this, at the file location
+**studium/database/create_database.rb**. If you run it
+a .sql file will be created, which is quite large - around
+8MB in size or more. This can then be read into a 
+sqlite database.
+
+Creating a new .sql database takes quite some time, though.
+Presently (in 2022) I don't have a better solution for this
+problem.
+
+If you want to create it on your own host system, first invoke
+that .rb file, which is possible via the commandline via:
+
+    studium --create-database
+
+Then a new .db file will be automatically created. But again,
+be warned, this takes quite some time.
+
+## The file allowed_themes_for_exams.yml
+
+The file <b>allowed_themes_for_exams.yml</b> lists the allowed themes
+for exams. For instance, a lecture that deals with Genetics and
+Cell Biology, may have as allowed themes at the least these two
+topics (e. g. **- genetics** and **- cell biology**).
+
+The reason why this yaml file exists is so that we can use this
+to search for lectures that include these topics. So, in some
+ways, this is for the use case as a **meta-tagger**.
+
+## The file curricula.yml
+
+The file curricula.yml will keep all Curricula entries for
+curricula in **Austria**. This is mostly done so that we
+have these curricula registered, via number mapping to the
+corresponding name.
+
+## Last saved into which file
+
+Whenever you ask an exam-question, it is kept track into which
+file that exam-question will be stored. The toplevel API
+<b>Studium.last_saved_into_which_file?</b> can be used
+to query this.
+
+It would then yield a path such as:
+
+    /home/x/programming/ruby/src/studium/lib/studium/exam_topics/basic_chemistry
+
+## class Studium::SearchFor_nECTS
+
+**class Studium::SearchFor_nECTS** can be used to show all lectures having the
+specified n ECTS credits.
+
+So for example:
+
+    Studium::SearchFor_nECTS.new(1)
+
+would show all lectures having **1.0 ECTS points**.
+
+You can invoke this class from the commandline as well, of course. The name
+of the executable is **n_ECTS**, residing at **bin/n_ECTS**.
+
+I aliased this executable to **nects** on my home system, and can then
+do the following as-is:
+
+    nects 1.0 --master --show-numbers
+
+This would show all lectures belonging to a master-curriculum
+having 1.0 ECTS points. Additionally, the leading LVA ID numbers
+will be shown as well.
+
+## Studium::Exams.report_nquestions_of
+
+The method Studium::Exams.report_nquestions_of() can be used to quickly
+report how many exam questions are available in a particular exam
+topic. If you pass in an Array of exam-topics, such as 'bem1',
+'bem2', 'metabolism', then the method will report the total amount of
+exam-questions in all these exam topics combined. I use this to
+query "meta"-topics combined, such as biochemistry1, biochemistry2,
+and so forth.
+
+## Studium::Statistics::TopStats
+
+class **Studium::Statistics::TopStats** can be used to
+display the percentage value of questions answered in the
+registered exam topics. The purpose is to, simply and quickly,
+show the performance over the registered exam-topics in use.
+
+Invocation example from ruby code:
+
+    Studium::Statistics::TopStats.new(ARGV)
+
+The following small image shows how this may look, being
+applied onto the exam-dataset that I use normally:
+
+<img src="https://i.imgur.com/rhOyyuF.png" style="margin: 1em; margin-left: 3em; border: 2px solid black">
+
+## Studium.report_solved_topics
+
+The solved topics can be quickly displayed if you use the
+following file and code:
+
+    require 'studium/toplevel_methods/report_solved_topics.rb'
+    Studium.report_solved_topics
+
+## class Studium::Exams::MandatoryContinuousAssessment
+
+class <b>Studium::Exams::MandatoryContinuousAssessment</b> can
+be used to handle lectures that require mandatory attendance
+(in german "prüfungsimmanente Lehrveranstaltungen").
+
+The section here does not include all options that this class
+is able to handle; instead, only a select subset will be shown
+and explained here.
+
+If you want to show which mandatory courses may be upcoming,
+sorted on the assigned priority, then you can do this:
+
+    mandatory --upcoming
+
+The command <b>mandatory</b> is an alias I use to 
+the .rb file that holds
+<b>class Studium::Exams::MandatoryContinuousAssessment</b>.
+
+You can also compare (some of) the registered curricula,
+by issuing:
+
+    mandatory --compare
+
+This will output the amount of ECTS points stored in 
+courses that require a mandatory attendance.
+
+If you want to also see the individual lectures and courses
+that were used to determine all courses requiring mandatory
+presence, you can use the following commandline switch:
+
+    mandatory --compare-detail
+    mandatory --compare-stats
+    mandatory --details
+
+On a side-note: if you wish to see some mandatory lectures,
+such as those that belong to the lecture type VO+SE, you
+can pass this as input to **bin/studium**, like so:
+
+    studium VO+SE
+
+You can also query "which mandatory lectures are offered
+in the summer semester" and combine it with "which
+mandatory lectures are offered at the TU Vienna, via:
+
+    mandatory --tuwien --summer
+
+Of course you need to have them registered first, such
+as in the file **lecture_information.yml**, if you wish
+to adapt it to your own universities. The default datset
+focuses on universities in Austria only. But that yaml
+file can be of help if you want to adjust it to your
+own use cases.
+
+## Studium::SetAliasesBasedOnThisFile
+
+This class can be used to batch-assign the main aliases used for
+asking exam questions, if a file called "exam_topics.md" exists.
+Alternatively you can pass in another file that is then used
+instead.
+
+So, rather than doing:
+
+    setalias1 chem1
+
+I can batch-assign different exam topics based on one-entry-per-line
+instead.
+
+This file allows me to store exam topics in an ordered manner,
+such as first line is topic1, second line is topic2 and so
+forth. Then, once that has been done, I can hit the number 1,
+and the first exam question will be asked (belonging to 
+topic2). Or I hit number 2 and the second exam topic will be
+asked, and so forth.
+
+The idea behind this is that I can use the keys 1, 2, 3, 4,
+5, 6, 7, 8 and 9 to ask exam questions and thus train my 
+memory in this regard. It's like an interactive trainer.
+If I want another dataset then I modify the .md file
+and re-assign. I also keep exam themes together, e. g.
+all subtopics that belong to biochemistry as a topic,
+or to cellbiology, or to genetics and so forth. It may
+be a bit difficult to explain if you have never tried this,
+so you can give it a try from the commandline perhaps - 
+I use this almost daily on linux, so it has become
+"second nature" really.
+
+## class ExamRegistrationAt
+
+class ExamRegistrationAt can show upcoming exams. You need to
+store this information in the file lecture_information.yml, so
+there is some time investment to be done, before class
+ExamRegistrationAt is useful for you. But, once you register
+upcoming exams there, class ExamRegistrationAt can show 
+which exams are the next upcoming ones. This helps allow to
+plan time for these exams.
+
+Now - there are two constants that determine how many days
+ahead into the future this class will "look". So, for
+instance, if you want to see only upcoming exams for the
+next 90 days, then you should store this information in
+one of these two constants.
+
+The two constants are:
+
+    LOOK_N_DAYS_INTO_THE_FUTURE
+    LOOK_N_DAYS_INTO_THE_PAST
+
+The first one is much more relevant; the second one is
+not so relevant (and it was only added fairly recently,
+in May 2022. The primary reason why the second constant
+was added was as an ad-hoc solution to not show outdated
+exam entries.).
+
+## The following curricula have been completely integrated into the Studium gem so far
+
+The following **table** lists which curricula have been **integrated fully** so far,
+as of **June 2022**:
+
+Number  |  Name of the Curriculum                            | Curriculum Number  | University               | URL to the curriculum
+--------|----------------------------------------------------|--------------------|--------------------------|---------------------------------------------------------------------------------------------------------
+**1**   | **Bachelor LMBT**                                  |    **033 217**     | **BOKU**                 | https://boku.ac.at/fileadmin/data/H01000/mitteilungsblatt/MB_2019_20/MB17/033_217_Bachelorcurriculum_LMBT_2020U.pdf
+**2**   | **Bachelor Umweltingenieurwissenschaften**         |    **033 231**     | **BOKU**                 | https://boku.ac.at/fileadmin/data/H01000/mitteilungsblatt/MB_2020_21/MB17/Bachelorcurriculum_UIW_033_231_2021U.pdf
+**3**   | **Bachelor Agrarwissenschaften**                   |    **033 255**     | **BOKU**                 | https://www.boku.ac.at/fileadmin/data/H01000/mitteilungsblatt/MB_2017_18/MB20/033_255_Bachelorcurriculum_AW_2018U.pdf
+**4**   | **Bachelor Technische Chemie**                     |    **033 290**     | **TU**                   | http://www.tuwien.ac.at/fileadmin/t/studabt/downloads/Studienplaene/Oktober_2017/BachelorstudiumTechnischeChemieE033290.pdf
+**5**   | **Bachelor Pharmazie**                             |    **033 305**     | **University of Vienna** | http://senat.univie.ac.at/fileadmin/user_upload/s_senat/konsolidierte_Bachelorcurricula/BA_Pharmazie.pdf
+**6**   | **Bachelor Molekulare Biologie**                   |    **033 630**     | **University of Vienna** | https://senat.univie.ac.at/fileadmin/user_upload/s_senat/konsolidierte_Bachelorcurricula/BA_Biologie_Version2015_Juni2018.pdf
+**7**   | **Bachelor Ernährungswissenschaften**              |    **033 638**     | **University of Vienna** | https://nutrition.univie.ac.at/fileadmin/user_upload/i_ernaehrung/Download/Bachelor/Curriculum/Curriculum_Bachelor_Ernaehrungswissenschaften_2013__geringfuegige_AEnderung__2017_2018_40.pdf
+**8**   | **Bachelor Chemie**                                |    **033 662**     | **University of Vienna** | http://senat.univie.ac.at/fileadmin/user_upload/s_senat/konsolidierte_Bachelorcurricula/BA_Chemie.pdf
+**9**   | **Bachelor Molekularbiologie** (Graz)              |    **033 665**     | **University Graz**      | https://online.uni-graz.at/kfu_online/wbMitteilungsblaetter_neu.display?pNr=14602&pDocNr=3627868&pOrgNr=14190
+________|____________________________________________________|____________________|__________________________|___________________________________________________________________________________________________________________________________________________________________________________
+**10**  | **Master LMBT**                                    |    **066 418**     | **BOKU**                 | https://www.boku.ac.at/fileadmin/data/H01000/mitteilungsblatt/MB_2017_18/MB21/066_417_Mastercurriculum_LMWT_2018U.pdf
+**11**  | **Master TU Vienna Biotechnology**                 |    **066 490**     | **TU**                   | https://www.tuwien.ac.at/fileadmin/t/studabt/downloads/Studienplaene/Oktober_2018/MasterTechnischeChemie.pdf
+**12**  | **Master Pharmazie**                               |    **066 605**     | **University of Vienna** | http://senat.univie.ac.at/fileadmin/user_upload/s_senat/konsolidierte_Masterstudien/MA_Pharmazie.pdf
+**13**  | **Master Immunobiologie**                          |    **066 830**     | **University of Vienna** | http://senat.univie.ac.at/fileadmin/user_upload/s_senat/konsolidierte_Masterstudien/MA_Molekulare_Mikrobiologie_Mikrobielle_Oekologie_und_Immunbiologie.pdf
+**14**  | **Master Biologische Chemie**                      |    **066 863**     | **University of Vienna** | http://senat.univie.ac.at/fileadmin/user_upload/s_senat/konsolidierte_Masterstudien/MA_BiologischeChemie.pdf
+**15**  | **Master Bioinformatik**                           |    **066 875**     | **University of Vienna** | http://senat.univie.ac.at/fileadmin/user_upload/s_senat/konsolidierte_Masterstudien/MA_Bioinformatik.pdf
+**16**  | **Master Genetik und Entwicklungsbiologie**        |    **066 877**     | **University of Vienna** | http://senat.univie.ac.at/fileadmin/user_upload/s_senat/konsolidierte_Masterstudien/MA_GenetikEntwicklungsbiologie.pdf
+________|____________________________________________________|____________________|__________________________|___________________________________________________________________________________________________________________________________________________________________________________
+
+
+**BOKU** stands short for "Universität für Bodenkultur" (Wien / Vienna).
+
+**TU** stands short for "Technische Universität" (Wien / Vienna), aka the
+"Technical University" in Vienna.
+
+Keep in mind that the above table currently **only** lists curricula organized in
+**Austria**. If anyone else wants to extend this table to include other
+**european universities**, such as in Germany, feel free to do so - but the
+dataset for these universities will have to be registered **externally**
+(or at the least maintained by someone else for these other european
+universities).
+
+I am willing to add required code to the studium gem, in order to make
+available any external dataset (and thus add other universities),
+though. I just can not maintain the dataset itself, since it will require
+constant adjustments. (In theory we could obtain the dataset dynamically,
+via HTTP-queries and parsing of the result, but no code doing this in
+an automated manner is presently part of the studium gem itself.)
+
+Note that the studium gem keeps these "Mitteilungsblätter" stored
+in the file called <b>studium/yaml/mitteilungsblätter.yml</b>.
+
+## Showing all lectures that belong to a particular curriculum
+
+You can show all lectures that belong to a particular curriculum via:
+
+    studium --lectures-from-this-curriculum=geodäsie
+    studium --lectures-from-this-curriculum=217
+
+This does not work perfectly well, so if in doubt use the
+curriculum id, as a number.
+
+## The very important file called lecture_information.yml
+
+Since as of <b>July 2022</b> the very important file called
+<b>lecture_information.yml</b> now resides at:
+
+    studium/lib/studium/lecture_information/lecture_information.yml
+
+It seemed better to me to put it into a separate directory, considering
+it is just about <b>the most important .yml file of this project</b>.
+
+Remember that the file caters primarily to universities in Austria,
+but since it is ultimately just one huge hash (see the content),
+you can simply add more .yml files to it, or modify the hash that
+you get to your liking - so the studium gem is, in principle
+extensible to <b>accomodate datasets from different universities</b>.
+I may even add more web-scraping means to allow users to automatically
+determine all lectures from a given curriculum at other universities -
+but for now (2022) this is not yet possible.
+
+## Determining the runmode of the Studium gem
+
+The runmode can be determined via <b>Studium.set_runmode()</b>.
+ 
+## Deprecations within the Studium gem
+
+This subsection keeps track of some deprecations of this project.
+
+The constant <b>EXAM_TOPICS</b>, which used to be:
+
+    EXAM_TOPICS = "#{Studium.project_base_directory?}exam_topics/"
+
+as well as "aliases" to it, such as DIRECTORY_TO_THE_EXAM_TOPICS
+or EXAM_TOPICS_DIRECTORY, was deprecated as of <b>July 2022</b>.
+
+If you want to obtain the exam-topics directory then you should
+consistently use the following method instead:
+
+    Studium.exam_topics_directory?
+
+The old code will be published here for some time longer, but
+eventually it may be removed entirely:
+
+      # ========================================================================= #
+      # === EXAM_TOPICS
+      #
+      # This constant will store where the exam topics are stored on a
+      # given computer system.
+      #
+      # The path will be relative to the PROJECT_BASE_DIRECTORY constant.
+      #
+      # Note that this is a constant though - it is recommended to use
+      # the @exam_topics variable instead if you need the variable
+      # to be dynamic.
+      #
+      # This may, for example, have a value such as:
+      #
+      #   /Programs/Ruby/2.5.1/lib/ruby/site_ruby/2.5.0/studium/exam_topics/
+      #
+      # ========================================================================= #
+      EXAM_TOPICS = "#{Studium.project_base_directory?}exam_topics/"
+        # ======================================================================= #
+        # === DIRECTORY_TO_THE_EXAM_TOPICS
+        # ======================================================================= #
+        DIRECTORY_TO_THE_EXAM_TOPICS = EXAM_TOPICS
+        # ======================================================================= #
+        # === EXAM_TOPICS_DIRECTORY
+        #
+        # Same as above.
+        # ======================================================================= #
+        EXAM_TOPICS_DIRECTORY = EXAM_TOPICS
+
+In <b>July 2022</b> the old method called <b>Studium.ensure_main_encoding()</b>
+was deprecated. It did no longer seem necessary to have it, as UTF-8
+is used by default now.
+
+However had, perhaps in the future this may have to be re-enabled in
+one way or another. I will keep the code here, but it may also be that
+this code will never be re-added, in which case a future release of
+the studium gem may remove the following subsection. Either way here
+goes:
+
+    # ========================================================================= #
+    # === Studium.ensure_main_encoding
+    #
+    # This method will try to ensure the main encoding in use. This
+    # presently works for both Arrays and Strings; other classes are
+    # not supported (but they are also not as important as Arrays
+    # and Strings really; possibly excluding class Hash).
+    # ========================================================================= #
+    def self.ensure_main_encoding(i)
+      copy = i
+      use_this_encoding = @use_this_encoding
+      # ======================================================================= #
+      # === Handle Array next
+      # ======================================================================= #
+      if copy.is_a? Array
+        copy = copy.map {|entry|
+          if entry.is_a? String
+            unless entry.encoding.to_s.include? use_this_encoding
+              entry = entry.force_encoding(use_this_encoding)
+            end
+          end
+          entry
+        }
+      # ======================================================================= #
+      # === Handle Hash next
+      # ======================================================================= #
+      elsif copy.is_a? Hash
+        new_hash = {}
+        copy.each_pair {|key, value|
+          unless key.encoding.to_s.include? use_this_encoding
+            key = key.dup if key.frozen?
+            unless key.is_a? Symbol
+              key = key.force_encoding(use_this_encoding)
+            end
+          end
+          if value.is_a? Array
+            array = Studium.ensure_main_encoding(array)
+          end
+          new_hash[key] = ensure_main_encoding(value)
+        }
+        copy = new_hash
+      # ======================================================================= #
+      # === Handle String next
+      # ======================================================================= #
+      elsif copy.is_a? String
+        unless copy.encoding.to_s.include? use_this_encoding
+          copy = copy.dup if copy.frozen?
+          copy = copy.force_encoding(use_this_encoding)
+        end
+      end
+      return copy
+    end
+
+In <b>July 2022</b> the constant:
+
+    FILE_LECTURE_INFORMATION = "#{PROJECT_YAML_DIRECTORY}lecture_information.yml"
+
+was deprecated. Use the toplevel instance variable @file_lecture_information
+instead, or the method <b>Studium.file_lecture_information</b>. 
+The constant <b>FILE_LECTURE_ALIASES</b> was also deprecated in <b>July
+2022</b>, as well as the constant <b>FILE_CURRICULA</b>.
+
+The same counts for the constant <b>FILE_IMPORTANT_EXAMS</b>. In general,
+methods are now more important, so use the replacement method called
+<b>Studium.file_important_exams</b>.
+
+The constant:
+
+    ALPHABET = ('a'..'z').to_a
+
+was moved into the only .rb file that needs it - it was part of
+constants.rb before <b>July 2022</b>.
+
+The following constant was removed in <b>July 2022</b>:
+
+    # ========================================================================= #
+    # === FILE_UPCOMING_PRACTICAL_COURSES
+    #
+    # This file is for a .yml file that keeps track of upcoming practical
+    # courses. In particular, this may be helpful in order to determine
+    # which practical courses may overlap with one another.
+    # ========================================================================= #
+    # FILE_UPCOMING_PRACTICAL_COURSES =
+    #   "#{STUDIUM_YAML_DIR}WS2017/upcoming_practical_courses.yml"
+
+It is probably no longer needed, because the file lecture_information.yml
+can indicate in which practical courses we are registered now.
+
+The constant ARRAY_TITLE_OF_THE_INDIVIDUAL_CURRICULA was also disabled
+as of <b>July 2022</b> - each individual curricula now has the title
+on its very second line:
+
+    # ========================================================================= #
+    # === ARRAY_TITLE_OF_THE_INDIVIDUAL_CURRICULA
+    #
+    # This constant is mostly on an ad-hoc basis in that we will register
+    # the title of all individual curricula. This can then be used by
+    # Studium::DetermineCurricula in particular to determine which
+    # courses ought to be shown.
+    # ========================================================================= #
+    ARRAY_TITLE_OF_THE_INDIVIDUAL_CURRICULA = [
+      'Bachelorcurriculum Informatik und molekulare Biologie',
+      'Bachelorcurriculum (Bio)Informatik und molekulare Biotechnologie, unter Berücksichtigung medizinisch-immunologischer Aspekte',
+      'Bachelorcurriculum Vector-based strategies in Life Sciences, Molecular Medicine and Biotechnology'
+    ]
+
+The constant <b>PASSED_EXAMS_PER_MONTH</b>:
+
+    PASSED_EXAMS_PER_MONTH = FILE_PASSED_EXAMS_PER_MONTH
+
+Was just an alias in the past. It has been removed in <b>July 2022</b>.
+
+If you have to, use the longer constant name called
+<b>FILE_PASSED_EXAMS_PER_MONTH</b>. The constant called
+<b>FILE_DIRECTORY_TO_THE_EXAM_TOPICS</b> was also
+removed.
+
+The constant <b>DIRECTORY_EXAM_TOPICS</b> was removed as well.
+
+    # ========================================================================= #
+    # === DIRECTORY_EXAM_TOPICS
+    #
+    # Determine where we can find the exam topics, as constant.
+    # ========================================================================= #
+    DIRECTORY_EXAM_TOPICS = MY_EXAM_TOPICS
+
+## Vorbesprechungen / Preparatory meetings
+
+Some courses require a date before the actual course week, which we
+will call "preliminary meetings" (in german, "Vorbesprechung" or
+"Vorbesprechungstermin"). In July 2022 the name was changed to
+preparatory_meeting.
+
+The Studium project supports this keeping track of such a preparatory
+meeting. The corresponding entry that has to exist, in the
+file **lecture_information.yml**, is called
+"preparatory_meeting:".
+
+The **class PreparatoryMeeting** can show upcoming preliminary
+meetings. That way you should not miss the mandatory attendance
+part anymore of some courses.
+
+The name <b>Vorbesprechungen</b> is kept as a backwards "alias"
+to this new class.
+
+If you wish to designate this in the file <b>lecture_information.yml</b>
+then you can use something like the following, adapted to your use
+case:
+
+    !ruby/symbol preparatory_meeting:
+     - "05.10.2023, 09:15-10:15, Ort: An der BOKU, Muthgasse 7"
+
+## Returning the dataset of a specific exam topic
+
+If you have a need to return the dataset of a specific
+exam topic, as an Array, then you can use the following
+API:
+
+    array = Studium.return_dataset_for_this_exam_topic('geology')
+    array = Studium.return_dataset_for_this_exam_topic('genetics')
+
+And so forth. This method appeared to be useful to use it on
+some website, for instance.
+
+## Displaying curriculum modules on the commandline
+
+<b>class Studium::Curricula::Modules::DisplayOnTheCommandline</b>
+can display each module of a specific curriculum on the commandline.
+
+This only really works very well for individual curricula. But in
+principle this class could be extended to work with <b>all</b>
+curricula in general.
+
+## class Studium::ReturnNEctsFromThisUrl
+
+<b>class Studium::ReturnNEctsFromThisUrl</b> can be used to
+determine the number of ECTS points of a given lecture.
+
+Pass the remote URL to this class in order for this to
+work.
+
+Example:
+
+    Studium::ReturnNEctsFromThisUrl.new('https://online.boku.ac.at/BOKUonline/wbLv.wbShowLVDetail?pStpSpNr=278600')
+
+## Java code pertaining to the studium gem
+
+Since about two years, give or take, say starting in
+the year 2020, Java code has been added to the
+studium gem - both for the commandline, as well as
+GUIs. This is highly experimental still and not 
+very extensive.
+
+Most work goes into <b>AskExamQuestion.java</b>
+right now, until it is possible to work with the
+Studium gem from the commandline, in particular
+on Windows. Then when this works alright, we may
+extend the Swing and JavaFX bindings, to make it
+more convenient to work with the project via a
+GUI - but first the commandline has to work
+very well.
+
+Once that works ok-ish the studium gem should be
+more useful on windows too; Java works fairly
+well on windows and is quite fast. Speed is one
+of the few things Java is better than ruby. In
+the long run, though, it may be ideal to use
+truffleruby or jruby to bridge the gap between
+these two worlds. Stay tuned for more to come
+in this regard.
+
+## Generating .pdf files
+
+You can generate some .pdf files about exam-topics.
+
+For example, for the topic **amg**, you can generate a .pdf file
+through:
+
+    studium --generate-pdf-for=amg1
+
+Do note that this functionality depends on the gem called **prawn**.
+
+Here are more examples for pdf-generation:
+
+    studium --generate-pdf-for=biotech1
+    studium --generate-pdf-for=biotech2
+    studium --generate-pdf-for=virus1
+    studium --generate-pdf-for=virus2
+
+Note that most of the functionality related to PDF-files can be
+found under the directory <b>studium/utility_scripts/pdf/</b>.
+
+Since as of <b>August 2022</b> it is now possible to
+generate a huge .pdf file that contains ALL the exam
+questions. So this is using the same functionality as
+above, but it will integrate **all** topics. Beware,
+this will lead to a truly huge .pdf file:
+
+The commandline for this functionality can be invoked
+by issuing any of the following:
+
+    studium --mega-pdf
+    studium --monster-pdf
+    studium --monster
+
+Note that this may take about 30 seconds or longer,
+and the generated .pdf file will easily have more
+than 1449 pages. So this is not too terribly useful
+for most people, but just in case this functionality
+exists, so there you go.
+
+## class Studium::ParseLvaDates
+
+This class (<b>class Studium::ParseLvaDates</b>) can be
+used to sanitize lecture data, for lva dates, aka when
+a lecture is occurring. This only works for a few
+universities right now; perhaps it will be improved
+in the future.
+
+## class Studium::BlockedCourses
+
+A <b>blocked course</b> is something like a practical lab-course
+that occupies a week or two weeks, en-bloc in one go. Such a course
+requires <b>mandatory presence</b> (that is the student has to be
+there), and is spanning over a limited time - less than the whole
+semester (half-year).
+
+The reason why this class was written in <b>October 2022</b> was
+to be able to indicate which courses are blocked. Perhaps you may
+want to register only for some blocked course, so in this case
+that class may be useful.
+
+Note that you have to populate the lecture with the correct
+"lva_dates:" entries by yourself. Perhaps in the future this
+may be changed to automatically determine the LVA-dates, but
+for now this has to be done manually.
+
+## class Studium::DisplayLectureUrl
+
+This class can display lectures and their associated remote URL
+(the homepage) via the commandline.
+
+Basic usage example from within Ruby:
+
+    require 'studium/utility_scripts/display_lecture_url.rb'
+    Studium::DisplayLectureUrl.new(ARGV)
+    Studium::DisplayLectureUrl.new('--indi2')
+
+This class can either output just one lecture's course
+URL, or operate in a batch-mode where all lectures of
+a curriculum are displayed.
+
+    Studium::DisplayLectureUrl.new('
+      301586 Molekulare Medizin 2:
+      301585 Molekulare Medizin 1:
+      301407 DNA-Tumorviren, vom Krebsauslöser zum Therapeutikum:
+      301589 Literaturseminar Molekulare Medizin:
+      322052 Nukleinsäure-Therapeutika: Antisense, RNA Interferenz, CRISPR - M14:
+      301586 Translation und Translationskontrolle bei Eukaryonten II:
+      322083 Zelluläre und molekulare Pharmakologie und molekulare Medizin - M14:
+    ')
+
+The latter functionality was added to simplify working with "raw"
+data, e. g. if you have this listed in a .md text file and want
+to copy/paste it. See also the executable at
+<b>bin/display_lecture_url</b>.
+
+## class Studium::UniversityCourse
+
+class Studium::UniversityCourse was added to represent a university-course,
+in December 2022. It remains to be seen how useful this class will be.
+
+I needed such a class because I wanted to determine the next exams or the
+next exam via:
+
+   .next_exams? # Obtain all upcoming exams, as Array.
+   .next_exam?  # Obtain the next upcoming exam, as String. nil otherwise.
+
+It is not difficult to obtain the list of upcoming exams without such
+a class, but I found it was easier to read, so I added this class.
+
+## Studium.map_input_to_this_curriculum_filename
+
+In <b>December 2022</b> the method <b>Studium.map_input_to_this_curriculum_filename()</b>
+was added.
+
+The reason as to why this method was added was because the studium gem
+used many different ways, in different files, to determine which input
+is valid (that is, can be mapped to a locally existing file containing
+a curriculum) and which input is not.
+
+For instance, a given input such as <b>genetik</b> or <b>genetic</b>
+should be mapped to the following target file:
+
+    studium/yaml/curricula/bachelor/bachelor_biologie_mikrobiologie_und_genetik_033630.yml
+
+But, internally, there were methods and case/when menus that would
+work on :genetik (as a symbol), and some others that would
+assume 'genetik' - but then omit the alternative aliases, such 
+as genetic, and other aliased names. So it was a very big mess
+really.
+
+Since as of December, with that now documented method, all parts
+of the Studium gem that require such a mapping, should make
+use of that method instead. Internally the method will convert
+all input to a String - it seems easier to work with Strings
+here.
+
+Right now not all the code used in the Studium gem will make
+use of the method here, but one reason why this method is
+documented is so that I can eventually transition all code
+parts to this new method over time. So at some point in the
+future this will become the new default.
+
+A related method, called <b>Studium.return_file_for_this_curriculum()</b>
+exists, but this method may eventually be deprecated, or rather,
+assimilated into the new method. Right now it still exists,
+though.
+
+## class Studium::ParseRemoteLecture
+
+In <b>December 2022</b> it was decided that class <b>Studium::ParseRemoteLecture</b>
+will be improved and extended in the near future.
+
+Up until December 2022 I mostly added courses manually into the
+big .yml file (lecture_information.yml). However had, that is
+quite cumbersome and takes away a **lot** of time. Furthermore
+this also leads to more errors, so I really needed a way to
+parse a remote homepage, and turn this information into a 
+correct, sanitized yaml-format. That way I can also assemble
+whole curricula offered at different universities, so different
+people could extend the dataset. Perhaps one day we could
+include all curricula at every university in europe, or even
+world-wide. But the latter may be for other people - I only
+want to focus on a dataset that focuses on central europe,
+while giving other users the option to extend and maintain
+their **own** datasets here.
+
+Note that right now class Studium::ParseRemoteLecture isn't quite
+as solid and useful yet - it still has to be improved.
+
+## class Studium::Exams::UpcomingRegisteredExams
+
+<b>class Studium::Exams::UpcomingRegisteredExams</b> can be used
+to quickly show all exams you registered for. In order for this
+to work you need to have added the entry <b>registered:</b>
+in the file <b>lecture_information.yml</b>.
+
+## Grades
+
+Exams at universities are typically graded. Different countries make
+use of different systems. For example, germany uses 6 grades whereas
+Austria uses 5 grades.
+
+If you want to output which exams fit to a certain grade, such as
+<b>grade 2</b>, then you can use code written in
+<b>studium/toplevel_methods/show_passed_exams_having_this_grade.rb</b>:
+
+The API is:
+
+    Studium.show_passed_exams_having_this_grade
+    Studium.show_passed_exams_having_this_grade(2)
+    Studium.show_passed_exams_having_this_grade(3)
+    Studium.show_passed_exams_having_this_grade(4)
+
+Simply pass the <b>number</b> to that method, corresponding to the
+grade that is sought. In order for this to work, you must use some
+file where the grades are stored. This can be either in the file
+<b>lecture_information.yml</b> (I recommend this approach), but it
+could also be a local .csv file. (The latter is mostly still there
+for legacy reasons; when this project was started, a .csv file was
+used rather than a .yml file. Lateron it was realized that the yaml
+file would be much better, since it can also include native and
+nested data structures, which makes it a lot easier to parse
+as-is, via the yaml wrapper that ruby has.)
+
+If you want to display the <b>average</b> grades of passed exams
+then you can use <b>class Studium::Exams::AverageGrade</b>.
+
+## Checks and sanitizing information stored in the studium gem
+
+The studium gem contains a LOT of information - the biggest
+data-file is the file called <b>lecture_information.yml</b>.
+But this is not the only file that contains information - there
+are various other YAML files (mostly) that contains important
+information as well. Furthermore, the studium gem depends
+on information made available on the world wide web, that is,
+on other computers.
+
+Naturally when a project depends on a lot of information,
+errors may exist or show up over time. Sometimes old classes
+are removed or changed, and then we should still ensure
+that the existing functionality remains in a working state.
+The whole projects should remain in a working state, anyway.
+
+Thus, in order to cope with this situation, and **reduce
+the number of errors and problems** that the studium gem
+faces, various helper-scripts are available that should
+help the user, but also developers (including myself)
+with the project. We want to verify that the information
+we use is correct.
+
+This is done primarily by the .rb files stored in the
+<b>studium/check_and_sanitize/</b> subdirectory of this
+project.
+
+For instance, say that you wish to check for problems
+in the file <b>lecture_information.yml</b>. This
+can be done as follows from the commandline:
+
+    studium --check-file-information
+
+## class Studium::Exams::UpcomingExamsDataset
+
+The **class Studium::Exams::UpcomingExamsDataset** is a **helper**-class.
+
+It wraps over the file <b>exams.yml</b> and allows a simple query to
+the upcoming exams, based on that file (which, as exam, must be
+registered in the file <b>exams.yml</b>).
+
+This information can then be used to query which exams are upcoming
+on which day, at which time. This information can also be re-used
+in different classes, which was one important reason as to why
+this class has been created in the first place.
+
+Take note that by default this file is <b>not</b> distributed 
+via the studium gem, as it is only useful for my own use
+case. Other users may have to create their own exams.yml 
+files. The format is simple - first comes the date of the
+exam at hand, then the description, such as:
+
+    26.01.2012: "TU Wien, 185.AAA java course 101, 18:30-20:00"
+
+## Showing upcoming exams (exams that will be held in the future, from today)
+
+**class Studium::ShowUpcomingExams.new** can show **upcoming exams**,
+on the commandline.
+
+The **first input argument** should be a number, e. g. 10, which
+means that the first 10 upcoming exams will be shown. For the
+next 20 exams, it would be **d20**.
+
+Note that this **depends on aliases** called "**pwdstud1**" or
+"**pwdstud2**". These have to exist in a yaml file (on my system
+this is the yaml file named **cd_aliases.yml**). The display is
+on the commandline but in principle, a **GUI** could be used as
+well for this task.
+
+Do note that when this class is invoked, it will additionally store
+the result into a file called, e. g. **d20.md** or **d10.md**. This
+would allow you to upload that file if you want to. I needed that
+functionality because I wanted to display the upcoming exams
+somewhere else other than on my machine, for when I am not at home.
+
+Note that there does exist another class, which can show upcoming
+exams, via a **.html** file. This class is called
+<b>Studium::Exams::UpcomingImportantExams</b>.
+
+You can invoke class <b>Studium::Exams::UpcomingImportantExams</b>
+from the commandline by issuing something like the following:
+
+    studium --upcoming-exams
+
+The display will be a HTML table essentially. In order for this
+to work, the file **lecture_information.yml** must contain the
+information for these upcoming exams - it is the only file
+that you may have to update, though. (In theory code could
+be added to automatically check for new exams, but this
+requires more code to be written. I am not sure if I will
+add this, simply due to time constraints alone.)
+
+You can pass in some other commands to the file from the
+commandline, such as **--do-not-exit** - see the **--help
+option** for more information pertaining to class
+<b>Studium::Exams::UpcomingImportantExams</b>.
+
+If you want an Array of upcoming exams, consider using the
+following method:
+
+    Studium::Exams::UpcomingExams.in_this_curriculum()
+    Studium::Exams::UpcomingExams.in_this_curriculum(:bachelor_agrarwissenschaften)
+
+Remember that this will only work if lecture_information.yml
+contains that information, so always maintain this .yml
+file properly.
+
+## The yaml file array_allowed_entries_for_the_file_lecture_information.yml
+
+The yaml file <b>array_allowed_entries_for_the_file_lecture_information.yml</b>
+contains all entries that are allowed in the file <b>lecture_information.yml</b>.
+
+A few entries will be explained next.
+
+Let's start with the entry
+<b>!ruby/symbol course_registration_time_limit</b>
+which was added in February 2023.
+
+This entry simply specifies at which point one can register for
+the given course. This is especially important for courses
+that have a specific time limitation.
+
+Usage example:
+
+    !ruby/symbol course_registration_time_limit:
+    - 01.02.2023-23.02.2023
+
+A middle '-' is mandatory here. First entry is <b>the starting day</b>;
+second entry (after the '-') is <b>the end</b> day, that is the very
+last day that can be used for <b>course registration</b> still.
+
+Note that this entry is experimental as of February 2023 - at a
+later time it will be determined how useful this entry is. But I
+think it is sufficiently useful to keep it available.
+
+
+
+## Contact information and mandatory 2FA coming up in 2022
+
+If your creative mind has ideas and specific suggestions to make this gem
+more useful in general, feel free to drop me an email at any time, via:
+
+    shevy@inbox.lt
+
+Before that email I used an email account at Google gmail, but in **2021** I
+decided to slowly abandon gmail, for various reasons. In order to limit the
+explanation here, allow me to just briefly state that I do not feel as if I
+want to promote any Google service anymore when the user becomes the 
+product (such as via data collection by upstream services). I feel this is
+a hugely flawed business model.
+
+Do keep in mind that responding to emails may take some time, depending on
+the amount of work I may have at that moment.
+
+In <b>2022</b> rubygems.org, or rather the corporate overlords who control the
+rubygems.org infrastructure these days, decided to make 2FA mandatory for every
+gem owner eventually: see
+https://blog.rubygems.org/2022/06/13/making-packages-more-secure.html
+
+Mandatory 2FA will eventually be extended to all rubygems.org developers and
+maintainers. As I can not use 2FA, for reasons I will skip explaining here,
+this means that my projects will eventually be taken over by shopify (or,
+correspondingly, whoever effectively controls the rubygems.org ecosystem).
+At that point, I no longer have any control what is done to my projects
+since shopify (respectively those controlling the gems ecosystem) took away
+control here. Not sure at which point ruby became corporate-controlled -
+that was not the case several years ago.
+
+Ruby also only allows 2FA users to participate on the issue tracker these
+days:
+
+  https://bugs.ruby-lang.org/issues/18800
+