studium 0.13.1

data/doc/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.md

@@ -0,0 +1,24 @@
+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

data/doc/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.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/todo/TODO_FOR_STUDIUM_GEM.md

@@ -0,0 +1,112 @@
+--------------------------------------------------------------------------------
+(1) theme of exams ... eventuell. Yup langsam entfernen. Aber das hat
+keine riesige Priorität.
+
+    bl /home/x/studium/YAML/theme_of_exams.yml
+
+theme_of_exams.yml
+
+^^^ this is deprecated - should be removed in the long run.
+
+
+^^^ eliminieren und in lecture_information integrieren, dann
+   uploaden.
+
+in file_lecture integrieren... dann hätten wir auch alle
+alten... na das geht nicht, wir müssen wohl
+duplikate verwenden. aber mach das dennoch damit wir
+mal all die information haben.
+also mal die alten prüfungen durcharbeiten... beginnend
+mit 2009 oder so.
+
+^^^
+nach dem rewrite noch doku hinfzuügen
+dann das gane hochladen.
+^^^ doku fehlt noch tja.
+
+^^^ AND REWRITE THE PROJECT TOO
+
+--------------------------------------------------------------------------------
+(2) - Add a Web component interface so that we can ask the questions
+      via a .cgi file as well.
+^^^^^^^^^^^^^
+--------------------------------------------------------------------------------
+(3) - We need to automatically register for a specific exam at a specific
+      date, without being forced to manually do so.
+--------------------------------------------------------------------------------
+(4) - 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
+
+--------------------------------------------------------------
+(5) - 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...
+
+   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.
+--------------------------------------------------------------------------------
+- Extend the gtk-GUI component:
+
+  -> Add a search box where we can select a topic such as:
+     "evo" ENTER
+     -> will jump to the right entry.
+
+  This can possibly be implemented via Gtk::EntryCompletion.
+
+------------------------------------------------------------------------------
+(5)
+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/
+
+------------------------------------------------------
+lvaexpander 19.12.2019-04.01.2020
+
+Traceback (most recent call last):
+        12: from /home/x/DATA/PROGRAMMING_LANGUAGES/RUBY/src/studium/lib/studium/utility_scripts/expand_time_range.rb:375:in `<main>'
+        11: from /home/x/DATA/PROGRAMMING_LANGUAGES/RUBY/src/studium/lib/studium/utility_scripts/expand_time_range.rb:375:in `new'
+        10: from /home/x/DATA/PROGRAMMING_LANGUAGES/RUBY/src/studium/lib/studium/utility_scripts/expand_time_range.rb:50:in `initialize'
+         9: from /home/x/DATA/PROGRAMMING_LANGUAGES/RUBY/src/studium/lib/studium/utility_scripts/expand_time_range.rb:341:in `run'
+         8: from /home/x/DATA/PROGRAMMING_LANGUAGES/RUBY/src/studium/lib/studium/utility_scripts/expand_time_range.rb:312:in `expand_and_show_the_dates_in_between'
+         7: from /home/x/DATA/PROGRAMMING_LANGUAGES/RUBY/src/studium/lib/studium/utility_scripts/expand_time_range.rb:292:in `return_array_of_days_between_this_start_and_this_end_range'
+         6: from /home/x/DATA/PROGRAMMING_LANGUAGES/RUBY/src/studium/lib/studium/utility_scripts/expand_time_range.rb:302:in `remove_weekends_from_this_array'
+         5: from /home/x/DATA/PROGRAMMING_LANGUAGES/RUBY/src/studium/lib/studium/utility_scripts/expand_time_range.rb:302:in `reject'
+         4: from /home/x/DATA/PROGRAMMING_LANGUAGES/RUBY/src/studium/lib/studium/utility_scripts/expand_time_range.rb:303:in `block in remove_weekends_from_this_array'
+         3: from /home/Programs/Ruby/2.6.5/lib/ruby/site_ruby/2.6.0/studium/base/time.rb:254:in `weekday?'
+         2: from /home/Programs/Ruby/2.6.5/lib/ruby/2.6.0/time.rb:375:in `parse'
+         1: from /home/Programs/Ruby/2.6.5/lib/ruby/2.6.0/time.rb:266:in `make_time'
+/home/Programs/Ruby/2.6.5/lib/ruby/2.6.0/time.rb:266:in `local': mon out of range (ArgumentError)
+
+^^^ fix this
+
+--------------------------------------------------------------------------------
+- Im sinatra-interface: add  class Studium::Exams::UpcomingExams
+  wir sollten eine toplevel-methode ^^^ da machen. dann ist
+  das displayen auch einfacher.
+--------------------------------------------------------------------------------
+- add multiple curricula into the gtk-widget.
+--------------------------------------------------------------------------------

data/doc/todo/TODO_FOR_THE_GRAPHICAL_PARTS_OF_THE_STUDIUM_GEM_INCLUDING_WWW_RELATED_ASPECTS.md

@@ -0,0 +1,35 @@
+------------------------------------------------------------------------------- 
+(2) - in the studium gem add a jruby-swing interface and then TEST it 
+      on windows. the interface should work on windows!!!!
+
+-------------------------------------------------------------------------------
+(1) 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.
+-------------------------------------------------------------------------------
+(1) 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.
+-------------------------------------------------------------------------------
+(2) 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.
+-------------------------------------------------------------------------------
+(3) 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?
+
+-------------------------------------------------------------------------------

data/lib/studium/autoinclude.rb

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