User Manual

Summary:


Introduction

Short basic example

As a quick example, consider the following text input file called demoA_1.csv, that describes four events:

# week, day, timeslot, group, type, subject, room, instructor, duration, comment
30,M,M1,A,AG,Math,A1,Joe,1
30,M,M2,A,AG,Physics,A1,Bill,1
30,M,A1,A,AG,English,A1,Susan,2
30,Th,xx,xx,*OFF,xxx,xx,xxxx,1,Valentines Day

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:

gensched demoA_1.csv

it will generate a folder named demoA_1 in which you can find this html page.

demoA_1_cropped.png

Now lets see a slightly more complex example covering two weeks and two groups of students, A and B. The following file:

# week, day, timeslot, group, type, subject, room, instructor, duration, comment
30,M,M1,A,AG,Math,R1,F. Sinatra,1,
30,M,M2,A,AG,Physics,R3,L. DiCaprio,1,
30,M,M3,A,AG,English,R3,J. Wayne,1,
30,M,M1,B,AG,Chemistry,RRR,J. Wayne,2,
30,M,M3,B,AG,Math,R1,M. X,1,
30,Tu,M2,B,AG,S???,R1,J. Wayne,1,
31,Tu,M1,A,AG,Math,R1,F. Sinatra,1,
31,Tu,M2,A,AG,Physics,R1,L. DiCaprio,1,
31,Tu,M3,A,AG,English,R2,J. Wayne,1,
31,Tu,M1,B,AG,Chemistry,R2,J. Wayne,2,
31,Tu,M3,B,AG,Math,R1,F. Sinatra,1,

will generate this html page.

demoA_2_cropped.png

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.

Basic Concepts

Grid-based time slots

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.

Events

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

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.

Workflow

If you want to use this software, the workflow is as follows:

  1. : edit the input csv file with your data, manually or more conveniently by using a spreadsheet software. This way, you can hold your data in some independent file, and use the spreadsheet to export to csv. See Using with LibreOffice
  2. : run gensched (manually, or more conveniently through a script you have written previously. See Command Line Options),
  3. : check output files, and in case of remaining conflicts, go back to step 1.
  4. : publish output html files online through ftp, or by mail after printing as pdf files, ... or whatever you want.

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.

spreadsheet_1.png

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.


Handling conflicts in input data

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

# week, day, timeslot, group, type, subject, room, instructor, duration, comment
30,M,M1,A,AG,Math,R1,F. Sinatra,1,
30,M,M2,A,AG,Physics,R3,L. DiCaprio,1,
30,M,M3,A,AG,English,R3,J. Wayne,1,
30,M,M1,B,AG,Chemistry,R2,J. Wayne,2,
30,M,M3,B,AG,Math,R3,F. Sinatra,1,
30,Tu,M1,A,AG,Math,R1,F. Sinatra,1,
30,Tu,M2,A,AG,Physics,R1,L. DiCaprio,1,
30,Tu,M3,A,AG,English,R2,J. Wayne,1,
30,Tu,M1,B,AG,Chemistry,R2,F. Sinatra,2,
30,Tu,M3,B,AG,Math,R1,F. Sinatra,1,
30,W,M1,A,AG,Math,R1,F. Sinatra,1,
30,W,M1,A,AG,Physics,R4,L. DiCaprio,1,
30,W,M2,A,AG,English,R2,J. Wayne,1,
30,W,M2,B,AG,Chemistry,R3,T. Hanks,2,In replacement of F. Sinatra
30,T,A1,B,AG,German,R4,T. Selleck,1
30,Tu,AZ2,B,AG,French,R6,P. Newman,1
30,Tu,A3,B,AGH,Russian,R7,P. Sellers,1
30,Th,A1,A,*OFF,xxxxx,A1,ccccc,2
30,Th,A2,B,AG,French,R6,P. Newman,1
30,Tu,A1,A,AG,English,A1,Susan,1
30,Tu,A1,B,AG,Russian,R7,P. Sellers,1
31,Th,A1,A,*OFF,xxxxx,A1,ccccc,2,special meeting day
32,Tu,A3,B,AG,Russian,R7,P. Sellers,3
32,M,M2,B,AG,Russian,R7,P. Sellers,2
32,W,M2,B,AG,Russian,R7,P. Sellers,3
# duplicated events
30,Tu,M3,A,AG,English,R2,J. Wayne,1,
30,Tu,M1,B,AG,Chemistry,R2,F. Sinatra,2,

At first, it is not obvious to see where the problems are. But processing this file will generate this schedule page.

demoA_3_cropped.png

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:

conflict_sample_1.png

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.


Input and output files

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:

ditaa_2.png

The auxiliary input files serve different purposes, and must be described separatly:

This generated index page links to:

See for example index.


Describing complex groups

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 demo/groups_demoB_4b.ini:

; 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.

Warning
It is required that in the "groups" file, the atomic groups are given first, to ensure at reading that other groups only use atomic groups that have been registered.

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.


Configuration

Section summary:

  1. Configuration file
  2. Including reference volume
  3. Internationalization
  4. Command Line Options
  5. Current defaults values

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 current run-time options can be checked directly from shell with Option: -f (deFaults), but main options are also printed in output files in a separate "help" page, see for example this page.

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.

Input data fields

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.

[InputFileFields]
week = 0
day = 1
timeslot = 2
group = 3
subject = 5
type = 4
instructor = 6
room = 7
duration = 8
comment = 9

Calendar configuration

The section [calendar] is there to mention the current year. All dates are automatically computed from week numbers and week days.

[calendar]
year=2014

General

The section [general] allows changing some global options, for example:

[general]
atomic_duration=1.5
NbTimeSlotsAM=2
NbTimeSlots=6
NbDays=5
OnePagePerDiv=1

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).

Switch name Description

Command line option

OnePagePerDiv If true, the divisions will be printed out on separate pages. This can be needed when many divisions to avoid a cluttered page.

OnePagePerWeek 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.

ColorPerSubject If true, the automatic cell colors will be set depending on the "subject" field.
Else, it will be set according to the "instructor" field.

option: -i (colors per Instructor)

PrintDayDate If true, each week day will hold its date in table header.

PrintUnknowItem 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.

OutputTimeStamp Set this to true if you wan the output folder to be time stamped, so you can later compare different versions.

Option: -t (Timestamp)

PrintEventType If true, the type of the event will be printed in each schedule cell. Set to false if unneeded.

PrintNoonSepLine Set to false if you don't want a noon separation line.

CopyStyleSheets 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.

Option: -n (No CSS copy)

CommentFormatting Set this to false if you don't want on the schedule page the special markup for events that hold a comment.

Sections

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 codes and names

The sections day_codes and 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.

Time slots codes and names

The sections TS_codes and 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 NbTimeSlots.

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

Including reference volume

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

Internationalization

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).

Command Line Options

The general syntax is:

gensched [options] input_file

For other configuration not accessible through command-line, see Configuration.

Summary:

Option: -h (Help)

Prints a short help message and exits.

Option: -H

Starts the default browser and shows full doc from local files, then exits.

Option: -d (Debug)

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.:

$ gensched -d input_file 2>stderr.txt

Option: -f (deFaults)

Prints the default configuration values (groups code, week days names and codes, unknown information codes, ...) and exits.

Option: -t (Timestamp)

Option: -g <groups_file>

if given, the file provided will be used as groups file. See Describing complex groups and demo4, on page Samples .

Option: -l <language_code>

Option: -n (No CSS copy)

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.

Option: -v

This flag enables the "verbose" mode, giving some more output

Option: -w <week-string>

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.

Some examples:

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"

will succeed.

option: -c (show Course type)

If given, then the course types will not be printed in schedule page table cells.

option: -p <file.ini> (configuration file)

Load file.ini as configuration file instead of the default gensched.ini

option: -i (colors per Instructor)

If used, then the colors in the schedule page will be related to the instructor (default is related to the subject)

option: -y <year>

Overrides the year given in configuration file

Current defaults values

Using command-line with Option: -f (deFaults), here are the default values given by current build:

- Input file fields positions: (starting from 1)
-index week = 1
-index day = 2
-index timeslot = 3
-index group = 4
-index type = 5
-index subject = 6
-index room = 7
-index instructor = 8
-index duration = 9
-index comment = 10
-unknown_subject_code=S???
-unknown_instructor_code=M. X
-unknown_room_code=RRR
-CSV_delim=,
-nb_tokens=10
Section: general:
-atomic_duration=1
-MaxDuration=5
-NbTimeSlots=7
-NbTimeSlotsAM=3
-NbDays=5
-NbCSSColors=22
- OverrideYear=-1
- WeekClString=
- Group type codes: 4
AG-0
CG-1
DG-2
N/A-3
- Event type codes: 2
*OFF-1
*SPE-2
- Week days codes/values:
- M : Monday
- Tu : Tuesday
- W : Wenesday
- Th : Thursday
- F : Friday
- Time slots codes/values:
- M1 : 9AM
- M2 : 10AM
- M3 : 11AM
- A1 : 2PM
- A2 : 3PM
- A3 : 4PM
- A4 : 5PM
- Misc. switches
- OnePagePerDiv: false
- OnePagePerWeek: false
- ColorPerSubject: true
- PrintDayDate: true
- PrintUnknowItem: true
- OutputTimeStamp: true
- PrintEventType: true
- PrintNoonSepLine: true
- CopyStyleSheets: true
- CommentFormatting: true