Metadata-Version: 1.1
Name: exaManagementSystem
Version: 1.1.19
Summary: Manages Series
Home-page: https://github.com/digsim/exaManagementSystem
Author: Andreas Ruppen
Author-email: andreas.ruppen@gmail.com
License: Apache
Description: # Exam Management System
        
        This is a tool to automatically generate exams based on individual problems. For this, individual problems are stored in the `Exercises` folder (configurable, see `exerciseDir` option), each in  separate sub-folders named `exXX` where `XX` are digits.
        
        Exams are defined using `cfg` files, one for each exam. The `cfg` files contains information like which problems to include. Using LaTeX, the system compiles different problems into exam.
        
        ## Installation
        
        ### Requirements
        
        Install LaTeX on you system. Make sure the commands `pdflatex`, `bibtex` and `latexmk` are available on the `$PATH` of your operating system. Furthermore the script sometimes uses either `gs` or `pdftk` (configurable, see `usepdftk` option) to combine several PDF documents.
        
        ### User Installation
        from a terminal launch
        ```
        ruppena@tungdil:~$ sudo pip install exaManagementSystem
        ```
        this will compile and install the project to the Python libraries (eg. `/usr/local/lib/python2.7/dist-packages/Exa_Management_System-1.1-py2.7.egg`). Furthermore it will install a script in `/usr/local/bin/`:
        * exaManagementSystem
        The configuration and logging.conf are copied into `/etc/ExaManagementSystem/` but it is possible to overwrite them either by placing a file with the same name (but prefixed with a dot eg. `.logging.conf`) in the user home directory or a file with the same name in the current working directory.
        
        ### Developer Installation
        from a terminal launch
        ```
        ruppena@tungdil:~$ git clone https://github.com/digsim/exaManagementSystem.git
        ruppena@tungdil:~$ cd exaManagementSystem
        ruppena@tungdil:~$ sudo python setup.py install --record files.txt
        ```
        
        #### Clean Working directory
        
        To clean the working directory
        
            sudo python setup.py clean --all
            sudo rm -rf build/ dist/ Exa_Management_System.egg-info/ files.txt
        
        ### Bash Completion Installation
        
        If your system supports bash-completion, it can be activated to have option completion for this script. The file `exaManagementSystem-completion.bash` is copied during the installation into the folder `/usr/local/etc/bash_completion.d/` make sure this folder is activated as bash-completion folder in your `.bashrc`, `.bash_login` or `.profile`
        
        ```
        if ! shopt -oq posix; then
          if [ -f /usr/local/etc/bash-completion ]; then
            . /usr/local/etc/bash-completion
        fi
        ```
        
        ### Uninstall
        from a terminal launch
        ```
        ruppena@tungdil:~$ sudo pip uninstall exaManagementSystem
        ruppena@tungdil:~$ sudo rm -rf /Library/Python/2.7/site-packages/exaManagementSystem*
        ```
        this will remove the package and any associated artifacts.
        
        ## Utilization
        
        ### Overview
        
        * To get help type following command in the console:
        ```
        ruppena@tungdil:~$ exaManagementSystem --help
        ```
        * To create a new exercise empty structure type:
        ```
        ruppena@tungdil:~$ exaManagementSystem --make-new-problem
        ```
        
        * To build a new exam:
        ```
        ruppena@tungdil:~$ exaManagementSystem --build-exam -e XX
        ```
        where `XX` is the number identifying a `serieXX.cfg` file in the `Series_properties` folder.
        
        * To create all the exams
        ```
        ruppena@tungdil:~$ exaManagementSystem --build-all-exams
        ```
        This compiles all defines series in the `Exam_properties` folder.
        
        * To generate a quick pdf preview for a given problem
        ```
        ruppena@tungdil:~$ exaManagementSystem --preview-problem -p XX
        ```
        where `XX` identifies on of the `exXX` folders of the `Exercises` folder. The PDF is opened with the viewer specified in the `opencmd` option.
        
        * To generate a quick pdf preview for a given problem solution
        ```
        ruppena@tungdil:~$ exaManagementSystem --preview-solution -p XX
        ```
        where `XX` identifies on of the `exXX` folders of the `Exercises` folder. The PDF is opened with the viewer specified in the `opencmd` option.
        
        * To create a single PDF containing all exams and the associated solutions in the defined order.
        ```
        ruppena@tungdil:~$ exaManagementSystem --make-workbook
        ```
        * To create a single PDF containing the collection of all defined problems
        ```
        ruppena@tungdil:~$ exaManagementSystem --make-catalogue
        ```
        
        ### Use-Case discussion
        
        Start by creating a new Exam-Folder
        
            exaManagementSystem --make-new-lecture -l GL
        
        This creates a new folder `GL` containing the necessary structure to start creating exam questions for the lecture `GL`.
        
        Adapt the properties in the `exam.cfg` to your needs.
        
        The first step is to create a new exam question
        
            exaManagementSystem --make-new-problem
        
        This will create the necessary structure and files in the `exerciseDir` folder of the `exam.cfg` file. Fill in the exo-french.tex, exo-german.tex and exo-solution.tex. Repeat this step for all exam quetions you would like to create.
        
        Define a new exam in the `examProperties` (specified in the `exam.cfg` file ) folder. Create a file named `examXXXXXX.cfg`, where XXXXX can be anything, with the following content
        ```
        [Exam]
        titles: Pattern, Théorie, SimJ
        exo-numbers: 23,1,24
        semester: Spring
        percentage: 30,35,25
        date: 9.6.2015 - 14h / PEII --- C120
        ```
        and launch the compliation of the exam with the command
        ```
        exaManagementSystem --build-exam -s XXXXXX
        ```
        the XXXXX corresponding to the XXXXX in the `examXXXXX.cfg` file name.
        
        
        
        ## Exam Definition
        
        By default the properties for an exam are stored in the folder `Exam_properties` (configurable, see `examProperties` option). A typical config file looks like:
        ```
        [Exam]
        titles: Pattern, Théorie, SimJ
        exo-numbers: 23,1,24
        semester: Spring
        percentage: 30,35,25
        date: 9.6.2015 - 14h / PEII --- C120
        ```
        It contains only one section: `Exam` with five keys:
        * The titles key defines the topics of the serie and is a comma separated list. In the final document this will produce an itemize in the serie header.
        * The exo-number defines which exercices are selected for this exam. The number references the last (numbered) part of one exercise folder.
        * The semester will print the according semester on the first page of the exam.
        * The percentage is used for creating the scale to print on the first page of the exam.
        * The date contains the exam date and is also printed on the first page of the exam.
        
        ## Configuration
        
        The general configuration is hold in a file called `exam.cfg`. It contains a bunch of key values which are grouped into 5 sections: `Config`, `Lecture`, `Logo`, `PDF ` and `Language`.
        
        The `Config` sections defines various folders like the one containing the individual exercises, the output directory, whether `pdftk` or `gs` is used for PDF concatenation or whether the generated files are zipped or not.
        
        The `Lecture` folder defines some strings specific for each lecture like its name and the name of the lecturer. It also contains strings for naming the series and the solutions.
        
        The `Logo` part defines the logos which are shown on the left and right of the header.
        
        The `PDF` part contains options used by LaTeX when creating the PDF file.
        
        The `Language` sections contains for each language a key value pair where the key defines the language and the value defines the exam title in the PDF. Additionally, the key is also used as postfix for the corresponding problem description in this language.
        
        Additionally, the generated `exam.cfg` file is fully documented.
        
        ## Exercise Folder Structure
        
        By default the folder containing all exercises is `Exercices` (configurable, see `exoDirName` option). For the system to work, this folder needs to contain a strict hierarchy. It contains several folders, all named "ex" plus a number, eg. `ex1`, `ex2`, ... `ex10` etc. Each of these folders contain only one exercise, its solution plus additional material (which will be zipped) to be distributed together with the series and the solution respectively. The structure is as follows:
        ```
        ~:$ ls -lR Exercices/ex1
        total 0
        drwxr-xr-x  4 ruppena  staff   136B Oct  6  2014 code/
        drwxr-xr-x  3 ruppena  staff   204B May 28 08:07 latex/
        
        Exercices/ex1/code:
        total 0
        drwxr-xr-x  2 ruppena  staff    68B Oct  6  2014 donne/
        drwxr-xr-x  2 ruppena  staff    68B Oct  6  2014 solution/
        
        Exercices/ex1/code/donne:
        
        Exercices/ex1/code/solution:
        
        Exercices/ex1/latex:
        total 32
        -rw-r--r--  1 ruppena  staff   711B May 28 08:07 exo-french.tex
        -rw-r--r--  1 ruppena  staff   774B May 28 08:07 exo-german.tex
        -rw-r--r--  1 ruppena  staff   4.2K May 28 08:07 exo-solution.tex
        drwxr-xr-x  4 ruppena  staff   136B Oct  6  2014 ressources/
        
        Exercices/ex1/latex/ressources:
        total 0
        drwxr-xr-x  2 ruppena  staff    68B Oct  6  2014 code/
        drwxr-xr-x  2 ruppena  staff   170B Oct  6  2014 figures/
        
        Exercices/ex1/latex/ressources/code:
        
        Exercices/ex1/latex/ressources/figures:
        total 792
        -rw-r--r--  1 ruppena  staff   233K Jun  7  2011 decorator_uml.png
        -rw-r--r--  1 ruppena  staff    76K Jun  7  2011 transparent_enclosure1.png
        -rw-r--r--  1 ruppena  staff    78K Jun  7  2011 transparent_enclosure2.png
        ```
        Each problem is made of two folders: `code` containing additional material to be distributed and `latex` containing the latex code to generate the problem.
        
        Additional material to be distributed in zipped form with the problem needs to be placed in a subfolder `code/donnee` whereas distributed material to be distributed with the solution needs to be placed in a subfolder `code/solution`.
        
        The problem latex code is in a file `exo-[language].tex` where `[language]` is one of the defined languages in the `Language` section of the `exam.cfg` file. The solution is written in a file called `exo-sol.tex`.
        
        You can define as many exam languages as you want. Just be sure that for each used language suffix:
        * there is a corresponding entry in the [Language] section of `exam.cfg` configuration
        * there exist a `exam-[language].cls` defining the first page of the exam in the corresponding language.
        Therefore it would be possible to have another file called `exo-english.tex` and a file `exam-english.cls` together with a definition `english: Exam` in the `exam.cfg`. Thus, the script would produce the exam in three languages: german, french and english. The global config file `exam.cfg` decides which languages are produced.  
        
        The layout of the titlepage can be adapted by modifying the `exam-[language].cls` files. Following keys need to be defined:
        * the layout of the points (per exercise / total) can be modified by changing the `\donepoints` variable.
        * `\indications` contains general indications (No books, no smart-phone etc.).
        * `\exampreamble` puts together the `\indications`, `date`, `university/course` header and `\donepoints`.
        * `\studentheader` contains the header where students put their names etc.
        
        
        Resources used for the latex code are stored in a subfolder `resources`. This folder contains two sub-folders; one for `figures` to store images which are included with
        
            \includegraphics[height=7cm]{\includepath/figures/inherit.png}
        
        and one to store listings to be included in the LaTeX code.
        
        Furthermore, it contains a subfolder `code` used to store source code which is later included into the LaTeX source with
        
            \lstinputlisting{\includepath/code_tex/ADT.java}
        
Keywords: students series
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Utilities
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Compilers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
