As a quick example, consider the following text input file called
demoA_1.csv, that describes four events:
This means that on Monday (M) of week 30, the student-group A will have:
Additionaly, it also says that thursday is off.
Then, if you run from shell the following command:
it will generate a folder named
demoA_1 in which you can find this html page.
Now lets see a slightly more complex example covering two weeks and two groups of students, A and B. The following file:
will generate this html page.
So you got the point: a line in the input file describes an event, which holds:
and its duration, expressed as the number of time slots. More on this in the following section.
As opposed to traditional calendar software, where all events have an arbitrary time of start and duration, gensched is targeted at scholar or university scheduling: with this type of schedule, the schools organization is based on some grid: we have common opening hours, the courses start all at the same time, have the same length, so groups of students can switch from one class room to another.
So the software is based on the concept of time slot: an events starts at some point in this grid, and has a length that is a multiple of an atomic lenth. This one is usually 60 or 90 minutes, you can define this.
Input data is based on the concept of event. An event is a line of text in the input file, as seen above. It can be of two types: a regular event or a special event.
A regular event is just some teaching event. It has the following items:
The input data is basically a list of events as described above, using the classical csv format. It does not need to be sorted in any way. Empty lines are allowed.
All the codes used in the samples above can be personnalized, we'll get to this later. If some information is unknown (say, you don't know who will take in charge some course, or you don't know what rooms will be available), then you can signal this by using some special code for this field. See Option: -f (deFaults).
Additionaly, events can have a "comment" field, that will be used as html cell title, so it appears when hovering over with mouse.
Special events are identified by a "group" field prefixed with '*'. They are two kinds special events:
For "off" days, it is produced by setting the "group" field to the string
*OFF. This event in the input file will have two consequences:
The text appearing in the schedule will be generic ("OFF" at present), unless the event has the "comment" field not empty. In that case, it is this latter text that will appear.
Non-teaching events are identified by a
*SPE, in "group type" field. These are used for meetings, or any other stuff not related to teaching. These events hold all the stuff of regular events (except for "group type", of course). The only difference is that these events do not count as work time for the instructors.
If you want to use this software, the workflow is as follows:
While it is possible to manually edit small csv files with a basic text editor, using a spreadsheet software has many advantages. The biggest is the ability to use so-called "auto-filters", so you can show only part of the data. For example, say you have a file of ~1000 events. Searching through these to find the one occurring on a given week and a day with a given instructor, just to change the room, this will be tedious. Instead, with the auto-filters, you can select the needed criterions until you find what you want, then edit the data, and save the file. Below is a figure showing the usage of Libreoffice-calc for this task.
Once you have edited the file, all you need to do is to save the whole file as a csv file (File->Save As). As this task has to be done each time, it is easier to record a macro that automates this. Then, add a button in the toolbar and associate it with the macro.
Once in a while, you may provide some input data that has some problems. These can be of two types:
For the first point, invalid lines in the input file will be shown on the "stats" page, and will be ignored for the rest of the process. For the second point, four types of inconsistencies are handled:
All of these are filed and a special page is generated that summarizes all the conflicts that were encountered during the process. Besides, on the schedule page, the events that are in a conflicted state are shown with a special color, and the table cell has an additional "title" attribute showing the nature of the conflict. By hovering the mouse on it, the user can immediatly see what the problem is. A special warning is also printed at the bottom of the table, with the total number of conflicts on this week and a link on the dedicated page.
But lets see an example. Lets consider this sample input file: demoA_3.csv
At first, it is not obvious to see where the problems are. But processing this file will generate this schedule page.
Several conflicts appear on this week. Conveniently, a link at the bottom of the week leads to the generated "conflicts" page, where a more detailed description is given. Besides, hovering with the mouse over the conflicted cells gives some information about the nature of the conflict, as it can be seen below:
Also, you might have noticed that the last three lines of the above input file are invalid. One uses "T" for "Tuesday", instead of "Tu". Another has "AZ2" as time slot code, which is invalid. The last line uses "AGH" as group type field, which is also invalid. This is detected at runtime, and these events are ignored. They appear as such on the relevant stats page, so user can check out and correct his input file. Moreover, the main index page mentions the number of invalid lines, if any.
Besides the actual html schedule,
gensched generates several other html files that are linked through an index, see this file for example. These files will be inside a folder named from the input files that will be created at runtime . Additionaly, other input files can be provided, so the real diagram is more like this:
The auxiliary input files serve different purposes, and must be described separatly:
gensched.iniholds all the general configuration of the software. It is optional (it can run without), default values are provided. But if present in the current folder, it will be automatically read and used.
groups.ini(or any name you want as long as it has the .ini extension) is optional. It is required if you need to describe a complex groups structure, see Option: -g <groups_file> and Describing complex groups.
volumes.refis also optional. It is a csv data file that can be used to provide a reference course volume per each subject, that will be printed out on the page "Volume per group per subject" on first line, to enable checking that the schedule provides enough volume of courses for every subject. See Including reference volume.
This generated index page links to:
See for example index.
This first two examples (see Samples ) describe the simplest situation where you have one type of "groups". However, in real life, it gets more complicated. gensched allows you to deal with all kinds of situations.
First, a course has a type: it can be designed as a lab work, a class work, or a classical course where the instructor gives a talk (aka a "lecture"). Usually, this is also related to the number of students: small group for a lab, class group, or several groups in a large conference room. In France, this is usually called TP ("Travaux Pratiques"), TD ("Travaux Dirigés"), and CM ("Cours Magistral").
We define the group types as:
The type of course appears in the different tables in the ouput with a codification that is the same as in the input data file. The default codes are:
This can be personnalized by configuration file (see Configuration). French users will replace this with the classical CM/TD/TP.
Thus, for each event, one needs to define both the type of course, and the corresponding student group. If you are in the simplest case where you only handle so-called atomic groups, this list of these is build automatically. Else, the groups must be given through an additional .ini input file, either through command-line or through general configuration file. See for example demoB_4b and the corresponding groups file
; this file holds the trainees groups organisation for demo4 ; this is the list of ALL the student atomic groups [atomic] groups=A,B ; this is the list of class groups [class] groups=Z ; here, there MUST be a line for each of the class groups above Z=A,B
We define here a class group named 'Z', that holds the two atomic groups A and B.
Please notice that in the corresponding input file, we need to specify that the English course is a "class" event, with the code "CG" in the course type.
The third level of groups is the "division" level: see for example demoB_4c, that also has more realistic group names: we have 4 atomic groups named A,B,C,D, two class groups named AB and CD, and one division named ABCD. And, yes, the names of the groups are totally free.
The software has a lot of configuration options. Some options can also be given through command-line (see Command Line Options). Other parameters must be given through configuration file (
gensched.ini), that is read at startup. Some can be given both ways, in that case the command-line options overrides the values given in configuration file.
The format of the files follows classical "ini" files, see http://en.wikipedia.org/wiki/INI_file, and whose structure match the following example:
; gensched.ini [section1] parameter1=hehehe parameter2=hohoho
The configuration file allows to change many things in the default behaviour of the software, in many aspects. It is a regular "ini" file. The default behaviour is to check for a file named
gensched.ini, but if command-line option -p if used, one can provide a configuration file with any name.
The order of fields in the input file can be changed, through a section named
InputFileFields. Below is an example of such a section, showing the allowed field names. Beware, if not present, the field index keeps its default value, and it could conflict with one of the given values. This is checked after loading of the file.
[calendar] is there to mention the current year. All dates are automatically computed from week numbers and week days.
[general] allows changing some global options, for example:
NbTimeSlotsAMholds the number of time slots in the morning. It is used to add a separation line in the output schedule for lunchtime. If you do not want such a separation, just add
PrintNoonSepLine=0in the file.
atomic_durationis the duration, expressed in hours, of the root time slot unit. For example, if equal to 1.5, this means that each time slot is 90 minutes.
NbDaysare needed and requested only if you need to personnalize the codes and names for, respectively, time slots and days.
Besides the above pairs, a number of boolean switches can be set (
=1) or unset (
=0) though this configuration file. Their description can be seen here. Some of these can be overriden by a command-line switch, see Command Line Options. To see their default values, check Option: -f (deFaults).
Command line option
|If true, the divisions will be printed out on separate pages. This can be needed when many divisions to avoid a cluttered page.|
|If true, the different weeks will be printed out on separate pages. Can be useful |
to lighten page and speed up download, in case of many weeks with heavy content.
|If true, the automatic cell colors will be set depending on the "subject" field.|
Else, it will be set according to the "instructor" field.
|If true, each week day will hold its date in table header.|
|If true, each field with the predefined "unknown" field will be printed out as such.|
Set this to false will only show the known information.
|Set this to true if you wan the output folder to be time stamped, so you can later compare different versions.|
|If true, the type of the event will be printed in each schedule cell. Set to false if unneeded.|
|Set to false if you don't want a noon separation line.|
|Set this to false if you have personnalized style sheets, so they don't don't get overwritten by the default ones at every run.|
|Set this to false if you don't want on the schedule page the special markup for events that hold a comment.|
This section is used to give the names of the class types as they appear in the output html tables, and as they are given in the input file. In France, this should stay as follows:
[sectioning] atomic_name=TP class_name=TD division_name=CM
day_names allow for personnalizing code/names for days. Adding these sections requires adding a key
NbDays in section
general, see General.
Any combination is possible, for example, french users will probably want this:
[day_codes] day0=L day1=Ma day2=Me day3=J day4=V [day_names] day0=Lundi day1=Mardi day2=Mercredi day3=Jeudi day4=Vendredi
Be aware, that these two sections are closely related and must have the same number of items, and items of both lists will match.
TS_names allow for personnalizing code/names for time slots. The "code" if for what will be read in the input data file, the "value" is what will be printed out on the schedule page. Be aware that these are just textual tags, and have no meaningful duration information.
Similarly to previous section, this requires adding a key
As an example, these are the codes and values for 90mn slots, identified by "Ax" for "AM" time slots, and "Px" for "PM "time slots.
[TS_codes] TS0=M1 TS1=M2 TS2=A1 TS3=A2 TS4=A3 TS5=A4 [TS_names] TS0=8h30 TS1=10h TS2=13h TS3=14h30 TS4=16h TS5=17h30
In order to compare actual course volumes with a "reference" volume, you can provide this reference as an additional csv file holding for each subject and for each course type the volume reference. This volume will then automatically appear in the "volume per subject" page, see this for example.
The volume is given in the form subject,volume:
; volume reference file for demoD_full ; holds course volumes for each type of groups ; order: Subject, Lecture volume, Class volume, Lab volume Astronomy,4,5,12 Biology,2,4,15 Chemistry,0,20,2 Comp.Sci.,15,5,5 Engineering,5,10,10 Literature,10,5,0 WebD,0,5,5 Maths,3,10,30 Physics,5,5,15 # some random comment and empty line Psychology,15,4,4 Sociology,2,5,6
This software can produce output in any language at run-time, as long as the corresponding language file is provided. English is the default language, but a french language file is also provided in current release, feel free to submit other language files.
The system is based on a local key, build using an enum. Check file LF_fr.ini as an example.
The choice of language is done through a command-line option, see Option: -l <language_code>.
If you add a language file, you need to add the corresponding language code in source file main.cpp (check for gv_LangCodes), and rebuild the software (see Building the software).
The general syntax is:
gensched [options] input_file
For other configuration not accessible through command-line, see Configuration.
Prints a short help message and exits.
Starts the default browser and shows full doc from local files, then exits.
If given, enable "debug" mode: lots of run-time information is dumped in stderr. Running in this mode should be done with stderr redirected, i.e.:
Prints the default configuration values (groups code, week days names and codes, unknown information codes, ...) and exits.
fr(French) is provided.
If given, copy of standard CSS stylesheets in output folder will not be done. This option is needed if user wants to provide his own stylesheets, or if he has edited the standard ones after a first run.
This flag enables the "verbose" mode, giving some more output
Enables the user to select which weeks he want to extract from the input data.
If not given, the week set will be build automatically from input file and the weeks will be ordered. This is handy, but in many situations (scholar year), the semester starts around week 35 to 39 (september), goes until end of december, and continues often with week 2 and 3 in january. Thus, this automatic mode is not suitable because week 2 will appear before week 36.
This option can be used to give the desired weeks in the desired order, and only those will appear in the ouput, independently of the data in the input file. If a requested week has not events in the input file, then the schedule for that week will appear empty.
gensched -w "34,40,50" myfile.csv
will extract only weeks 34, 40 and 50 from input file
gensched -w "34-36,50" myfile.csv
will extract only weeks 34, 35, 36 and 50 from input file
gensched -w "34-36,50-51,2" myfile.csv
will extract only weeks 34, 35, 36, 50, 51 and 2 from input file
Checking is done to make sure that user doesn't request something invalid, for example the following line:
gensched -w "36-34"
will fail, as it doesn't really make sense to print out weeks in reverse order. But the following:
gensched -w "36,35,34"
If given, then the course types will not be printed in schedule page table cells.
Load file.ini as configuration file instead of the default gensched.ini
If used, then the colors in the schedule page will be related to the instructor (default is related to the subject)
Overrides the year given in configuration file
Using command-line with Option: -f (deFaults), here are the default values given by current build: