studium 0.16.9

data/doc/SQL_database_specification/SQL_database_specification.md

@@ -0,0 +1,46 @@
+This file explains some of the SQL specification that the
+studium gem uses in regards to the distributed exams.
+
+At the time of writing this in January of 2022, more than
+40.000 exam questions are registered in the studium gem.
+These reside in different text files, which means that
+querying the content in particular on windows is somewhat
+slow; on linux this is no issue.
+
+So, that was one reason why it was considered necessary
+to create a SQL database, to allow for a faster query.
+
+What should be included in that SQL database?
+
+Evidently we want to include the exam-question, and the
+associated exam-answer in it. Furthermore we need to
+know to which topic this exam-question belongs to,
+which can be handled by associating it with a proper
+table in that database.
+
+The available exam topics (which we can then use for
+the tables in the SQL database) can be queried as
+follows:
+
+    Studium.exam_topics_short_names?
+
+So, the next step is:
+
+    CREATE TABLE quality_management (
+      exam-topic  CHAR (250) NOT NULL,
+      exam-answer CHAR (550) NOT NULL
+    )
+
+Let's create the main database first:
+
+    sqlite 
+    sqlite3 exam_questions.db "CREATE TABLE ruby(exam_question, exam_answer);"
+    INSERT INTO ruby(exam_question, exam_answer) values ('In Ruby: <one>Bundler</one> will calculate the dependency tree for an application and store this result in a file named ... ?','<one>Gemfile.lock</one>.');
+ 
+You can query the content via:
+
+    .databases
+
+To create this from the commandline, do:
+
+    studium --create-database

data/doc/deprecated_components/deprecated_components.md

@@ -0,0 +1,46 @@
+This file lists some classes that can be considered semi-deprecated.
+Furthermore, this file here may also include some constants that
+have been removed.
+
+At some later point in the future parts that are deprecated may
+be removed; or rewritten. Being listed in this file does not
+automatically mean that the code has been fully removed (yet).
+
+------------------------------------------------------------------------
+
+(1) Studium::ShowLecturesOfThisCurriculumAsTable
+
+This class depended on hardcoded local files (e. g. descriptions
+to lectures stored in .md files).
+
+As the studium project no longer uses .md files for descriptions
+of lectures, the class was no longer doing its old job nor was
+it necessary anymore.
+
+A partial replacement has been written to, at the least, show the
+descriptions of lectures belonging to a particular curriculum at
+hand.
+
+The name of that class is:
+
+    Studium::ShowDescriptionsOfLecturesBelongingToThisModule
+
+On 13.05.2023, the constant FILE_ALLOWED_THEMES_FOR_EXAMS was removed.
+It already was uncommented prior to that day. Users should instead
+use the method Studium.file_allowed_themes_for_courses() instead,
+or its aliased name called Studium.file_allowed_themes_for_exams().
+
+The old code is shown next:
+
+  # ========================================================================= #
+  # === FILE_ALLOWED_THEMES_FOR_EXAMS
+  # ========================================================================= #
+  FILE_ALLOWED_THEMES_FOR_EXAMS =
+    "#{PROJECT_YAML_DIRECTORY}allowed_themes_for_exams.yml"
+
+On the 15.05.2023 the constant FILE_MAIN_TOPIC was deprecated. Use
+Studium.file_main_topic? instead if you need to obtain the same file.
+
+On the 31.05.2023 the directory studium/yaml/meta_themes/ was removed. Its
+contents were integrated into the file grouped_themes.yml instead. A
+symlink was set, pointing from meta_themes towards grouped_themes.

data/doc/documentation_for_the_file_lecture_information/documentation_for_the_file_lecture_information.md

@@ -0,0 +1,311 @@
+This file contains information about the format used in the file
+called "lecture_information.yml".
+
+Ideally you should store ONLY lectures that are:
+
+  (a) important to you
+  (b) difficult to obtain in an automated manner
+
+The format of the file must be like this:
+
+  lecture_id name of the lecture
+
+Available entries are, for instance, the following ones:
+
+  !ruby/symbol ects: 3.0
+  !ruby/symbol sws:  2.0
+  !ruby/symbol university: BOKU
+  !ruby/symbol language: english
+  !ruby/symbol type: VO
+  !ruby/symbol semester: summer
+  !ruby/symbol grade: 2
+
+Grade refers to the grade of the passed lecture, e. g. 1 or 2 or 3
+or 4 or 5 (or any other values, including A, B, C and so forth).
+
+type: can be of VO, VU, UE, PR, SE, VO+SE right now.
+
+The entry "!ruby/symbol currently_participating_in_this_course"
+is false by default. If it is set to true then this implies that
+the student at hand is currently participating in this course.
+This may then be colourized a bit more intently by some classes
+of the studium-gem, to indicate more important courses right
+now. Other than that it is not a hugely important entry, but
+if you are presently attending a given lecture, it is
+recommended to toggle this entry to true.
+
+Next follows a line for this that can simply be used for
+copy/pasting, if you are participating in this course and need
+to add this to the .yml file mentioned above:
+
+  !ruby/symbol currently_participating_in_this_course: true
+
+---------------------------------------------------------------------
+
+The entry "!ruby/symbol semester:" can be of the following three
+values:
+
+  winter
+  summer
+  both
+
+This means that a lecture is either offered during the winter-course
+only, during the summer-course only, or in both terms.
+
+---------------------------------------------------------------------
+
+The entry 'registered_for_an_upcoming_exam_at:' can be used to
+denote an upcoming exams. If you wish to take an exam at a specific
+date, but haven't yet registered for it, you can use the entry
+called 'not_yet_registered_for_an_upcoming_exam_at' instead, and
+lateron change it to 'registered_for_an_upcoming_exam_at' when
+you have registered indeed. Note that since as of 2021 or so,
+this has been shortened to just 'registered'. It was easier to
+use this shorter name, in particular when you want to denote
+to which exams you are registered, when this may change again.
+
+---------------------------------------------------------------------
+
+The optional symbol-entry !ruby/symbol exam_registration_at:
+determines at which point one can register for a given exam.
+This allows us to plan ahead at which point we can register.
+
+An example how this looks like will be shown next:
+
+  !ruby/symbol exam_registration_at:
+   - "02.08.2019, 08:00"
+
+---------------------------------------------------------------------
+
+The entry 'preparatory_meetings' is to be used to denote at which
+time preliminary (preparatory) meetings are to be held for
+the given lecture at hand. In german this is called
+"Vorbesprechung".
+
+This is sometimes necessary in order to partake in a practical
+course that allows only a limited number of students to
+participate.
+
+The entry curricula should be kept within single quotes aka
+'' rather than "". This has no particular reason other than
+enforcing the same quote-style; I find it simpler to have
+a consistent styl here, rather than mix the two variants
+randomly.
+
+---------------------------------------------------------------------
+The symbol called :priority_points can be used to denote which
+lectures are especially important in a curriculum. This can
+then be used to automatically determine which lectures should
+be integrated into a individual curriculum. Presently, the
+maximum amount of points that can be used here is 1000 - only
+one lecture may have this value. Then comes 999, 998 and so
+forth. ( !ruby/symbol priority_points: 1000 )
+
+The array at 'lecturers' denotes which lecturers hold this given
+lecture. This may change from semester to semester, and thus is
+quite volatile; I recommend to not pay too much attention to it
+and to not become too dependent on the information.
+
+The entry !ruby/symbol is_a_steop_lecture: true means that the given
+lecture is a STEOP lecture - part of a STEOP phase. By default, all
+lectures have false at this setting.
+
+The entry !ruby/symbol outdated_lecture: true means that the lecture
+is no longer offered by the given university. In other words, it can
+no longer be used for an individual curriculum.
+
+The entry "!ruby/symbol description: |", without the quotes, can be
+used to describe the lecture at hand. This may happen in any
+language. For example, I use german for lectures that are held
+in german in universities of austria.
+
+The entry "lva_dates" denotes the dates of these lectures, e. g. when
+this lecture is being held.
+
+The entry "!ruby/symbol module:", an Array, denotes to which modules
+this entry belongs to. This can be useful for automatically inferring
+which lectures belong to which module. A longer name is useful here,
+as the chance to conflict with modules listed in different curricula
+but named the same, is lessened. If there is more than one entry
+listed here then this means that this may belong to more than one
+curriculum. In this case we will favour the first entry, IF we have
+to favour any entry at all that is. Note that the entry
+"!ruby/symbol individual_curriculum_module:" is like the entry
+"!ruby/symbol module:" except that it is only valid for my
+individual curriculum.
+
+---------------------------------------------------------------------
+
+The entry "!ruby/symbol depends_on_these_modules:" denotes on
+which other modules this module depends. The similar entry called
+"!ruby/symbol individual_curriculum_depends_on_these_modules:"
+is valid for lectures that are part of an individual curriculum.
+I needed to use separate entries here so that we can still keep
+track of "official" curricula with their module-system.
+
+---------------------------------------------------------------------
+
+The entry "!ruby/symbol description_in_english: |" is guaranteed to
+be an english representation of the content of said lecture. It is
+especially useful if you wish to describe your curriculum to an
+audience that understands the english language rather than the
+german language.
+
+The entry !ruby/symbol homepage: should point to the most important
+URL of this lecture - the homepage. This will also be used to
+autogenerate a .rb file that holds a menu pointing to these remote
+URLs, via a case/when menu interface (and regexes inside that).
+This allows us to programmatically open these remote URLs from
+shorter input.
+
+The entry !ruby/symbol moodle: can be used to point to the course's
+online resources, which typically makes use of the moodle software.
+Since as of February 2021 this can be an Array. In that event,
+the first element must be the most recent course available.
+
+Since as of July 2019, the exam-type can be specified. Valid specifications
+right now include written, oral, and single choice or multiple choice for
+this setting. The entry that governs this is called
+!ruby/symbol exam_format. 5 different formats can be used here.
+
+Examples:
+
+  !ruby/symbol exam_format: single_choice
+  !ruby/symbol exam_format: multiple_choice
+  !ruby/symbol exam_format: oral
+  !ruby/symbol exam_format: written
+  !ruby/symbol exam_format: continuous_presence
+
+The entry:
+
+ !ruby/symbol sws: 3.0
+
+refers to "Semesterwochenstunden". This is the number of hours per
+week of this course, per semester. So a value of 3.0 means that the
+students have to invest 3 hours per week into the lecture directly,
+e. g. via participation on-site. (The number of ECTS required for
+a given course is a more useful indicator, though.)
+
+---------------------------------------------------------------------
+
+The entry:
+
+  !ruby/symbol sws:  2.0
+
+refers to "Semesterwochendstunden", aka hours taught per given week,
+where students may attend to the course and learn something new
+(hopefully). It is vaguely related to the ects: entry, but not as
+important anymore in my opinion.
+
+---------------------------------------------------------------------
+
+The entry:
+
+  !ruby/symbol boku_three_pillars: 40/50/10
+
+is important only at the BOKU, since the BOKU makes use of a 
+"three pillars" concept.
+
+---------------------------------------------------------------------
+
+The entry:
+
+  !ruby/symbol url_to_exam_questions: https://www.univie.ac.at/stv-biologie/forum/viewtopic.php?f=120&t=17017
+
+can be used to provide an URL to some exam questions for a given
+lecture; usually compiled by the students. This may also include
+old (outdated) exam questions, so keep this in mind.
+
+---------------------------------------------------------------------
+
+The entry:
+
+  !ruby/symbol wiki: https://vowi.fsinf.at/wiki/TU_Wien:Betriebssysteme_VO_%28Puschner%29
+
+can be used to provide an URL to the wiki of a course; typically
+this refers to a wiki maintained and operated by the students,
+but it may also refer to any wiki in general.
+
+---------------------------------------------------------------------
+
+The entry:
+
+  !ruby/symbol university:
+
+has these valid possibilities: BOKU, TU Vienna.
+
+---------------------------------------------------------------------
+
+The entry:
+
+  !ruby/symbol url_to_exam_registration: https://online.boku.ac.at/BOKUonline/wbExamOffer.wbExamsOfCourse?pCourseNr=288193
+
+can be used to register a direct URL to the exam registration.
+That way the user can quickly open that URL and register for
+such an exam.
+
+---------------------------------------------------------------------
+
+The entry:
+
+  !ruby/symbol url_to_videos: https://www.youtube.com/channel/UCSTgIH6RlNWn_FCN5TpSRgw/
+
+can be used to denote the URL to some videos associated with a lecture.
+That way the user can quickly watch important videos.
+
+Currently this is limited (or encouraged to limit) to only one entry,
+but in the future this may have to become an Array, to allow multiple
+video entries instead.
+
+---------------------------------------------------------------------
+
+The entry:
+
+  !ruby/symbol is_an_elective_course: true
+
+refers to an elective course, a "Wahlfach". The default value here is
+false.
+
+The reason why this was added was so that a script can calculate how
+many elective courses are part of a given individual curriculum at
+hand. I am not sure if this is really necessary, but in the worst
+case it simply is additional information, so no real harm done when
+it is used.
+
+---------------------------------------------------------------------
+
+The entry:
+
+  !ruby/symbol zoom_link: https://bokuvienna.zoom.us/j/215409204
+
+can be used to specify a specific zoom link to a lecture. This
+will not work for all lectures, naturally, but simply can be
+used as providing additional information.
+
+---------------------------------------------------------------------
+The entry:
+
+  !ruby/symbol extra_information: |
+
+added on the 03.10.2020, can be used to add additional information
+to a course. This can include additional links or information
+which may be useful to other students or to you. It is kept 
+either in english or german typically, but there are no
+restrictions as to which languages are allowed here.
+
+Example how to use this, in german, for secondary downloads to
+a course's content:
+
+    Neue Unterlagen sind zu finden auf:
+
+      https://www.abc.de/xyz
+      Username: abc
+      Password: def
+---------------------------------------------------------------------
+The entries:
+
+  !ruby/symbol zoom_meeting_id: 971 7398 3518
+  !ruby/symbol zoom_kenncode:   913893
+
+can be used in combination with zoom-based courses.
+---------------------------------------------------------------------

data/doc/elegant_colours/elegant_colours.md

@@ -0,0 +1,21 @@
+For the various exam questions and their corresponding answers, I
+consider the following foreground colours to be elegant on a black
+background:
+
+For questions:
+
+  - teal
+  - lightseagreen
+  - lime
+  - peru
+
+For answers:
+
+  - steelblue
+  - mediumturquoise
+  - mediumseagreen
+  - springgreen (for true emphasis)
+
+This file here just collects potentially useful colours in such
+a scenario, in the event that I may wish to modify the colours
+that are used - or add to this list.

data/doc/statistics/yearly_statistics.md

@@ -0,0 +1,8 @@
+The idea here is to store some data on a yearly basis e. g. end of a
+year. Ideally only store one data point per year.
+
+30.12.2022: 44.212 exam questions, of which 12442 were
+            answered already (28.14%).
+
+24.06.2023: We already solved 12070 of 46.423 available questions. (26.0% solved).
+^^^^ this is not yet complete

data/doc/todo/todo_for_the_graphical_parts_of_the_studium_gem_including_www_related_aspects.md

@@ -0,0 +1,92 @@
+--------------------------------------------------------------------------------
+(1) → in the studium gem add a jruby-swing interface and then TEST it
+      on windows. The interface should work on windows !!!!!!!!
+--------------------------------------------------------------------------------
+(2) → Improve the sinatra interface of studium gem, also visually. make it
+      an alternative to the studium-gtk variant in the long run - at the
+      least so that it works.
+      And add a .cgi file.
+      ^^^ this was done in 2021 but needs more improvements still.
+--------------------------------------------------------------------------------
+(3) → in studium-gtk:
+      - add lecture-related information, as list-store. we want to show the
+      individual lectures. all of them.
+      ^^^ this now exists, but we have to style it a little bit more.
+--------------------------------------------------------------------------------
+(4) → In the gtk3-wrapper, we need to add support for clickable
+      hyperlinks in the text-buffer. This works semi-well; we need
+      to determine the start and end iters, and then act on these.
+      Right now we just parse the whole thing and have the first
+      entry be clickable. This will work for most entries, but
+      it would be better to distinguish this.
+      Also change the colours to blue-ish once that works.
+--------------------------------------------------------------------------------
+(5) → Add a progressbar
+      create_the_progress_bar
+      but only if the check button is active. then when the user hits
+      the start button, it will pulse. But where is this one added?
+--------------------------------------------------------------------------------
+(6) → Add the editor to the studium3 gui,
+      so that we can modify the content without depending on
+      bluefish. And one day also write jruby code for that.
+--------------------------------------------------------------------------------
+(7) → We need an easier way to find out when a question has been
+      asked happened.
+      Add some way for the studium gem to see which answers were
+      asked during the last run or something like that... hmm some
+      log file or so...
+      daily exam questions
+      and then document it too.
+      perhaps just make some log that logs into a file.
+      Stored as a hash in a yaml file.
+      Studium::Log::StoreLastQuestionAskedIntoFile
+      ^^^ That log now exists, but what is still missing is a
+      way to easily check whether a question was already asked
+      or not. Perhaps we need a second "solved" alias that also
+      checks whether the question has already been asked or not
+      today.
+      daily_exam_questions/daily_exam_questions.md
+      ^^^ actually store this as-is on a daily basis no matter what.
+      once that works we can think of other additions.
+--------------------------------------------------------------------------------
+(8) → add multiple curricula into the gtk-widget.
+--------------------------------------------------------------------------------
+(9) → We need a script or a method that can parse a remote lecture,
+      such as at the university of vienna, and tell us
+      all information, including the curricula of this
+      course. also so that we can copy/paste this as-is.
+--------------------------------------------------------------------------------
+(10) → Module M1 Technische Grundlagen der Informatik und Orientierung im Studium [7.0 ECTS in this module]
+      ^^^ hier müssen wir noch die module hinzufügen für
+      "handle_curricula.rb"
+      ^^^^^^^
+      this works ok-ish.
+--------------------------------------------------------------------------------
+(11) → Add a Web component interface so that we can ask the questions
+      via a .cgi file as well.
+      ^^^^^^^^^^^^^
+--------------------------------------------------------------------------------
+(12) → We need to automatically register for a specific exam at a specific
+      date, without being forced to manually do so.
+--------------------------------------------------------------------------------
+(13) → In www/*cgi, we need a dropdown box, and also a way to select between
+      different curricula, for display - and pretty the output too, since
+      some things are broken.
+      ^^^^^^ hmm
+      should perhaps rewrite the studium project......
+      after rewriting the cyberweb project. :P
+--------------------------------------------------------------------------------
+(14) → in the studium gem,
+      we could create new gtk3-bindings for some parts
+      hmmm
+      display everything in a single app with tabs or so
+      with individual widgets
+      ^^^ yeah \o/
+--------------------------------------------------------------------------------
+(15) → Im sinatra-interface: add  class Studium::Exams::UpcomingExams
+      wir sollten eine toplevel-methode ^^^ da machen. dann ist
+      das displayen auch einfacher.
+--------------------------------------------------------------------------------
+(16) → next_generation_exam_question_trainer.cgi
+      ^^^ fix this
+--------------------------------------------------------------------------------

data/doc/todo/todo_for_the_studium_gem.md

@@ -0,0 +1,55 @@
+--------------------------------------------------------------------------------
+(1) → We need an easier way to find out when a question has been
+      asked happened.
+      Add some way for the studium gem to see which answers were
+      asked during the last run or something like that... hmm some
+      log file or so...
+      daily exam questions
+      and then document it too.
+      perhaps just make some log that logs into a file.
+      Stored as a hash in a yaml file.
+      Studium::Log::StoreLastQuestionAskedIntoFile
+      ^^^ That log now exists, but what is still missing is a
+      way to easily check whether a question was already asked
+      or not. Perhaps we need a second "solved" alias that also
+      checks whether the question has already been asked or not
+      today.
+      daily_exam_questions/daily_exam_questions.md
+      ^^^ actually store this as-is on a daily basis no matter what.
+      once that works we can think of other additions.
+--------------------------------------------------------------------------------
+(2) → We need a script or a method that can parse a remote lecture,
+      such as at the university of vienna, and tell us
+      all information, including the curricula of this
+      course. also so that we can copy/paste this as-is.
+--------------------------------------------------------------------------------
+(3) → Module M1 Technische Grundlagen der Informatik und Orientierung im Studium [7.0 ECTS in this module]
+      ^^^ hier müssen wir noch die module hinzufügen für
+      "handle_curricula.rb"
+      ^^^^^^^
+      this works ok-ish.
+--------------------------------------------------------------------------------
+(4) → We need to automatically register for a specific exam at a specific
+      date, without being forced to manually do so.
+--------------------------------------------------------------------------------
+(5) → In www/*cgi, we need a dropdown box, and also a way to select between
+      different curricula, for display - and pretty the output too, since
+      some things are broken.
+      ^^^^^^ hmm
+      should perhaps rewrite the studium project......
+      after rewriting the cyberweb project. :P
+--------------------------------------------------------------------------------
+(6) → in the studium gem,
+      we could create new gtk3-bindings for some parts
+      hmmm
+      display everything in a single app with tabs or so
+      with individual widgets
+      ^^^ yeah \o/
+--------------------------------------------------------------------------------
+(7) → Im sinatra-interface: add  class Studium::Exams::UpcomingExams
+      wir sollten eine toplevel-methode ^^^ da machen. dann ist
+      das displayen auch einfacher.
+--------------------------------------------------------------------------------
+(8) → next_generation_exam_question_trainer.cgi
+      ^^^ fix this
+--------------------------------------------------------------------------------

data/lib/studium/autoinclude.rb

@@ -0,0 +1,7 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'studium'
+
+include Studium