studium 0.9.383

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 319c78a55210eed81fd136b89c85292e24de6670b438cd0f6de196d6823b2b3e
+  data.tar.gz: ab8fce48c78081e34894586d6fce43847f951fbb6cbb5ef555952fe3a02ddc62
+SHA512:
+  metadata.gz: 8b7cd9d2ab53353a5b3ed632ce6cfc78e19e23607217debb829fe6472c35331f8cc8ab5cc91264e875ee6e391c34f6477c604ce744a8216c685ccfa6132a879e
+  data.tar.gz: b873d29d2b91eb498d07d5fb2b4f922a270459c3ded27f3670ad3692bb410748bc94fb861c43a5f32e979bbca84eca777572a67760504bb44c1fac41cf1e30f6

data/README.md

@@ -0,0 +1,1651 @@
+[![forthebadge](http://forthebadge.com/images/badges/built-with-love.svg)](https://www.gobolinux.org/)
+[![forthebadge](http://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)
+
+[![logo](http://shevy.bplaced.net/STUDIES.png)](https://rubygems.org/gems/studium)
+
+## The purpose of the studium-gem
+
+The **Studium project** attempts to help the user with **study-**
+and **exam-related topics** in general.
+
+The **primary** purpose of the studium gem is to distribute the code
+(in ruby), the associated dataset (mostly text files, in particular
+yaml files) and also **interconnect** the various ruby files under
+the same "umbrella-project".
+
+The original goal for the **Studium project**, that is **why** it 
+was started, was to bundle together **knowledge** from different
+topics - be it related to **ruby**, **informatics**, **biology**,
+**chemistry**, **biotechnology** or **physics**, as an
+**exam trainer**. The objective here was to improve the grades
+and pass more exams within a given time frame. Since then this
+original use case has been **extended** quite a bit, including
+online-related aspects (make the dataset available via a
+web-interface, such as through sinatra).
+
+There are several different classes which are all part of the
+**Studium** gem (namespace being **module Studium**), that could
+potentially be of **help** to the user.
+
+If 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 is:
+
+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.
+
+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.
+
+A **general overview on the commandline**, as to what the main
+functionality is, can be obtained through this entry point, aka
+**--help**:
+
+    studium --help
+
+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.
+
+## Exam dataset
+
+The **individual exam topics** 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, but if you want to use
+this project (such as a base-system, and then modify it) 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.
+
+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 but if you want
+to, you can ignore this limit. I personally found it useful to have.
+Whenever I have more than 1000 questions, I tend to create a new file
+with "advanced" questions, or simply split things up.
+
+For example, I used to have 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 4000 as of now. (It may be even more if you
+also include molecular techniques and genetics into biochemistry, which
+some university lectures 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.
+
+But - what I believe may work for many 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).
+
+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.
+
+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
+
+Since as of March 2018, the studium project also supports flashcards
+formally.
+
+Flashcards are menmonic-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
+
+## class Studium::Exams::ShowUpcomingExams
+
+The **class ShowUpcomingExams** will display the next n upcoming
+exams, where n should be a number from 3-20. There are also files
+such as d10 or d20 in the bin/ subdirectory, which defaults to
+e. g. 10 or 20 upcoming exams.
+
+Note that in order for this to work, this may require to define
+local directories, and the exams in a file called **exams.yml**.
+
+This may change in the future, since the **exams.yml** file is
+not distributed with this gem (it is specific for my exams, so
+really most useless to other people) - but for now, this is how
+things are.
+
+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.
+
+## 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 this project is to simulate the behaviour of mnemo-cards,
+memo-cards or flashcards (we will assume these names to be 
+synonymous).
+
+The project can ask a random exam question.
+
+Then, if the correct answer has been given, this question can be marked
+as "solved" - the code for the latter solved action resides in the
+file called **solved.rb**.
+
+Any question that has been marked as "solved" will no longer be
+within the total pool of questions that the computer will ask you.
+
+In other words, we can toggle on/off on a per question basis, via
+a trailing [] 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 - 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.
+
+## Namespaces in the project
+
+The main namespace is called **Studium**, which is german for studies.
+
+The exam-relevant part resides under **Studium::Exams**. 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).
+
+## Statistical information within the Studium project
+
+The Studium project also allows for a few statistical informations,
+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.
+
+This can be invoked such as in this way:
+
+    studium --statistics
+
+This will tap into <b>class Studium::DetermineCurricula</b>.
+
+## 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
+t 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 10.03.2018, 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 March 2018, 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.
+
+## 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>show_lva_dates_of_this_lecture.rb</b>.
+
+The usage 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 such as via:
+
+    studium --show-lva-dates-of-this-lecture=Primatologie
+    studium --show-lva-dates-of-this-lecture="300227 Primatologie"
+
+## 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 (March 2018), 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 August 2018, 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**.
+
+## 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.
+
+## 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 lecture, do any of this:
+
+    mandatory --compare-detail
+    mandatory --compare-stats
+
+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
+
+## Studium.pristine
+
+The toplevel-method made available through <b>Studium.pristine</b>
+can be used to create a new <b>lecture_information</b> file.
+The one that is, by default, bundled with the studium-gem is/was
+tailored to my own needs. So if you want to use the file,
+it may be better to generate it once, and then modify that
+newly generated file. (Don't forget to keep a backup of it
+available as well, in case it is deleted or overwritten.)
+
+This can also be done on the commandline, 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
+
+## 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>.
+
+## Vorbesprechungen / Preliminary meetings
+
+Some courses require a date before the actual course week, which we
+will call "preliminary meetings" (in german, "Vorbesprechung" or
+"Vorbesprechungstermin").
+
+The Studium project also supports this. The corresponding entry that
+has to exist, in the file **lecture_information.yml**, is called
+"vorbesprechungen:".
+
+The **class Vorbesprechungen** can show upcoming preliminary
+meetings. That way you should not miss the mandatory
+attendance part anymore.
+
+## 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.
+
+## 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(4)
+
+Simply pass the <b>number</b> to that method. 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 .csv file. (The latter is mostly
+for legacy reasons; when this project was started, a .csv file was
+used. 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.)
+
+## Expanding time ranges
+
+Take a lecture where you may have to spend time in a laboratory,
+from early morning to late evening, over a time period of three
+weeks. (This is just an example to illustrate this subsection.)
+
+You may see that the school/university displays the dates via
+something like:
+
+    15.10. - 2.11.2018,
+
+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
+start at the 15th of october, in the year 2018 (this is the
+dd.mm.yyyy notation which is in general used in europe).
+
+The - means "up until" and the end date is specified to be
+at the second of november, in 2018.
+
+Since I needed to quickly convert this 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.
+
+It will accept such odd input and output an Array that can
+be used in a yaml file, of specific dates, weekend-names
+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.)
+
+Internally you can also use module-level instance methods, such
+as:
+
+    Studium.expand_time_range()
+    Studium.expander()
+
+Use whatever 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"
+
+## 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
+just to polish existing functionality, and to add a tiny bit of new
+functionality every now and then. :)
+
+## 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.)
+
+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**.
+
+## 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
+
+## 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 also disable colours for the whole project.
+
+In ruby code you could invoke this method:
+
+    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>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.
+
+You can also change these colours through the commandline,
+as the next examples will show.
+
+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. 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 %3Cslateblue %3Ethis will be in slateblue
+colour %3C/slateblue %3E. The latter variant may become shorter
+in the future, such as <slateblue>foo</> 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.
+
+## Registered URL entries to the (registered) lectures
+
+Since as of 15.04.2019 (April 2019) 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:
+
+    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.
+
+This requires that there is a key called :homepage registered
+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.
+
+## lecture_information.yml
+
+The file <b>lecture_information.yml</b> is extremely important and rather
+central to the project, so this subsection will detail the rationale for
+this file and what information this file will contain.
+
+The file **lecture_information.yml** is distributed as part of the **studium
+gem**, in the <b>yaml/</b> **subdirectory**.
+
+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 **format** of that file is simple:
+
+- The first line, 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 result.
+
+Then, **additionally**, you must **prepend* the LV ID as the first entry
+in that particular line.
+
+Complete example for this:
+
+<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. 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 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.)
+
+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 this file, from the
+commandline, through <b>class Studium::CheckTheLectureInformationFile</b>.
+
+This can be invoked from the commandline as well:
+
+    studium --check-file-information
+
+## Studium.find_corresponding_exam_topic
+
+The toplevel method **Studium.find_corresponding_exam_topic** 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' becomes '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::Exams::PushSolvedQuestionsOnTop
+
+**class Studium::Exams::PushSolvedQuestionsOnTop** has a very simple
+task: 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 **#**, and the first
+line after that '#' comment, which is just a newline for 
+readability reasons.
+
+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.
+
+## Studium::Statistics::TopStats
+
+class **Studium::Statistics::TopStats** can be used to
+display the percentage value of questions answered in the
+registered exam topics.
+
+Invocation example:
+
+    Studium::Statistics::TopStats.new(ARGV)
+
+## 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. :)
+
+## Showing upcoming exams
+
+**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>.
+
+## 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**.
+
+## 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.)
+
+## 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.
+
+I aliased the class to **nects**, and can then do the following:
+
+    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.
+
+## 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 **March 2020**:
+
+Number  |  Name of the Curriculum                            | Curriculum Number  | University               | URL to the curriculum
+--------|----------------------------------------------------|--------------------|--------------------------|---------------------------------------------------------------------------------------------------------
+**1**   | **Bachelor LMBT**                                  |    **033 217**     | **BOKU**                 | https://www.boku.ac.at/fileadmin/data/H01000/mitteilungsblatt/MB_2016_17/MB21/033_217_Bachelorcurriculum_LMBT_2017U.pdf
+**2**   | **Bachelor KTWW**                                  |    **033 231**     | **BOKU**                 | https://boku.ac.at/fileadmin/data/H01000/mitteilungsblatt/MB_2018_19/MB17/033_231_Bachelorcurriculum_KTWW_2019U.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.)
+
+## 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.
+
+## 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
+
+This class 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.
+
+
+## Contact information
+
+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:
+
+    shevegen@gmail.com
+
+(Do keep in mind that responding to emails may take some time, depending
+on the amount of work I may have at that moment, due to reallife. I will,
+however had, read feedback. Patches and code changes are welcome too
+of course, as long as they are in the spirit of the project at
+hand, e. g. fitting to the general theme.)
+
+Thank you.